Skip to main content

类：DownloadItem

类：DownloadItem​

🌐 Class: DownloadItem

控制从远程来源下载文件。

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

DownloadItem 是一个表示 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}`)
    }
  })
})

实例事件​

🌐 Instance Events

Event: 'updated'​

返回：

🌐 Returns:

  • event 活动
  • state 字符串 - 可以是 progressing 或 interrupted。

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

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

state 可以是以下之一：

🌐 The state can be one of following:

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

Event: 'done'​

返回：

🌐 Returns:

  • event 活动
  • state 字符串 - 可以是 completed、cancelled 或 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 - 下载成功完成。
  • cancelled - 下载已被取消。
  • interrupted - 下载已中断且无法恢复。

实例方法​

🌐 Instance Methods

downloadItem 对象具有以下方法：

🌐 The downloadItem object has the following methods:

downloadItem.setSavePath(path)​

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

该 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 参数相同的属性。

这个 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.

note

要启用可续传下载，你所下载的服务器必须支持范围请求并提供 Last-Modified 和 ETag 头值。否则，resume() 将丢弃之前接收到的字节，并从头开始重新下载。

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

文件名不一定与本地磁盘上实际保存的文件相同。 如果用户在弹出的下载保存对话框中更改了文件名， 保存的实际文件名将会不同。

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.

note

以下方法特别适用于在会话重新启动时恢复 cancelled 项。

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.