下载项

类：DownloadItem¶

控制从远程源下载文件。

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

DownloadItem 是 EventEmitter，表示 Electron 中的一个下载项。 它用于 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 仅在 session 的 will-download 回调函数中可用。 如果 path 不存在，Electron 会尝试递归创建目录。 如果用户未通过该 API 设置保存路径，Electron 将使用原有 例程来确定保存路径；这通常会提示保存对话框。

downloadItem.getSavePath()¶

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

downloadItem.setSaveDialogOptions(options)¶

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

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

downloadItem.getSaveDialogOptions()¶

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

downloadItem.pause()¶

暂停下载。

downloadItem.isPaused()¶

返回 boolean - 下载是否已暂停。

downloadItem.resume()¶

恢复已暂停的下载。

[!NOTE] 为了启用可恢复下载，您正在从中下载的服务器必须支持范围请求，并提供 Last-Modified 和 ETag 标头值。否则 resume() 将丢弃之前接收的字节，并从头开始重新下载。

downloadItem.canResume()¶

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

downloadItem.cancel()¶

取消下载操作。

downloadItem.getURL()¶

返回 string - 下载项的来源 URL。

downloadItem.getMimeType()¶

返回 string - 文件的 MIME 类型。

downloadItem.hasUserGesture()¶

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

downloadItem.getInitiatorOrigin()¶

返回 string - 启动下载的源（例如 https://example.com，或不透明源为 null），如果下载不是由 Web 内容启动的（例如 webContents.downloadURL()），则为空字符串。使用此方法而不是 getURL() 或 webContents 来决定这是谁的下载：URL 由发起者选择，而 webContents 是整个标签页。

downloadItem.getFilename()¶

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

[!NOTE] 文件名并不总是与本地磁盘上实际保存的文件名相同。 如果用户在提示的下载保存对话框中更改文件名，则 实际保存的文件名将有所不同。

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。

[!NOTE] 以下方法特别适用于在 session 重启时恢复 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 属性，用于确定下载项的保存文件路径。

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