chrome.downloads

説明

chrome.downloads API を使用すると、プログラムでダウンロードの開始、監視、操作、検索ができます。

権限

downloads

この API を使用するには、拡張機能のマニフェストで "downloads" 権限を宣言する必要があります。

{
  "name": "My extension",
  ...
  "permissions": [
    "downloads"
  ],
}

例

chrome.downloads API の使用例については、examples/api/downloads ディレクトリをご覧ください。その他の例や、ソースコードの表示に関するヘルプについては、サンプルをご覧ください。

型

BooleanDelta

プロパティ

  • 現在

    ブール値（省略可）

  • 前へ

    ブール値（省略可）

DangerType

ファイル

ダウンロードのファイル名が不審です。

URL

ダウンロードの URL が悪意のあるものとして知られている。

コンテンツ

ダウンロードしたファイルは悪意のあるファイルであることが確認されています。

まれ

ダウンロードの URL は一般的にダウンロードされているものではなく、危険を及ぼす可能性があります。

ホスト

ダウンロードは、悪意のあるバイナリを配布していることがわかっているホストから行われたもので、危険である可能性が高い。

不要な

ダウンロードが望ましくないか、安全でない可能性がある。たとえば、ブラウザやパソコンの設定を変更する可能性があります。

安全性

ダウンロードによってユーザーのパソコンに既知の危険が及ぶことはありません。

承認済

ユーザーが危険なダウンロードを承認しました。

列挙型

"file"

"url"

"content"

"uncommon"

"host"

"unwanted"

"safe"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

DoubleDelta

プロパティ

  • 現在

    number 省略可

  • 前へ

    number 省略可

DownloadDelta

プロパティ

  • canResume

    BooleanDelta 省略可

    canResume の変更（ある場合）。

  • 危険

    StringDelta 省略可

    danger の変更（ある場合）。

  • endTime

    StringDelta 省略可

    endTime の変更（ある場合）。

  • エラー

    StringDelta 省略可

    error の変更（ある場合）。

  • 存在しています

    BooleanDelta 省略可

    exists の変更（ある場合）。

  • fileSize

    DoubleDelta 省略可

    fileSize の変更（ある場合）。

  • filename

    StringDelta 省略可

    filename の変更（ある場合）。

  • finalUrl

    StringDelta 省略可

    Chrome 54 以降

    finalUrl の変更（ある場合）。

  • id

    数値

    変更された DownloadItem の id。

  • パントマイム

    StringDelta 省略可

    mime の変更（ある場合）。

  • 一時停止

    BooleanDelta 省略可

    paused の変更（ある場合）。

  • startTime

    StringDelta 省略可

    startTime の変更（ある場合）。

  • state

    StringDelta 省略可

    state の変更（ある場合）。

  • totalBytes

    DoubleDelta 省略可

    totalBytes の変更（ある場合）。

  • URL

    StringDelta 省略可

    url の変更（ある場合）。

DownloadItem

プロパティ

  • byExtensionId

    文字列 省略可

    このダウンロードが拡張機能によって開始された場合、このダウンロードを開始した拡張機能の識別子。一度設定すると変更できません。

  • byExtensionName

    文字列 省略可

    このダウンロードが拡張機能によって開始された場合、このダウンロードを開始した拡張機能のローカライズされた名前。拡張機能の名前が変更された場合や、ユーザーが言語 / 地域を変更した場合は変更される可能性があります。

  • bytesReceived

    数値

    ホストからこれまでに受信したバイト数（ファイルの圧縮は考慮しない）。

  • canResume

    ブール値

    ダウンロードが進行中で一時停止している場合、または中断されていて中断された場所から再開できる場合は true。

  • 危険

    DangerType

    このダウンロードが安全であると考えられるか、不審であるとわかっているかどうかの表示。

  • endTime

    文字列 省略可

    ダウンロードが終了した日時（ISO 8601 形式）。Date コンストラクタに直接渡すことができます: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • エラー

    InterruptReason 省略可

    ダウンロードが中断された理由。SERVER_ で始まるエラーのいずれかに、複数の種類の HTTP エラーがグループ化されることがあります。ネットワーク関連のエラーは NETWORK_ で始まり、ファイル システムへのファイルの書き込みプロセス関連のエラーは FILE_ で始まり、ユーザーが開始した中断は USER_ で始まります。

  • estimatedEndTime

    文字列 省略可

    ダウンロードが完了する推定日時（ISO 8601 形式）。Date コンストラクタに直接渡すことができます: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • 存在しています

    ブール値

    ダウンロードしたファイルがまだ存在するかどうか。Chrome ではファイルの削除が自動的に監視されないため、この情報は最新ではない可能性があります。search() を呼び出して、ファイルの存在チェックをトリガーします。存在チェックが完了し、ファイルが削除されている場合は、onChanged イベントが発行されます。search() は、存在チェックが完了するまで待機してから戻るわけではないため、search() の結果はファイル システムを正確に反映していない可能性があります。また、search() は必要に応じて呼び出すことができますが、10 秒に 1 回より頻繁にファイルの存在を確認することはありません。

  • fileSize

    数値

    解凍後のファイル全体のバイト数。不明な場合は -1。

  • filename

    文字列

    絶対ローカルパス。

  • finalUrl

    文字列

    Chrome 54 以降

    すべてのリダイレクト後の、このダウンロードの元となる絶対 URL。

  • id

    数値

    ブラウザ セッションをまたがって保持される識別子。

  • シークレット

    ブール値

    このダウンロードが履歴に記録されている場合は false、記録されていない場合は true。

  • パントマイム

    文字列

    ファイルの MIME タイプ。

  • 一時停止

    ブール値

    ダウンロードでホストからのデータの読み取りが停止したが、接続は開いたままになっている場合は true。

  • referrer

    文字列

    絶対 URL。

  • startTime

    文字列

    ダウンロードが開始された時刻（ISO 8601 形式）。Date コンストラクタに直接渡すことができます: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • state

    州名

    ダウンロードが進行中か、中断されたか、完了したかを示します。

  • totalBytes

    数値

    ファイル全体のバイト数。ファイル圧縮は考慮されません。不明な場合は -1。

  • URL

    文字列

    リダイレクト前の、このダウンロードが開始された絶対 URL。

