メインコンテンツへ飛ぶ

クラス: DownloadItem

クラス: DownloadItem​

リモートソースからのファイルのダウンロードを制御します。

プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。

DownloadItem は EventEmitter を継承しており、Electron でのダウンロードアイテムを表します。これは Session クラスの will-download イベントで使用されており、ユーザーがダウンロードアイテムを制御できるようにします。

// メインプロセス
const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
// 保存パスを設定して、Electronに保存ダイアログを出さないようにします。
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 にできます。

ダウンロードが更新され、まだ未完了であるときに発生します。

state は、次のいずれかになります。

  • progressing - ダウンロードが進行中です。
  • interrupted - ダウンロードが中断されましたが、再開することができます。

イベント: 'done'​

戻り値:

  • event Event
  • state string - completed、cancelled か interrupted にできます。

ダウンロードが終了状態となったときに発生します。これは完了したダウンロード、キャンセルされたダウンロード (downloadItem.cancel() によって) 、再開できる中断されたダウンロードを含みます。

state は、次のいずれかになります。

  • 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 - ファイル保存ダイアログのオプションを設定します。このオブジェクトは options パラメータ(dialog.showSaveDialog()の)と同じプロパティを持ちます。

この API によって、ダウンロードアイテムに対して既定で開かれる保存ダイアログのカスタムオプションをユーザが設定できます。このAPIは、セッションの will-download コールバック関数でのみ利用可能です。

downloadItem.getSaveDialogOptions()​

戻り値 SaveDialogOptions - downloadItem.setSaveDialogOptions(options)によってその前に設定されたオブジェクトを返す。

downloadItem.pause()​

ダウンロードを一時停止します。

downloadItem.isPaused()​

戻り値 boolean - ダウンロードが一時停止しているかどうか。

downloadItem.resume()​

一時停止されたダウンロードを再開します。

[!NOTE] 再開可能なダウンロードを有効にするには、ダウンロードしているサーバーが Range リクエストをサポートしており、Last-Modified と ETag の両方のヘッダの値を提供していなければなりません。そうでなければ、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] ファイル名はローカルディスクに保存したものと常に同じではありません。ユーザーが表示されたダウンロード保存ダイアログでファイル名を変更した場合、保存されたファイルの実際の名前は異なります。

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 のいずれかにできます。

[!NOTE] 以下のメソッドは、セッションが再開されたときに cancelled のアイテムを再開するのに特に有用です。

downloadItem.getURLChain()​

戻り値 string[] - すべてのリダイレクトを含むアイテムの完全な URL チェーン。

downloadItem.getLastModifiedTime()​

戻り値 string - ヘッダーの Last-Modified の値。

downloadItem.getETag()​

戻り値 string - ヘッダーの ETag の値。

downloadItem.getStartTime()​

戻り値 Double - ダウンロードが開始されたUNIXエポックからの秒数。

downloadItem.getEndTime()​

戻り値 Double - ダウンロードが終了した時の UNIX エポックからの秒数。

インスタンスプロパティ​

downloadItem.savePath​

string 型のプロパティです。ダウンロードアイテムを保存するファイルパスを決定します。

このプロパティは、セッションの will-download コールバック関数内でのみ利用可能です。ユーザがこのプロパティを経由して保存先のパスを設定しない場合、Electron は、保存先のパスを決定するために独自のルーチンを使用します。通常は保存ダイアログを表示します。