browser.downloads

說明

使用 chrome.downloads API，透過程式輔助方式啟動、監控、操控及搜尋下載內容。

權限

downloads

您必須在擴充功能資訊清單中宣告 "downloads" 權限，才能使用這個 API。

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

範例

您可以在 examples/api/downloads 目錄中，找到使用 browser.downloads API 的簡單範例。如需其他範例和查看原始碼的說明，請參閱「範例」。

類型

BooleanDelta

屬性

  • 執行中

    布林值 選填

  • 上一個

    布林值 選填

DangerType

列舉

「file」
下載檔案的名稱可疑。

"url"
下載網址已知為惡意網址。

"content"
下載的檔案已知為惡意檔案。

「uncommon」
下載網址不常有人下載，可能含有危險內容。

「host」
下載內容來自已知會散布惡意二進位檔的主機，可能具有危險性。

「unwanted」
下載項目可能包含垃圾內容或不安全。例如，可能會變更瀏覽器或電腦設定。

「safe」
下載內容不會對使用者的電腦造成已知危害。

「accepted」
使用者已接受危險下載。

"allowlistedByPolicy"
企業相關值。

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

"forceSaveToGdrive"
供 Secure Enterprise Browser 擴充功能使用。必要時，Chrome 會禁止下載到磁碟，並直接將檔案下載到 Google 雲端硬碟。

"forceSaveToOnedrive"
供安全企業瀏覽器擴充功能使用。必要時，Chrome 會禁止下載到磁碟，並直接將檔案下載到 OneDrive。

DoubleDelta

屬性

  • 執行中

    數字 選填

  • 上一個

    數字 選填

DownloadDelta

屬性

  • canResume

    BooleanDelta 選用

    canResume 的變更 (如有)。

  • 危險

    StringDelta 選用

    danger 的變更 (如有)。

  • endTime

    StringDelta 選用

    endTime 的變更 (如有)。

  • 錯誤

    StringDelta 選用

    error 的變更 (如有)。

  • 存在

    BooleanDelta 選用

    exists 的變更 (如有)。

  • fileSize

    DoubleDelta 選填

    fileSize 的變更 (如有)。

  • filename

    StringDelta 選用

    filename 的變更 (如有)。

  • finalUrl

    StringDelta 選用

    Chrome 54+ 瀏覽器。*自 Chrome 148 起

    finalUrl 的變更 (如有)。

  • id

    數字

    DownloadItem 變更的 id。

  • 默劇

    StringDelta 選用

    mime 的變更 (如有)。

  • 已暫停

    BooleanDelta 選用

    paused 的變更 (如有)。

  • startTime

    StringDelta 選用

    startTime 的變更 (如有)。

  • 州

    StringDelta 選用

    state 的變更 (如有)。

  • totalBytes

    DoubleDelta 選填

    totalBytes 的變更 (如有)。

  • 網址

    StringDelta 選用

    url 的變更 (如有)。

DownloadItem

屬性

  • byExtensionId

    字串 選填

    如果下載作業是由擴充功能啟動，則為該擴充功能的 ID。設定後即無法變更。

  • 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 選填

    下載中斷的原因。多種 HTTP 錯誤可能會歸類在以 SERVER_ 開頭的錯誤。網路相關錯誤的開頭為 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 秒最多只會檢查一次檔案是否存在。

  • fileSize

    數字

    解壓縮後整個檔案的位元組數，如果未知則為 -1。

  • filename

    字串

    絕對本機路徑。

  • finalUrl

    字串

    Chrome 54+ 瀏覽器。*自 Chrome 148 起

    經過所有重新導向後，這項下載作業的絕對網址。

  • id

    數字

    在瀏覽器工作階段中持續存在的 ID。

  • incognito

    布林值

    如果這項下載作業記錄在歷史記錄中，則為 False；如果未記錄，則為 True。

  • 默劇

    字串

    檔案的 MIME 類型。

  • 已暫停

    布林值

    如果下載作業已停止從主機讀取資料，但保持連線開啟，則為 True。

  • 參照網址

    字串

    絕對網址。

  • startTime

    字串

    下載開始時間，採用 ISO 8601 格式。可直接傳遞至 Date 建構函式：chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • 州

    狀態

    指出下載作業正在進行、中斷或已完成。

  • totalBytes

    數字

    整個檔案的位元組數 (不考慮檔案壓縮)，如果未知，則為 -1。

  • 網址

    字串

    這項下載作業的絕對網址 (重新導向前)。