DownloadOptions

プロパティ

  • body

    文字列 省略可

    投稿の本文。

  • conflictAction

    FilenameConflictAction 省略可

    filename がすでに存在する場合に実行するアクション。

  • filename

    文字列 省略可

    ダウンロードしたファイルを含むダウンロード ディレクトリの相対ファイルパス。サブディレクトリを含むこともあります。絶対パス、空のパス、バックリファレンス「..」を含むパスはエラーになります。onDeterminingFilename を使用すると、ファイルの MIME タイプと仮のファイル名が決定された後にファイル名を提案できます。

  • headers

    HeaderNameValuePair[] 省略可

    URL が HTTP[s] プロトコルを使用する場合に、リクエストとともに送信する追加の HTTP ヘッダー。各ヘッダーは、XMLHttpRequest で許可されているものに限定された、キー name と value または binaryValue を含むディクショナリとして表されます。

  • method

    HttpMethod 省略可

    URL で HTTP[S] プロトコルを使用する場合に使用する HTTP メソッド。

  • saveAs

    ブール値（省略可）

    ファイル選択ツールを使用して、filename が設定されているか、すでに存在するかに関係なく、ユーザーがファイル名を選択できるようにします。

  • URL

    文字列

    ダウンロードする URL。

DownloadQuery

