類別：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 將使用原始常式來決定儲存路徑；這通常會提示儲存對話方塊。