類別：DownloadItem

類別：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 事件
• state 字串 - 可以是 progressing 或 interrupted。

當下載已更新且尚未完成時發出。

state 可以是以下其中之一

• progressing - 下載正在進行中。
• interrupted - 下載已中斷，可以恢復。

事件：'done'

傳回

• event 事件
• state 字串 - 可以是 completed、cancelled 或 interrupted。

當下載處於終止狀態時發出。這包括已完成的下載、已取消的下載 (透過 downloadItem.cancel()) 以及無法恢復的中斷下載。

state 可以是以下其中之一

• completed - 下載已成功完成。
• cancelled - 下載已取消。
• interrupted - 下載已中斷且無法恢復。

實例方法

downloadItem 物件具有以下方法

downloadItem.setSavePath(path)

• path 字串 - 設定下載項目的儲存檔案路徑。

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

恢復已暫停的下載。

注意： 若要啟用可恢復的下載，您下載的伺服器必須支援範圍請求，並提供 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。

注意： 以下方法特別適用於在重新啟動 session 時恢復 cancelled 項目。

downloadItem.getURLChain()

傳回 string[] - 項目的完整 URL 鏈，包括任何重新導向。

downloadItem.getLastModifiedTime()

傳回 string - Last-Modified 標頭值。

downloadItem.getETag()

傳回 string - ETag 標頭值。

downloadItem.getStartTime()

傳回 Double - 下載開始時的 UNIX epoch 時間以來的秒數。

downloadItem.getEndTime()

傳回 Double - 下載結束時的 UNIX epoch 時間以來的秒數。

實例屬性

downloadItem.savePath

一個 string 屬性，決定下載項目的儲存檔案路徑。

該屬性僅在 session 的 will-download 回呼函數中可用。如果使用者沒有透過該屬性設定儲存路徑，Electron 將使用原始程序來決定儲存路徑；這通常會提示儲存對話方塊。