プロパティ

  • bytesReceived

    number 省略可

    ホストからこれまでに受信したバイト数（ファイルの圧縮は考慮しない）。

  • 危険

    DangerType 省略可

    このダウンロードが安全であると考えられるか、不審であるとわかっているかどうかの表示。

  • endTime

    文字列 省略可

    ダウンロードが終了した日時（ISO 8601 形式）。

  • endedAfter

    文字列 省略可

    結果を、指定された ISO 8601 形式のミリ秒より後に終了した DownloadItem に制限します

  • endedBefore

    文字列 省略可

    結果を、指定された ms（ISO 8601 形式）より前に終了した DownloadItem に制限します。

  • エラー

    InterruptReason 省略可

    ダウンロードが中断された理由。

  • 存在しています

    ブール値（省略可）

    ダウンロードしたファイルが存在するかどうか。

  • fileSize

    number 省略可

    解凍後のファイル全体のバイト数。不明な場合は -1。

  • filename

    文字列 省略可

    絶対ローカルパス。

  • filenameRegex

    文字列 省略可

    結果を、filename が指定された正規表現と一致する DownloadItem に制限します。

  • finalUrl

    文字列 省略可

    Chrome 54 以降

    すべてのリダイレクト後の、このダウンロードの元となる絶対 URL。

  • finalUrlRegex

    文字列 省略可

    Chrome 54 以降

    結果を、finalUrl が指定された正規表現と一致する DownloadItem に制限します。

  • id

    number 省略可

    クエリする DownloadItem の id。

  • limit

    number 省略可

    返される一致する DownloadItem の最大数。デフォルトは 1,000 です。一致するすべての DownloadItem を返すには、0 に設定します。結果をページングする方法については、search をご覧ください。

  • パントマイム

    文字列 省略可

    ファイルの MIME タイプ。

  • orderBy

    string[] 省略可

    この配列の要素を DownloadItem プロパティに設定して、検索結果を並べ替えます。たとえば、orderBy=['startTime'] を設定すると、DownloadItem が開始時刻の昇順で並べ替えられます。降順を指定するには、ハイフンを前に付けます（-startTime）。

  • 一時停止

    ブール値（省略可）

    ダウンロードでホストからのデータの読み取りが停止したが、接続は開いたままになっている場合は true。

  • クエリ

    string[] 省略可

    この検索語句の配列は、filename、url、finalUrl のいずれかに、ダッシュ「-」で始まらないすべての検索語句が含まれ、ダッシュで始まる検索語句は含まれない DownloadItem に結果を制限します。

  • startTime

    文字列 省略可

    ダウンロードが開始された時刻（ISO 8601 形式）。

  • startedAfter

    文字列 省略可

    結果を、指定されたミリ秒以降に開始された DownloadItem に制限します（ISO 8601 形式）。

  • startedBefore

    文字列 省略可

    結果を、ISO 8601 形式で指定されたミリ秒より前に開始された DownloadItem に制限します。

  • state

    State（都道府県） 省略可

    ダウンロードが進行中か、中断されたか、完了したかを示します。

  • totalBytes

    number 省略可

    ファイル全体のバイト数。ファイル圧縮は考慮されません。不明な場合は -1。

  • totalBytesGreater

    number 省略可

    totalBytes が指定された整数より大きい DownloadItem に結果を制限します。

  • totalBytesLess

    number 省略可

    結果を、totalBytes が指定された整数より小さい DownloadItem に制限します。

  • URL

    文字列 省略可

    リダイレクト前の、このダウンロードが開始された絶対 URL。

  • urlRegex

    文字列 省略可

    結果を、url が指定された正規表現と一致する DownloadItem に制限します。

FilenameConflictAction

一意化

重複を避けるため、filename はファイル名の拡張子の前にカウンタを含むように変更されます。

上書き

既存のファイルは新しいファイルで上書きされます。

プロンプト

ファイル選択ツール ダイアログが表示されます。

列挙型

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

プロパティ

  • conflictAction

    FilenameConflictAction 省略可

    filename がすでに存在する場合に実行するアクション。

  • filename

    文字列

    DownloadItem の新しいターゲット DownloadItem.filename。ユーザーのデフォルトのダウンロード ディレクトリからの相対パスで、サブディレクトリを含む可能性があります。絶対パス、空のパス、バックリファレンス「..」を含むパスは無視されます。拡張機能によって登録された onDeterminingFilename リスナーがある場合、filename は無視されます。

GetFileIconOptions

プロパティ

  • サイズ

    number 省略可

    返されるアイコンのサイズ。アイコンは正方形で、サイズは size * size ピクセルになります。アイコンのデフォルトの最大サイズは 32x32 ピクセルです。サポートされているサイズは 16 と 32 のみです。他のサイズを指定するとエラーになります。

HeaderNameValuePair

プロパティ

  • name

    文字列

    HTTP ヘッダーの名前。

  • 値

    文字列

    HTTP ヘッダーの値。

HttpMethod

列挙型

"GET"

"POST"

InterruptReason

列挙型

"FILE_FAILED"

"FILE_ACCESS_DENIED"

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

"FILE_TOO_LARGE"

"FILE_VIRUS_INFECTED"

"FILE_TRANSIENT_ERROR"

"FILE_BLOCKED"

"FILE_SECURITY_CHECK_FAILED"

"FILE_TOO_SHORT"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_FAILED"

"NETWORK_TIMEOUT"

"NETWORK_DISCONNECTED"

"NETWORK_SERVER_DOWN"

"NETWORK_INVALID_REQUEST"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"SERVER_CERT_PROBLEM"

"SERVER_FORBIDDEN"

"SERVER_UNREACHABLE"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

"CRASH"

State

in_progress

ダウンロードは現在、サーバーからデータを受信しています。

中断

エラーが発生し、ファイル ホストとの接続が切断されました。

完了

ダウンロードが正常に完了しました。

列挙型

"in_progress"

"interrupted"

"complete"

StringDelta

プロパティ

  • 現在

    文字列 省略可

  • 前へ

    文字列 省略可

UiOptions

Chrome 105 以降

プロパティ

  • 有効

    ブール値

    ダウンロード UI を有効または無効にします。

メソッド

acceptDanger()

chrome.downloads.acceptDanger(
  downloadId: number,
): Promise<void>

