Skip to main content

Class: DownloadItem

Class: DownloadItem​

Control file downloads from remote sources.控制从远程源下载的文件。

Process:进程：Main
This class is not exported from the 'electron' module. 此类不是从'electron'模块导出的。It is only available as a return value of other methods in the Electron API.它只能作为Electron API中其他方法的返回值使用。

DownloadItem is an EventEmitter that represents a download item in Electron. 是一个EventEmitter，表示Electron中的下载项。It is used in will-download event of Session class, and allows users to control the download item.它用于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 Event
  • state string - Can be progressing or interrupted.可以是progressing或interrupted。

Emitted when the download has been updated and is not done.在下载已更新但尚未完成时发出。

The state can be one of following:state可以是以下状态之一：

  • progressing - The download is in-progress.下载正在进行中。
  • interrupted - The download has interrupted and can be resumed.下载已中断，可以继续。

Event: 'done'​

Returns:返回：

  • event Event
  • state string - Can be completed, cancelled or interrupted.可以是completed、cancelled或interrupted。

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.这包括已完成的下载、已取消的下载（通过downloadItem.cancel()）和无法恢复的中断下载。

The state can be one of following:state可以是以下值之一：

  • completed - The download completed successfully.下载成功完成。
  • cancelled - The download has been cancelled.下载已被取消。
  • interrupted - The download has interrupted and can not resume.下载已中断，无法继续。

Instance Methods实例方法​

The downloadItem object has the following methods:downloadItem对象具有以下方法：

downloadItem.setSavePath(path)​

  • path string - Set the save file path of the download item.设置下载项目的保存文件路径。

The API is only available in session's will-download callback function. API仅在会话的will-download回调函数中可用。If path doesn't exist, Electron will try to make the directory recursively. 如果path不存在，Electron将尝试递归生成目录。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.如果用户没有通过API设置保存路径，Electron将使用原始例程来确定保存路径；这通常会提示一个保存对话框。

downloadItem.getSavePath()​

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.setSavePath(path)设置的路径，或者是从显示的保存对话框中选择的路径。

downloadItem.setSaveDialogOptions(options)​

  • options SaveDialogOptions - Set the save file dialog options. 设置保存文件对话框选项。This object has the same properties as the options parameter of dialog.showSaveDialog().此对象与dialog.showSaveDialog()的options参数具有相同的属性。

This API allows the user to set custom options for the save dialog that opens for the download item by default. 此API允许用户为默认情况下为下载项目打开的保存对话框设置自定义选项。The API is only available in session's will-download callback function.API仅在会话的will-download回调函数中可用。

downloadItem.getSaveDialogOptions()​

Returns返回SaveDialogOptions - Returns the object previously set by downloadItem.setSaveDialogOptions(options).返回以前由downloadItem.setSaveDialogOptions(options)设置的对象。

downloadItem.pause()​

Pauses the download.暂停下载。

downloadItem.isPaused()​

Returns返回boolean - Whether the download is paused.是否暂停下载。

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. 要启用可恢复的下载，您正在下载的服务器必须支持范围请求，并提供Last-Modified和ETag标头值。Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.否则，resume()将忽略以前接收到的字节，并从头开始重新启动下载。

downloadItem.canResume()​

Returns返回boolean - Whether the download can resume.是否可以继续下载。

downloadItem.cancel()​

Cancels the download operation.取消下载操作。

downloadItem.getURL()​

Returns返回string - The origin URL where the item is downloaded from.从中下载项目的原始URL。

downloadItem.getMimeType()​

Returns返回string - The files mime type.文件mime类型。

downloadItem.hasUserGesture()​

Returns返回boolean - Whether the download has user gesture.下载是否有用户手势。

downloadItem.getFilename()​

Returns返回string - The file name of the download item.下载项目的文件名。

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

Returns返回Integer - The total size in bytes of the download item.下载项目的总大小（以字节为单位）。

If the size is unknown, it returns 0.如果大小未知，则返回0。

downloadItem.getReceivedBytes()​

Returns返回Integer - The received bytes of the download item.接收到的下载项目的字节数。

downloadItem.getContentDisposition()​

Returns返回string - The Content-Disposition field from the response header.响应标头中的“内容处置”字段。

downloadItem.getState()​

Returns返回string - The current state. 当前状态。Can be progressing, completed, cancelled or interrupted.可以是progressing、completed、cancelled或interrupted。

Note: The following methods are useful specifically to resume a cancelled item when session is restarted.以下方法特别适用于在会话重新启动时恢复cancelled项目。

downloadItem.getURLChain()​

Returns返回string[] - The complete URL chain of the item including any redirects.项目的完整URL链，包括任何重定向。

downloadItem.getLastModifiedTime()​

Returns返回string - Last-Modified header value.上次修改的标头值。

downloadItem.getETag()​

Returns返回string - ETag header value.ETag标头值。

downloadItem.getStartTime()​

Returns返回Double - Number of seconds since the UNIX epoch when the download was started.自UNIX epoch开始下载以来的秒数。

Instance Properties实例属性​

downloadItem.savePath​

A string property that determines the save file path of the download item.一个string属性，用于确定下载项的保存文件路径。

The property is only available in session's will-download callback function. 该属性仅在会话的will-download回调函数中可用。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.如果用户没有通过属性设置保存路径，Electron将使用原始例程来确定保存路径；这通常会提示一个保存对话框。