2016-11-15 00:14:19 +00:00
|
|
|
## Class: DownloadItem
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-04-22 17:30:49 +00:00
|
|
|
> Control file downloads from remote sources.
|
2016-04-21 22:35:29 +00:00
|
|
|
|
2016-11-03 17:26:00 +00:00
|
|
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
|
|
|
2016-06-09 11:32:37 +00:00
|
|
|
`DownloadItem` is an `EventEmitter` that represents a download item in Electron.
|
|
|
|
It is used in `will-download` event of `Session` class, and allows users to
|
2015-09-20 11:08:31 +00:00
|
|
|
control the download item.
|
|
|
|
|
|
|
|
```javascript
|
2015-09-24 07:55:45 +00:00
|
|
|
// In the main process.
|
2016-07-26 01:39:25 +00:00
|
|
|
const {BrowserWindow} = require('electron')
|
|
|
|
let win = new BrowserWindow()
|
2016-05-04 17:59:02 +00:00
|
|
|
win.webContents.session.on('will-download', (event, item, webContents) => {
|
2015-09-24 07:55:45 +00:00
|
|
|
// Set the save path, making Electron not to prompt a save dialog.
|
2016-06-09 11:32:37 +00:00
|
|
|
item.setSavePath('/tmp/save.pdf')
|
|
|
|
|
|
|
|
item.on('updated', (event, state) => {
|
2016-06-09 11:57:29 +00:00
|
|
|
if (state === 'interrupted') {
|
|
|
|
console.log('Download is interrupted but can be resumed')
|
|
|
|
} else if (state === 'progressing') {
|
|
|
|
if (item.isPaused()) {
|
|
|
|
console.log('Download is paused')
|
|
|
|
} else {
|
|
|
|
console.log(`Received bytes: ${item.getReceivedBytes()}`)
|
|
|
|
}
|
2016-06-09 11:32:37 +00:00
|
|
|
}
|
|
|
|
})
|
2016-06-09 11:57:29 +00:00
|
|
|
item.once('done', (event, state) => {
|
2016-05-10 09:42:11 +00:00
|
|
|
if (state === 'completed') {
|
2016-06-09 11:32:37 +00:00
|
|
|
console.log('Download successfully')
|
2015-09-20 11:08:31 +00:00
|
|
|
} else {
|
2016-06-09 11:32:37 +00:00
|
|
|
console.log(`Download failed: ${state}`)
|
2015-09-20 11:08:31 +00:00
|
|
|
}
|
2016-06-09 11:32:37 +00:00
|
|
|
})
|
|
|
|
})
|
2015-09-20 11:08:31 +00:00
|
|
|
```
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
### Instance Events
|
|
|
|
|
|
|
|
#### Event: 'updated'
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-06-09 11:32:37 +00:00
|
|
|
Returns:
|
|
|
|
|
|
|
|
* `event` Event
|
|
|
|
* `state` String
|
|
|
|
|
|
|
|
Emitted when the download has been updated and is not done.
|
|
|
|
|
|
|
|
The `state` can be one of following:
|
|
|
|
|
|
|
|
* `progressing` - The download is in-progress.
|
|
|
|
* `interrupted` - The download has interrupted and can be resumed.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### Event: 'done'
|
2015-09-21 05:45:42 +00:00
|
|
|
|
2016-06-09 11:32:37 +00:00
|
|
|
Returns:
|
|
|
|
|
2015-09-21 05:45:42 +00:00
|
|
|
* `event` Event
|
|
|
|
* `state` String
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-06-09 11:32:37 +00:00
|
|
|
Emitted when the download is in a terminal state. This includes a completed
|
2016-11-03 17:26:00 +00:00
|
|
|
download, a cancelled download (via `downloadItem.cancel()`), and interrupted
|
2015-09-20 11:08:31 +00:00
|
|
|
download that can't be resumed.
|
|
|
|
|
2016-06-09 11:32:37 +00:00
|
|
|
The `state` can be one of following:
|
|
|
|
|
|
|
|
* `completed` - The download completed successfully.
|
|
|
|
* `cancelled` - The download has been cancelled.
|
|
|
|
* `interrupted` - The download has interrupted and can not resume.
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
### Instance Methods
|
2015-09-20 11:08:31 +00:00
|
|
|
|
|
|
|
The `downloadItem` object has the following methods:
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.setSavePath(path)`
|
2015-09-24 07:55:45 +00:00
|
|
|
|
|
|
|
* `path` String - Set the save file path of the download item.
|
|
|
|
|
|
|
|
The API is only available in session's `will-download` callback function.
|
|
|
|
If user doesn't set the save path via the API, Electron will use the original
|
|
|
|
routine to determine the save path(Usually prompts a save dialog).
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getSavePath()`
|
2016-07-28 00:33:36 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `String` - The save path of the download item. This will be either the path
|
2016-07-28 00:33:36 +00:00
|
|
|
set via `downloadItem.setSavePath(path)` or the path selected from the shown
|
|
|
|
save dialog.
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.pause()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
|
|
|
Pauses the download.
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.isPaused()`
|
2016-06-09 11:51:01 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `Boolean` - Whether the download is paused.
|
2016-06-09 11:51:01 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.resume()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
|
|
|
Resumes the download that has been paused.
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.canResume()`
|
2016-06-09 11:51:01 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Resumes `Boolean` - Whether the download can resume.
|
2016-06-09 11:51:01 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.cancel()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
|
|
|
Cancels the download operation.
|
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getURL()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `String` - The origin url where the item is downloaded from.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getMimeType()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `String` - The files mime type.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.hasUserGesture()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `Boolean` - Whether the download has user gesture.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getFilename()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `String` - The file name of the download item.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2015-09-24 08:31:41 +00:00
|
|
|
**Note:** The file name is not always the same as the actual one saved in local
|
|
|
|
disk. If user changes the file name in a prompted download saving dialog, the
|
|
|
|
actual name of saved file will be different.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getTotalBytes()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `Integer` - The total size in bytes of the download item.
|
|
|
|
|
2015-09-21 05:45:42 +00:00
|
|
|
If the size is unknown, it returns 0.
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getReceivedBytes()`
|
2015-09-20 11:08:31 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `Integer` - The received bytes of the download item.
|
2015-09-21 01:38:38 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getContentDisposition()`
|
2015-09-21 01:38:38 +00:00
|
|
|
|
2016-09-24 23:59:30 +00:00
|
|
|
Returns `String` - The Content-Disposition field from the response
|
2015-09-21 01:38:38 +00:00
|
|
|
header.
|
2016-06-09 11:32:37 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
#### `downloadItem.getState()`
|
2016-06-09 11:32:37 +00:00
|
|
|
|
2016-11-08 05:31:36 +00:00
|
|
|
Returns `String` - The current state. Can be `progressing`, `completed`, `cancelled` or `interrupted`.
|
2016-11-23 08:35:26 +00:00
|
|
|
|
|
|
|
**Note:** The following methods are useful specifically to resume a
|
|
|
|
`cancelled` item when session is restarted.
|
|
|
|
|
|
|
|
#### `downloadItem.getURLChain()`
|
|
|
|
|
|
|
|
Returns `String[]` - The complete url chain of the item including any redirects.
|
|
|
|
|
|
|
|
#### `downloadItem.getLastModifiedTime()`
|
|
|
|
|
|
|
|
Returns `String` - Last-Modified header value.
|
|
|
|
|
|
|
|
#### `downloadItem.getETag()`
|
|
|
|
|
|
|
|
Returns `String` - ETag header value.
|
|
|
|
|
|
|
|
#### `downloadItem.getStartTime()`
|
|
|
|
|
|
|
|
Returns `Double` - Number of seconds since the UNIX epoch when the download was
|
|
|
|
started.
|