危険なダウンロードを承認するようユーザーに求めます。表示されているコンテキスト（タブ、ウィンドウ、ページ/ブラウザ アクションのポップアップ）からのみ呼び出すことができます。危険なダウンロードを自動的に受け入れません。ダウンロードが承認されると、onChanged イベントが発生します。承認されない場合は何も起こりません。すべてのデータが一時ファイルに取得され、ダウンロードが危険でないか、危険性が受け入れられると、一時ファイルの名前がターゲット ファイル名に変更され、state が「complete」に変更され、onChanged がトリガーされます。

パラメータ

戻り値

  • Promise<void>

    Chrome 96 以降

cancel()

chrome.downloads.cancel(
  downloadId: number,
): Promise<void>

ダウンロードをキャンセルします。callback が実行されると、ダウンロードはキャンセル、完了、中断されるか、存在しなくなります。

パラメータ

  • downloadId

    数値

    キャンセルするダウンロードの ID。

戻り値

  • Promise<void>

    Chrome 96 以降

download()

chrome.downloads.download(
  options: DownloadOptions,
): Promise<number>

URL をダウンロードします。URL で HTTP[S] プロトコルが使用されている場合、リクエストには、そのホスト名に現在設定されているすべての Cookie が含まれます。filename と saveAs の両方が指定されている場合は、[名前を付けて保存] ダイアログが表示され、指定された filename が事前に入力されます。ダウンロードが正常に開始されると、新しい DownloadItem の downloadId を使用して callback が呼び出されます。ダウンロードの開始中にエラーが発生した場合は、callback が downloadId=undefined で呼び出され、runtime.lastError に説明文字列が含まれます。エラー文字列は、リリース間で下位互換性が維持されるとは限りません。拡張機能はこれを解析してはなりません。

パラメータ

  • オプション

    DownloadOptions

    ダウンロードする内容と方法。

戻り値

  • Promise<number>

    Chrome 96 以降

erase()

chrome.downloads.erase(
  query: DownloadQuery,
): Promise<number[]>

ダウンロードしたファイルを削除せずに、履歴から一致する DownloadItem を消去します。query に一致する DownloadItem ごとに onErased イベントがトリガーされ、callback が呼び出されます。

パラメータ

戻り値

  • Promise<number[]>

    Chrome 96 以降

getFileIcon()

chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
): Promise<string | undefined>

指定されたダウンロードのアイコンを取得します。新しいダウンロードの場合、ファイル アイコンは onCreated イベントを受信した後に利用できます。ダウンロード中にこの関数から返される画像は、ダウンロード完了後に返される画像と異なる場合があります。アイコンの取得は、プラットフォームに応じて、基盤となるオペレーティング システムまたはツールキットをクエリすることで行われます。そのため、返されるアイコンは、ダウンロードの状態、プラットフォーム、登録されたファイル形式、ビジュアル テーマなど、さまざまな要因によって異なります。ファイル アイコンを特定できない場合、runtime.lastError にはエラー メッセージが含まれます。

パラメータ

  • downloadId

    数値

    ダウンロードの識別子。

  • オプション

    GetFileIconOptions 省略可

戻り値

  • Promise<string | undefined>

    Chrome 96 以降

open()

chrome.downloads.open(
  downloadId: number,
): Promise<void>

DownloadItem が完了している場合は、ダウンロードしたファイルをすぐに開きます。それ以外の場合は、runtime.lastError を介してエラーを返します。このメソッドには、"downloads" 権限に加えて "downloads.open" 権限が必要です。アイテムが初めて開かれると、onChanged イベントが発火します。このメソッドは、ユーザー操作への応答でのみ呼び出すことができます。

パラメータ

  • downloadId

    数値

    ダウンロードしたファイルの識別子。

戻り値

  • Promise<void>

    Chrome 123 以降

pause()

chrome.downloads.pause(
  downloadId: number,
): Promise<void>

ダウンロードを一時停止します。リクエストが成功すると、ダウンロードは一時停止状態になります。それ以外の場合、runtime.lastError にはエラー メッセージが含まれます。ダウンロードがアクティブでない場合、リクエストは失敗します。

パラメータ

  • downloadId

    数値

    一時停止するダウンロードの ID。

戻り値

  • Promise<void>

    Chrome 96 以降

removeFile()

chrome.downloads.removeFile(
  downloadId: number,
): Promise<void>

ダウンロードしたファイルが存在し、DownloadItem が完了している場合は、そのファイルを削除します。それ以外の場合は、runtime.lastError を介してエラーを返します。

パラメータ

  • downloadId

    数値

