类: DownloadItem

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

进程: 主进程
此类不是从 'electron' 模块导出的。它仅在 Electron API 中作为其他方法的返回值提供。

DownloadItem 是 Electron 中的一个 EventEmitter，表示一个下载项。它在 Session 类的 will-download 事件中使用，并允许用户控制下载项。

// 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}`)
    }
  })
})

实例事件

事件: 'updated'

返回值

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

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

state 可以是以下之一

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

事件: 'done'

返回值

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

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

state 可以是以下之一

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

恢复已暂停的下载。

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

`downloadItem.canResume()`

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

`downloadItem.cancel()`

取消下载操作。

`downloadItem.getURL()`

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

`downloadItem.getMimeType()`

返回值 string - 文件的 MIME 类型。

`downloadItem.hasUserGesture()`

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

`downloadItem.getFilename()`

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

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

`downloadItem.getCurrentBytesPerSecond()`

返回值 Integer - 当前下载速度，单位为字节/秒。

`downloadItem.getTotalBytes()`

返回值 Integer - 下载项的总大小，以字节为单位。

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

`downloadItem.getReceivedBytes()`

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

`downloadItem.getPercentComplete()`

返回值 Integer - 下载完成百分比。

`downloadItem.getContentDisposition()`

返回值 string - 来自响应头的 Content-Disposition 字段。

`downloadItem.getState()`

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

注意： 以下方法专门用于在会话重启时恢复 cancelled 项。

`downloadItem.getURLChain()`

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

`downloadItem.getLastModifiedTime()`

返回值 string - Last-Modified 标头值。

`downloadItem.getETag()`

返回值 string - ETag 标头值。

`downloadItem.getStartTime()`

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

`downloadItem.getEndTime()`

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

实例属性

`downloadItem.savePath`

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

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