类：downloadItem

控制来自于远程资源的文件下载。

Process: Main
This class is not exported from the 'electron' module. 它只能作为 Electron API 中其他方法的返回值。

DownloadItem 是一个 EventEmitter 事件触发器，在Electron中代表一个下载项。它用于will-download事件以及Session类，并且允许用户控制下载项目。

// 在主进程中.
const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
  // 无需对话框提示， 直接将文件保存到路径
  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}`)
    }
  })
})

实例事件

事件名: 'updated'

event Event
state string - 可以是 progressing 或 interrupted。

当下载正在执行但还没完成的时候发出。

状态可以是以下之一：

progressing - 下载正在进行中
interrupted - 下载已经中断，可以恢复

事件名: 'done'

event Event
state string - 可以是 completed，cancelled 或 interrupted。

当下载处于终止态时触发。包括下载完成，取消下载 (通过 downloadItem.cancel())，以及无法恢复的中断下载。

状态可以是以下之一：

completed - 下载成功完成
cancelled - 下载已被取消
interrupted - 下载已经中断，无法恢复

实例方法

downloadItem 对象具有以下方法：

`downloadItem.setSavePath(path)`

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

该API仅能在will-download 方法的回调中使用。如果 path 不存在，Electron 将尝试递归创建目录。如果用户没有通过这个API设置保存路径，Electron 将使用默认方式决定保存路径；通常弹出保存对话框。

`downloadItem.getSavePath()`

返回 string - 下载项目的文件保存路径。该值为通过 downloadItem.setSavePath(path) 设置的路径或通过显示的保存对话框选择的路径。

`downloadItem.setSaveDialogOptions(options)`

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

此 API 允许用户为下载项默认打开的保存对话框设置自定义选项。该API仅能在will-download 方法的回调中使用。

`downloadItem.getSaveDialogOptions()`

返回 SaveDialogOptions - 返回之前通过 downloadItem.setSaveDialogOptions(options) 设置的对象。

`downloadItem.pause()`

暂停下载。

`downloadItem.isPaused()`

返回 boolean - 下载是否暂停。

`downloadItem.resume()`

Resumes the download that has been paused.

[!NOTE] To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. 否则，resume() 将关闭以前接收到的字节并从头开始重新开始下载。

`downloadItem.canResume()`

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

`downloadItem.cancel()`

取消下载操作。

`downloadItem.getURL()`

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

`downloadItem.getMimeType()`

返回 string - 文件 MIME 类型。

`downloadItem.hasUserGesture()`

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

`downloadItem.getFilename()`

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

[!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()`

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

`downloadItem.getTotalBytes()`

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

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

`downloadItem.getReceivedBytes()`

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

`downloadItem.getPercentComplete()`

Returns Integer - The download completion in percent.

`downloadItem.getContentDisposition()`

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

`downloadItem.getState()`

返回 string - 当前状态。 Can be progressing, completed, cancelled or interrupted.

[!NOTE] The following methods are useful specifically to resume a cancelled item when session is restarted.

`downloadItem.getURLChain()`

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

`downloadItem.getLastModifiedTime()`

返回 string - 响应头中 Last-Modified 的值。

`downloadItem.getETag()`

Returns string - 响应头中 ETag 的值。

`downloadItem.getStartTime()`

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

`downloadItem.getEndTime()`

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

实例属性

`downloadItem.savePath`

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

该属性仅在会话的 will-download 回调函数中可用。如果用户未通过属性设置保存路径，Electron将使用默认方式决定保存路径；通常为弹出保存对话框。