DownloadOptions

屬性

  • body

    字串 選填

    貼文內文。

  • conflictAction

    FilenameConflictAction 選用

    如果 filename 已存在，要採取的動作。

  • filename

    字串 選填

    相對於「下載」目錄的檔案路徑，用於包含下載的檔案，可能包含子目錄。絕對路徑、空白路徑和包含反向參照「..」的路徑會導致錯誤。onDeterminingFilename 可在檔案的 MIME 類型和暫定檔案名稱確定後，建議檔案名稱。

  • 標頭

    HeaderNameValuePair[] 選用

    如果網址使用 HTTP[s] 通訊協定，則會隨要求傳送額外的 HTTP 標頭。每個標頭都以字典表示，其中包含 name 鍵和 value 或 binaryValue，僅限 XMLHttpRequest 允許的標頭。

  • 方法

    HttpMethod 選填

    如果網址使用 HTTP[S] 通訊協定，則要使用的 HTTP 方法。

  • saveAs

    布林值 選填

    使用檔案選擇器，讓使用者選取檔案名稱，無論是否已設定或存在 filename。

  • 網址

    字串

    要下載的網址。

DownloadQuery

屬性

  • bytesReceived

    數字 選填

    目前從主機接收的位元組數，不考慮檔案壓縮。

  • 危險

    DangerType 選用

    表示這項下載內容是否安全或可疑。

  • endTime

    字串 選填

    下載結束時間，採用 ISO 8601 格式。

  • endedAfter

    字串 選填

    僅限傳回在指定毫秒後結束的DownloadItem (採用 ISO 8601 格式)

  • endedBefore

    字串 選填

    限制結果，只顯示在指定毫秒前結束的DownloadItem (採用 ISO 8601 格式)。

  • 錯誤

    InterruptReason 選填

    下載作業中斷的原因。

  • 存在

    布林值 選填

    下載的檔案是否存在。

  • fileSize

    數字 選填

    解壓縮後整個檔案的位元組數，如果未知則為 -1。

  • filename

    字串 選填

    絕對本機路徑。

  • filenameRegex

    字串 選填

    限制結果，只顯示 filename 符合指定規則運算式的 DownloadItem。

  • finalUrl

    字串 選填

    Chrome 54+ 瀏覽器。*自 Chrome 148 起

    經過所有重新導向後，這項下載作業的絕對網址。

  • finalUrlRegex

    字串 選填

    Chrome 54+ 瀏覽器。*自 Chrome 148 起

    限制結果，只顯示 finalUrl 符合指定規則運算式的 DownloadItem。

  • id

    數字 選填

    要查詢的 DownloadItem id。

  • 限制

    數字 選填

    傳回的相符 DownloadItem 數量上限。預設值為 1000。如要傳回所有相符的 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

    字串 選填

    將結果限制為在指定毫秒前開始的DownloadItem (採用 ISO 8601 格式)。

  • 州

    State 選填

    指出下載作業正在進行、中斷或已完成。

  • totalBytes

    數字 選填

    整個檔案的位元組數 (不考慮檔案壓縮)，如果未知，則為 -1。

  • totalBytesGreater

    數字 選填

    將結果限制為 totalBytes 大於指定整數的 DownloadItem。

  • totalBytesLess

    數字 選填

    將結果限制為 totalBytes 小於指定整數的 DownloadItem。

  • 網址

    字串 選填

    這項下載作業的絕對網址 (重新導向前)。

  • urlRegex

    字串 選填

    限制結果，只顯示 url 符合指定規則運算式的 DownloadItem。

FilenameConflictAction

uniquify

為避免重複，filename 會變更為在副檔名前加上計數器。

覆寫

新檔案會覆寫現有檔案。

提示詞

系統會顯示檔案選擇器對話方塊。

列舉

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