戻り値

  • Promise<void>

    Chrome 96 以降

resume()

chrome.downloads.resume(
  downloadId: number,
): Promise<void>

一時停止したダウンロードを再開します。リクエストが成功した場合、ダウンロードは進行中で一時停止されていません。それ以外の場合、runtime.lastError にはエラー メッセージが含まれます。ダウンロードがアクティブでない場合、リクエストは失敗します。

パラメータ

  • downloadId

    数値

    再開するダウンロードの ID。

戻り値

  • Promise<void>

    Chrome 96 以降 
chrome.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

DownloadItem を見つけます。query を空のオブジェクトに設定して、すべての DownloadItem を取得します。特定の DownloadItem を取得するには、id フィールドのみを設定します。多数のアイテムをページングするには、orderBy: ['-startTime'] を設定し、limit をページあたりのアイテム数に設定し、startedAfter を最後のページの最後のアイテムの startTime に設定します。

パラメータ

戻り値

setShelfEnabled()

Chrome 117 以降で非推奨
chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

代わりに setUiOptions を使用してください。

現在のブラウザ プロファイルに関連付けられているすべてのウィンドウの下部にあるグレーのシェルフを有効または無効にします。少なくとも 1 つの拡張機能で無効になっている限り、シェルフは無効になります。他の拡張機能がシェルフを無効にしているときにシェルフを有効にすると、runtime.lastError を通じてエラーが返されます。"downloads" 権限に加えて、"downloads.shelf" 権限が必要です。

パラメータ

  • 有効

    ブール値

setUiOptions()

Chrome 105 以降 
chrome.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

現在のブラウザ プロファイルに関連付けられているすべてのウィンドウのダウンロード UI を変更します。少なくとも 1 つの拡張機能で UiOptions.enabled が false に設定されている限り、ダウンロード UI は非表示になります。他の拡張機能の少なくとも 1 つが UiOptions.enabled を無効にしているときに、UiOptions.enabled を true に設定すると、runtime.lastError を通じてエラーが返されます。"downloads" 権限に加えて、"downloads.ui" 権限が必要です。

パラメータ

  • オプション

    UiOptions

    ダウンロード UI の変更をカプセル化します。

戻り値

  • Promise<void>

show()

chrome.downloads.show(
  downloadId: number,
): void

ダウンロードしたファイルをファイル マネージャーのフォルダに表示します。

パラメータ

  • downloadId

    数値

    ダウンロードしたファイルの識別子。

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

ファイル マネージャーでデフォルトのダウンロード フォルダを表示します。

イベント

onChanged

chrome.downloads.onChanged.addListener(
  callback: function,
)

bytesReceived と estimatedEndTime 以外の DownloadItem のプロパティが変更されると、このイベントは downloadId と、変更されたプロパティを含むオブジェクトとともに発生します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (downloadDelta: DownloadDelta) => void

onCreated

chrome.downloads.onCreated.addListener(
  callback: function,
)

このイベントは、ダウンロードが開始されると DownloadItem オブジェクトとともに発生します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (downloadItem: DownloadItem) => void

onDeterminingFilename

chrome.downloads.onDeterminingFilename.addListener(
  callback: function,
)

ファイル名決定プロセスでは、拡張機能がターゲット DownloadItem.filename をオーバーライドする機会が与えられます。各拡張機能で、このイベントに登録できるリスナーは 1 つのみです。各リスナーは、同期または非同期で suggest を 1 回だけ呼び出す必要があります。リスナーが suggest を非同期で呼び出す場合は、true を返す必要があります。リスナーが suggest を同期的に呼び出さず、true を返さない場合、suggest は自動的に呼び出されます。すべてのリスナーが suggest を呼び出すまで、DownloadItem は完了しません。リスナーは、引数なしで suggest を呼び出して、ダウンロードでファイル名に downloadItem.filename を使用できるようにするか、suggestion オブジェクトを suggest に渡して、ターゲット ファイル名をオーバーライドできます。複数の拡張機能がファイル名をオーバーライドする場合、リスナーが suggestion オブジェクトを suggest に渡す最後にインストールされた拡張機能が優先されます。どの拡張機能が優先されるかについて混乱が生じないように、競合する可能性のある拡張機能はインストールしないようにしてください。ダウンロードが download によって開始され、MIME タイプと仮のファイル名が決定される前にターゲットのファイル名がわかっている場合は、代わりに filename を download に渡します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (downloadItem: DownloadItem, suggest: function) => void

onErased

chrome.downloads.onErased.addListener(
  callback: function,
)

ダウンロードが履歴から消去されたときに downloadId で発生します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (downloadId: number) => void

    • downloadId

      数値