跳转到主内容

类：downloadItem

类：downloadItem​

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

ProcessMain

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.getInitiatorOrigin()​

History
Version(s)Changes
None
API ADDED

Returns string - The origin that started the download (for example https://example.com, or null for an opaque origin), or an empty string if the download was not started by web content (for example webContents.downloadURL()). Use this rather than getURL() or the webContents to decide whose download it is: the URL is chosen by the initiator and the webContents is the whole tab.

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将使用默认方式决定保存路径；通常为弹出保存对话框。