屬性

  • conflictAction

    FilenameConflictAction 選用

    如果 filename 已存在，要採取的動作。

  • filename

    字串

    DownloadItem 的新目標 DownloadItem.filename，做為使用者預設下載目錄的相對路徑，可能包含子目錄。系統會忽略絕對路徑、空白路徑，以及包含反向參照「..」的路徑。如果有任何擴充功能註冊了 onDeterminingFilename 監聽器，系統會忽略 filename。

GetFileIconOptions

屬性

  • 大小

    數字 選填

    傳回圖示的大小，以密度獨立像素 (DIP) 為單位。必須為 16 或 32 (預設為 32)。在高 DPI 螢幕上，傳回的圖片會依裝置縮放比例係數縮放 (例如，在 2x 螢幕上，大小 32 的圖片會縮放為 64x64 像素)。背景 Service Worker 的呼叫預設為 1 倍。

HeaderNameValuePair

屬性

  • 名稱

    字串

    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

下載作業目前正在接收伺服器傳送的資料。

中斷

發生錯誤，與檔案主機的連線中斷。

complete

下載完成。

列舉

"in_progress"

「interrupted」

"complete"

StringDelta

屬性

  • 執行中

    字串 選填

  • 上一個

    字串 選填

UiOptions

Chrome 105 以上版本 Chrome 148 以上版本為 browser.*

屬性

  • 已啟用

    布林值

    啟用或停用下載 UI。

方法

acceptDanger()

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

提示使用者接受危險下載。只能從可見的結構定義 (分頁、視窗或網頁/瀏覽器動作彈出式視窗) 呼叫。不會自動接受危險的下載內容。如果接受下載，系統會觸發 onChanged 事件，否則不會有任何動作。當所有資料都擷取到暫存檔案，且下載內容不危險或危險已接受時，暫存檔案會重新命名為目標檔案名稱，state 會變更為「complete」，並觸發 onChanged。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在危險提示對話方塊關閉時解析。

cancel()

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

取消下載。執行 callback 時，下載作業已取消、完成、中斷或不存在。

參數

  • downloadId

    數字

    要取消的下載作業 ID。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在取消要求完成時解析。

download()

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

下載網址。如果網址使用 HTTP[S] 通訊協定，要求就會包含目前為主機名稱設定的所有 Cookie。如果同時指定 filename 和 saveAs，系統會顯示「另存新檔」對話方塊，並預先填入指定的 filename。如果下載作業順利開始，系統會使用新 DownloadItem 的 downloadId 呼叫 callback。如果開始下載時發生錯誤，系統會使用 downloadId=undefined 呼叫 callback，且 runtime.lastError 會包含說明字串。我們不保證錯誤字串在不同版本之間能回溯相容。擴充功能不得剖析。

參數

傳回

  • Promise<number>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，並以新 DownloadItem 的 ID 解析。

erase()

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

從記錄中清除相符的DownloadItem，但不刪除下載的檔案。系統會為每個符合 query 的 DownloadItem 觸發 onErased 事件，然後呼叫 callback。

參數

傳回

  • Promise<number[]>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

getFileIcon()

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

擷取指定下載項目的圖示。如果是新下載項目，則必須先決定下載項目的目標檔案名稱 (例如 onChanged 觸發 filename 變更時)，才能使用檔案圖示。如果在決定檔案名稱前嘗試擷取圖示，系統會透過 runtime.lastError 傳回錯誤。下載期間，這個函式傳回的圖片可能與下載完成後傳回的圖片不同。系統會根據平台，查詢基礎作業系統或工具包，擷取圖示。因此，系統傳回的圖示會取決於多項因素，包括下載狀態、平台、註冊的檔案類型和視覺主題。如果無法判斷檔案圖示，runtime.lastError 會包含錯誤訊息。

參數

傳回

  • Promise<string | undefined>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，其解析結果為代表下載內容的圖片網址。

open()

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

如果 DownloadItem 完成，則立即開啟下載的檔案；否則透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限外，這個方法還需要 "downloads.open" 權限。首次開啟項目時，系統會觸發 onChanged 事件。這個方法只能在回應使用者手勢時呼叫。

參數

  • downloadId

    數字

    下載檔案的 ID。

傳回

  • 承諾<void>

    Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

pause()

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

