mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Update DownloadItem for getState

Browse source
This commit is contained in:
Cheng Zhao 2016-06-09 20:32:37 +09:00
parent 0321e23c7a
commit 3f1dba3016
1 changed files with 50 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
docs/api/download-item.md
View file

@ -2,49 +2,66 @@
> Control file downloads from remote sources.
`DownloadItem` is an EventEmitter that represents a download item in Electron.
It is used in `will-download` event of `Session` module, and allows users to
`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
control the download item.
```javascript
// In the main process.
win.webContents.session.on('will-download', (event, item, webContents) => {
// Set the save path, making Electron not to prompt a save dialog.
item.setSavePath('/tmp/save.pdf');
console.log(item.getMimeType());
console.log(item.getFilename());
console.log(item.getTotalBytes());
item.on('updated', () => {
console.log('Received bytes: ' + item.getReceivedBytes());
});
item.on('done', (e, state) => {
if (state === 'completed') {
console.log('Download successfully');
item.setSavePath('/tmp/save.pdf')
item.on('updated', (event, state) => {
if (state === 'progressing') {
console.log(`Received bytes: ${item.getReceivedBytes()}`)
} else {
console.log('Download is cancelled or interrupted that can\'t be resumed');
console.log('Download stopped')
}
});
});
})
item.on('done', (event, state) => {
if (state === 'completed') {
console.log('Download successfully')
} else {
console.log(`Download failed: ${state}`)
}
})
})
```
## Events
### Event: 'updated'
Emits when the `downloadItem` gets updated.
### Event: 'done'
Returns:
* `event` Event
* `state` String
* `completed` - The download completed successfully.
* `cancelled` - The download has been cancelled.
* `interrupted` - An error broke the connection with the file server.
Emits when the download is in a terminal state. This includes a completed
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.
### Event: 'done'
Returns:
* `event` Event
* `state` String
Emitted when the download is in a terminal state. This includes a completed
download, a cancelled download(via `downloadItem.cancel()`), and interrupted
download that can't be resumed.
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.
## Methods
The `downloadItem` object has the following methods:
@ -102,3 +119,14 @@ Returns a `Integer` represents the received bytes of the download item.
Returns a `String` represents the Content-Disposition field from the response
header.
### `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.