electron/docs/api/download-item.md

141 lines
3.5 KiB
Markdown
Raw Normal View History

2015-09-20 11:08:31 +00:00
# DownloadItem
2016-04-22 17:30:49 +00:00
> Control file downloads from remote sources.
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.
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) => {
if (state === 'progressing') {
console.log(`Received bytes: ${item.getReceivedBytes()}`)
} else {
console.log('Download stopped')
}
})
item.on('done', (event, state) => {
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
```
## Events
### Event: 'updated'
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
### Event: 'done'
2016-06-09 11:32:37 +00:00
Returns:
* `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
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.
2015-09-20 11:08:31 +00:00
## Methods
The `downloadItem` object has the following methods:
2015-09-24 07:55:45 +00:00
### `downloadItem.setSavePath(path)`
* `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).
2015-09-20 11:08:31 +00:00
### `downloadItem.pause()`
Pauses the download.
2016-06-09 11:51:01 +00:00
### `downloadItem.isPaused()`
Returns whether the download is paused.
2015-09-20 11:08:31 +00:00
### `downloadItem.resume()`
Resumes the download that has been paused.
2016-06-09 11:51:01 +00:00
### `downloadItem.canResume()`
Resumes whether the download can resume.
2015-09-20 11:08:31 +00:00
### `downloadItem.cancel()`
Cancels the download operation.
2015-11-13 08:03:40 +00:00
### `downloadItem.getURL()`
2015-09-20 11:08:31 +00:00
Returns a `String` represents the origin url where the item is downloaded from.
### `downloadItem.getMimeType()`
Returns a `String` represents the mime type.
### `downloadItem.hasUserGesture()`
Returns a `Boolean` indicates whether the download has user gesture.
### `downloadItem.getFilename()`
2015-09-20 11:08:31 +00:00
Returns a `String` represents the file name of the download item.
2015-09-20 11:08:31 +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
### `downloadItem.getTotalBytes()`
Returns a `Integer` represents the total size in bytes of the download item.
If the size is unknown, it returns 0.
2015-09-20 11:08:31 +00:00
### `downloadItem.getReceivedBytes()`
Returns a `Integer` represents the received bytes of the download item.
### `downloadItem.getContentDisposition()`
Returns a `String` represents the Content-Disposition field from the response
header.
2016-06-09 11:32:37 +00:00
### `downloadItem.getState()`
Returns current state as `String`.
Possible values are:
* `progressing` - The download is in-progress.
* `completed` - The download completed successfully.
* `cancelled` - The download has been cancelled.
* `interrupted` - The download has interrupted.