暫停下載。如果要求成功，下載作業會處於暫停狀態。否則 runtime.lastError 會包含錯誤訊息。如果下載作業未進行，要求就會失敗。

參數

  • downloadId

    數字

    要暫停的下載作業 ID。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在暫停要求完成時解析。

removeFile()

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

如果下載的檔案存在且 DownloadItem 已完成，請移除該檔案；否則，請透過 runtime.lastError 傳回錯誤。

參數

  • downloadId

    數字

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

resume()

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

繼續暫停的下載。如果要求成功，下載作業就會繼續進行，不會暫停。否則 runtime.lastError 會包含錯誤訊息。如果下載作業未啟用，要求就會失敗。

參數

  • downloadId

    數字

    要繼續下載的 ID。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在繼續要求完成時解析。

browser.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

找出 DownloadItem。將 query 設為空物件，即可取得所有 DownloadItem。如要取得特定 DownloadItem，請只設定 id 欄位。如要翻閱大量項目，請設定 orderBy: ['-startTime']，將 limit 設為每頁的項目數量，並將 startedAfter 設為最後一頁最後一個項目的 startTime。

參數

傳回

  • Promise<DownloadItem[]>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

setShelfEnabled()

自 Chrome 117 起淘汰
browser.downloads.setShelfEnabled(
  enabled: boolean,
): void

請改用 setUiOptions。

啟用或停用與目前瀏覽器設定檔相關聯的每個視窗底部的灰色工具列。只要有至少一個擴充功能停用工作夾，工作夾就會停用。如果至少有一個其他擴充功能已停用書架，則啟用書架會透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限外，還需要 "downloads.shelf" 權限。

參數

  • 已啟用

    布林值

setUiOptions()

Chrome 105 以上版本 Chrome 148 以上版本為 browser.* 
browser.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

變更與目前瀏覽器設定檔相關聯的所有視窗下載 UI。只要至少有一個擴充功能將 UiOptions.enabled 設為 false，系統就會隱藏下載 UI。如果至少有一個其他擴充功能已停用 UiOptions.enabled，將其設為 true 會透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限外，還需要 "downloads.ui" 權限。

參數

  • 選項

    UiOptions

    封裝下載 UI 的變更。

傳回

  • 承諾<void>

    傳回 Promise，在 UI 更新完成時解析。

show()

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

在檔案管理員中，顯示下載檔案所在的資料夾。

參數

  • downloadId

    數字

    下載檔案的 ID。

showDefaultFolder()

browser.downloads.showDefaultFolder(): void

在檔案管理工具中顯示預設的「下載」資料夾。

事件

onChanged

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

當 DownloadItem 的任何屬性 (bytesReceived 和 estimatedEndTime 除外) 變更時，系統會觸發這個事件，並傳送 downloadId 和包含已變更屬性的物件。

參數

onCreated

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

下載開始時，這個事件會與 DownloadItem 物件一起觸發。

參數

onDeterminingFilename

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

在決定檔案名稱的過程中，擴充功能可以覆寫目標 DownloadItem.filename。每個擴充功能最多只能為這個事件註冊一個監聽器。每個事件監聽器都必須呼叫 suggest 剛好一次，無論是同步或非同步。如果事件監聽器以非同步方式呼叫 suggest，則必須傳回 true。如果事件監聽器未同步呼叫 suggest，也未傳回 true，系統會自動呼叫 suggest。所有事件監聽器都呼叫 suggest 後，DownloadItem 才會完成。監聽器可以呼叫不含任何引數的 suggest，允許下載作業使用 downloadItem.filename 做為檔案名稱，或將 suggestion 物件傳遞至 suggest，覆寫目標檔案名稱。如果有多個擴充功能覆寫檔案名稱，則最後安裝的擴充功能 (其事件監聽器會將 suggestion 物件傳遞至 suggest) 會勝出。為避免混淆，使用者不應安裝可能發生衝突的擴充功能。如果下載作業是由 download 啟動，且在確定 MIME 類型和暫定檔案名稱之前，目標檔案名稱就已確定，請改為將 filename 傳遞至 download。

參數

onErased

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

從記錄中清除下載內容時，會觸發 downloadId。

參數

  • callback

    函式

    callback 參數如下： 

    (downloadId: number) => void

    • downloadId

      數字