类：DownloadItem

¥Class: DownloadItem

控制从远程源下载文件。

¥Control file downloads from remote sources.

进程：主进程
该类不是从 'electron' 模块导出的。它仅可用作 Electron API 中其他方法的返回值。

¥Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.

DownloadItem 是 EventEmitter，代表 Electron 中的下载项。用于 Session 类的 will-download 事件，允许用户控制下载项。

¥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.

// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
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')

  item.on('updated', (event, state) => {
    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()}`)
      }
    }
  })
  item.once('done', (event, state) => {
    if (state === 'completed') {
      console.log('Download successfully')
    } else {
      console.log(`Download failed: ${state}`)
    }
  })
})

实例事件

¥Instance Events

事件：'updated'

¥Event: 'updated'

¥Returns:

event 事件

¥event Event
state 字符串 - 可以是 progressing 或 interrupted。

¥state string - Can be progressing or interrupted.

下载已更新但未完成时发出。

¥Emitted when the download has been updated and is not done.

state 可以是以下之一：

¥The state can be one of following:

progressing - 下载正在进行中。

¥progressing - The download is in-progress.
interrupted - 下载已中断，可以恢复。

¥interrupted - The download has interrupted and can be resumed.

事件：'done'

¥Event: 'done'

¥Returns:

event 事件

¥event Event
state 字符串 - 可以是 completed、cancelled 或 interrupted。

¥state string - Can be completed, cancelled or interrupted.

当下载处于最终状态时发出。这包括已完成的下载、取消的下载（通过 downloadItem.cancel()）以及无法恢复的中断下载。

¥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.

state 可以是以下之一：

¥The state can be one of following:

completed - 下载成功完成。

¥completed - The download completed successfully.
cancelled - 下载已被取消。

¥cancelled - The download has been cancelled.
interrupted - 下载已中断且无法恢复。

¥interrupted - The download has interrupted and can not resume.

实例方法

¥Instance Methods

downloadItem 对象有以下方法：

¥The downloadItem object has the following methods:

`downloadItem.setSavePath(path)`

path 字符串 - 设置下载项目的保存文件路径。

¥path string - Set the save file path of the download item.

该 API 仅在会话的 will-download 回调函数中可用。如果 path 不存在，Electron 将尝试递归创建目录。如果用户没有通过 API 设置保存路径，Electron 将使用原始例程来确定保存路径；这通常会提示保存对话框。

¥The API is only available in session's will-download callback function. If path doesn't exist, Electron will try to make the directory recursively. If user doesn't set the save path via the API, Electron will use the original routine to determine the save path; this usually prompts a save dialog.

`downloadItem.getSavePath()`

返回 string - 下载项目的保存路径。这将是通过 downloadItem.setSavePath(path) 设置的路径或从显示的保存对话框中选择的路径。

¥Returns string - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.

`downloadItem.setSaveDialogOptions(options)`

options SaveDialogOptions - 设置保存文件对话框选项。该对象与 dialog.showSaveDialog() 的 options 参数具有相同的属性。

¥options SaveDialogOptions - Set the save file dialog options. This object has the same properties as the options parameter of dialog.showSaveDialog().

此 API 允许用户为默认情况下为下载项目打开的保存对话框设置自定义选项。该 API 仅在会话的 will-download 回调函数中可用。

¥This API allows the user to set custom options for the save dialog that opens for the download item by default. The API is only available in session's will-download callback function.

`downloadItem.getSaveDialogOptions()`

返回 SaveDialogOptions - 返回先前由 downloadItem.setSaveDialogOptions(options) 设置的对象。

¥Returns SaveDialogOptions - Returns the object previously set by downloadItem.setSaveDialogOptions(options).

`downloadItem.pause()`

暂停下载。

¥Pauses the download.

`downloadItem.isPaused()`

返回 boolean - 下载是否暂停。

¥Returns boolean - Whether the download is paused.

`downloadItem.resume()`

恢复已暂停的下载。

¥Resumes the download that has been paused.

注意：要启用可恢复下载，你下载的服务器必须支持范围请求并提供 Last-Modified 和 ETag 标头值。否则 resume() 将忽略先前接收到的字节并从头开始重新下载。

¥Note: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.

`downloadItem.canResume()`

返回 boolean - 是否可以恢复下载。

¥Returns boolean - Whether the download can resume.

`downloadItem.cancel()`

取消下载操作。

¥Cancels the download operation.

`downloadItem.getURL()`

返回 string - 下载项目的原始 URL。

¥Returns string - The origin URL where the item is downloaded from.

`downloadItem.getMimeType()`

返回 string - 文件 mime 类型。

¥Returns string - The files mime type.

`downloadItem.hasUserGesture()`

返回 boolean - 下载是否有用户手势。

¥Returns boolean - Whether the download has user gesture.

`downloadItem.getFilename()`

返回 string - 下载项目的文件名。

¥Returns string - The file name of the download item.

注意：文件名并不总是与本地磁盘中实际保存的文件名相同。如果用户在提示的下载保存对话框中更改文件名，则保存的文件的实际名称将会不同。

¥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.

`downloadItem.getCurrentBytesPerSecond()`

返回 Integer - 当前下载速度（以字节/秒为单位）。

¥Returns Integer - The current download speed in bytes per second.

`downloadItem.getTotalBytes()`

返回 Integer - 下载项目的总大小（以字节为单位）。

¥Returns Integer - The total size in bytes of the download item.

如果大小未知，则返回 0。

¥If the size is unknown, it returns 0.

`downloadItem.getReceivedBytes()`

返回 Integer - 下载项目的接收字节数。

¥Returns Integer - The received bytes of the download item.

`downloadItem.getPercentComplete()`

返回 Integer - 下载完成度（以百分比为单位）。

¥Returns Integer - The download completion in percent.

`downloadItem.getContentDisposition()`

返回 string - 响应标头中的 Content-Disposition 字段。

¥Returns string - The Content-Disposition field from the response header.

`downloadItem.getState()`

返回 string - 目前的状态。可以是 progressing、completed、cancelled 或 interrupted。

¥Returns string - The current state. Can be progressing, completed, cancelled or interrupted.

注意：以下方法对于在会话重新启动时恢复 cancelled 项目特别有用。

¥Note: The following methods are useful specifically to resume a cancelled item when session is restarted.

`downloadItem.getURLChain()`

返回 string[] - 项目的完整 URL 链，包括任何重定向。

¥Returns string[] - The complete URL chain of the item including any redirects.

`downloadItem.getLastModifiedTime()`

返回 string - Last-Modified 标头值。

¥Returns string - Last-Modified header value.

`downloadItem.getETag()`

返回 string - ETag 标头值。

¥Returns string - ETag header value.

`downloadItem.getStartTime()`

返回 Double - 自开始下载时的 UNIX 纪元以来的秒数。

¥Returns Double - Number of seconds since the UNIX epoch when the download was started.

`downloadItem.getEndTime()`

返回 Double - 自下载结束的 UNIX 纪元以来的秒数。

¥Returns Double - Number of seconds since the UNIX epoch when the download ended.

实例属性

¥Instance Properties

`downloadItem.savePath`

string 属性，确定下载项目的保存文件路径。

¥A string property that determines the save file path of the download item.

该属性仅在会话的 will-download 回调函数中可用。如果用户没有通过属性设置保存路径，Electron 将使用原始例程来确定保存路径；这通常会提示保存对话框。

¥The property is only available in session's will-download callback function. If user doesn't set the save path via the property, Electron will use the original routine to determine the save path; this usually prompts a save dialog.