chrome.downloads

說明

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

權限

downloads

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

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

示例

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

類型

BooleanDelta

屬性

  • 執行中

    布林值 (選用)

  • 返回

    布林值 (選用)

DangerType

檔案

下載的檔案名稱為可疑，

網址

下載的網址是已知的惡意網址。

內容

下載的檔案為惡意檔案。

不常見

下載的網址不是常見的下載網址，因此可能有危險。

主辦方

下載內容來自已知會散佈惡意二進位檔的主機，且可能有危險。

不需要

下載項目可能非必要或不安全。例如變更瀏覽器或電腦設定。

安全

下載作業對使用者的電腦沒有已知的危險。

已接受

使用者已接受危險的下載內容。

列舉

"blockedTooLarge"

DoubleDelta

屬性

  • 執行中

    數字 選填

  • 返回

    數字 選填

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 的變更 (如果有的話)。

  • 網址

    StringDelta 選用

    url 的變更 (如果有的話)。

DownloadItem

屬性

  • byExtensionId

    字串 選用

    啟動此下載作業的擴充功能 ID (如果擴充功能是由擴充功能啟動)。設定後不會變更。

  • byExtensionName

    字串 選用

    啟動此下載的擴充功能的本地化名稱 (如果擴充功能是由擴充功能啟動)。如果擴充功能變更名稱或使用者語言代碼，就可能有所變動。

  • bytesReceived

    號碼

    從主機到目前為止收到的位元組數 (未考慮檔案壓縮)。

  • canResume

    boolean

    如果下載作業正在進行中且暫停，或者下載作業中斷，可從中斷處繼續下載，則為「是」。

  • 危險

    DangerType

    表示此下載內容是否安全或已知為可疑。

  • endTime

    字串 選用

    下載作業的結束時間 (以 ISO 8601 格式表示)。可以直接傳遞至日期建構函式：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 格式完成下載作業的預估時間。可以直接傳遞至日期建構函式：chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • 存在

    boolean

    下載的檔案是否仍然存在。Chrome 不會自動監控檔案移除作業，因此這些資訊可能已過時。呼叫 search()，觸發檔案是否存在檢查。資料存在檢查完成後，如果檔案已遭刪除，就會觸發 onChanged 事件。請注意，search() 不會等待存在狀態檢查完成再傳回結果，因此 search() 的結果可能無法準確反映檔案系統。此外，您也可以視需要呼叫 search()，但系統只會每 10 秒檢查一次檔案是否存在。

  • fileSize

    號碼

    壓縮後整個檔案所含的位元組數，如果不明，則為 -1。

  • filename

    字串

    絕對本機路徑。

  • finalUrl

    字串

    Chrome 54 以上版本

    在所有重新導向後，進行這項下載的絕對網址。

  • id

    號碼

    具有跨瀏覽器工作階段的永久識別碼。

  • 無痕模式

    boolean

    如果下載內容也在記錄中，則為「false」。如果未記錄，則為「true」。

  • 默劇

    字串

    檔案的 MIME 類型。

  • 已暫停

    boolean

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

  • referrer

    字串

    絕對網址。

  • startTime

    字串

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

  • state

    狀態

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

  • totalBytes

    號碼

    整個檔案中的位元組數 (未考慮檔案壓縮) 或 -1 (如果不明)。

  • 網址

    字串

    系統在任何重新導向之前啟動此下載內容的絕對網址。

DownloadOptions

屬性

  • body

    字串 選用

    文章內文。

  • conflictAction

    FilenameConflictAction 選用

    「filename」已存在時要採取的行動。

  • filename

    字串 選用

    與「下載」目錄相關的檔案路徑，內含已下載檔案，可能內含子目錄。絕對路徑、空白路徑以及包含反向參照「..」的路徑都會發生錯誤。onDeterminingFilename 可讓您在檔案的 MIME 類型及確定暫定檔案名稱後提供檔案名稱建議。

  • headers

    HeaderNameValuePair[] 選用

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

  • method

    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 以上版本

    在所有重新導向後，進行這項下載的絕對網址。

  • finalUrlRegex

    字串 選用

    Chrome 54 以上版本

    將結果限制為 finalUrl 符合指定規則運算式的 DownloadItem。

  • id

    數字 選填

    要查詢的 DownloadItem id。

  • 限制

    數字 選填

    傳回相符 DownloadItem 的數量上限。預設值為 1000。如要傳回所有相符的 DownloadItem，請將值設為 0。請參閱 search，瞭解如何逐頁瀏覽結果。

  • 默劇

    字串 選用

    檔案的 MIME 類型。

  • orderBy

    string[] 選填

    如要將搜尋結果排序，請將這個陣列的元素設為 DownloadItem 屬性。舉例來說，設定 orderBy=['startTime'] 時，DownloadItem 會依開始時間遞增排序。如要指定遞減順序，請在前方加上連字號：「-startTime」。

  • 已暫停

    布林值 (選用)

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

  • 項查詢

    string[] 選填

    這個搜尋字詞陣列會將搜尋結果限制在 DownloadItem，其中 filename、url 或 finalUrl 包含所有以破折號「-」開頭的搜尋字詞，且沒有以破折號開頭的搜尋字詞。

  • startTime

    字串 選用

    下載開始的 ISO 8601 格式時間。

  • startedAfter

    字串 選用

    限制在指定 ms 之後 (以 ISO 8601 格式) 開始的 DownloadItem 結果。

  • startedBefore

    字串 選用

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

  • state

    狀態 選填

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

  • totalBytes

    數字 選填

    整個檔案中的位元組數 (未考慮檔案壓縮) 或 -1 (如果不明)。

  • totalBytesGreater

    數字 選填

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

  • totalBytesLess

    數字 選填

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

  • 網址

    字串 選用

    系統在任何重新導向之前啟動此下載內容的絕對網址。

  • urlRegex

    字串 選用

    將結果限制為 url 符合指定規則運算式的 DownloadItem。

FilenameConflictAction

統一

為了避免重複，filename 已變更為在副檔名之前加入計數器。

覆寫

系統會以新檔案覆寫現有檔案。

提示

系統會向使用者顯示檔案選擇器對話方塊。

列舉

FilenameSuggestion

屬性

  • conflictAction

    FilenameConflictAction 選用

    「filename」已存在時要採取的行動。

  • filename

    字串

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

GetFileIconOptions

屬性

  • 大小

     選用

    傳回的圖示大小。圖示將是尺寸為大小 * 像素的正方形。圖示的預設大小為 32x32 像素。支援的尺寸為 16 和 32。指定其他大小時發生錯誤。

HeaderNameValuePair

屬性

  • 名稱

    字串

    HTTP 標頭名稱。

  • 值

    字串

    HTTP 標頭的值。

HttpMethod

列舉

InterruptReason

列舉

"FILE_TRANSIENT_ERROR"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_CERT_PROBLEM"

"SERVER_CONTENT_LENGTH_MISMATCH"

State

in_progress

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

中斷

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

完成

下載成功。

列舉

"in_progress"

StringDelta

屬性

  • 執行中

    字串 選用

  • 返回

    字串 選用

UiOptions

Chrome 105 以上版本

屬性

  • 已啟用

    boolean

    啟用或停用下載使用者介面。

方法

acceptDanger()

Promise 
chrome.downloads.acceptDanger(
  downloadId: number,
  callback?: function,
)

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

參數

  • downloadId

    號碼

    DownloadItem 的 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

cancel()

Promise 
chrome.downloads.cancel(
  downloadId: number,
  callback?: function,
)

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

參數

  • downloadId

    號碼

    要取消的下載 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

download()

Promise 
chrome.downloads.download(
  options: DownloadOptions,
  callback?: function,
)

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

參數

  • 下載的內容和下載方式。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (downloadId: number)=>void

    • downloadId

      號碼

傳回

  • Promise<number>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

erase()

Promise 
chrome.downloads.erase(
  query: DownloadQuery,
  callback?: function,
)

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

參數

  • 項查詢

    DownloadQuery

  • 回呼

    函式選用

    callback 參數如下所示： 

    (erasedIds: number[])=>void

    • erasedIds

      數字 []

傳回

  • Promise<number[]>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getFileIcon()

Promise 
chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
  callback?: function,
)

擷取指定下載的圖示。系統收到 onCreated 事件後，就會顯示新下載的檔案圖示。此函式在下載期間傳回的圖片可能與下載完成後傳回的圖片不同。系統會根據平台查詢基礎作業系統或工具包，藉此擷取圖示。因此，傳回的圖示取決於許多因素，包括下載狀態、平台、已註冊的檔案類型，以及視覺主題。如果系統無法判定檔案圖示，runtime.lastError 就會顯示錯誤訊息。

參數

  • downloadId

    號碼

    下載的 ID。

  • 選項

    GetFileIconOptions 選用

  • 回呼

    函式選用

    callback 參數如下所示： 

    (iconURL?: string)=>void

    • iconURL

      字串 選用

傳回

  • Promise<string|undefined>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

open()

Promise 
chrome.downloads.open(
  downloadId: number,
  callback?: function,
)

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

參數

  • downloadId

    號碼

    已下載檔案的 ID。

  • 回呼

    函式選用

    Chrome 123 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 123 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

pause()

Promise 
chrome.downloads.pause(
  downloadId: number,
  callback?: function,
)

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

參數

  • downloadId

    號碼

    要暫停的下載 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeFile()

Promise 
chrome.downloads.removeFile(
  downloadId: number,
  callback?: function,
)

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

參數

  • downloadId

    號碼

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

resume()

Promise 
chrome.downloads.resume(
  downloadId: number,
  callback?: function,
)

繼續暫停的下載。如果要求已成功下載，且下載作業已恢復正常，否則 runtime.lastError 會包含錯誤訊息。如果未進行下載，要求會失敗。

參數

  • downloadId

    號碼

    要繼續執行的下載 ID，

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

Promise 
chrome.downloads.search(
  query: DownloadQuery,
  callback?: function,
)

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

參數

傳回

  • Promise<DownloadItem[]>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setShelfEnabled()

自 Chrome 117 版起已淘汰的項目
chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

請改用 setUiOptions。

在每個與目前瀏覽器設定檔相關的視窗下方，啟用或停用灰色檔案櫃。只要至少有 1 個擴充功能停用，這個專區就會遭到停用。如果至少有其他擴充功能停用了檔案櫃，則系統會透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限外，您也必須具備 "downloads.shelf" 權限。

參數

  • 已啟用

    boolean

setUiOptions()

Promise Chrome 105 以上版本 
chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
)

針對與目前瀏覽器設定檔相關聯的每個視窗，變更下載使用者介面。只要至少有一個擴充功能將 UiOptions.enabled 設為 false，下載使用者介面就會隱藏。如果將 UiOptions.enabled 設為 true，但至少有一個擴充功能已停用，則系統會透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限外，您也必須具備 "downloads.ui" 權限。

參數

  • 選項

    UiOptions

    將變更封裝至下載使用者介面。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

show()

chrome.downloads.show(
  downloadId: number,
)

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

參數

  • downloadId

    號碼

    已下載檔案的 ID。

showDefaultFolder()

chrome.downloads.showDefaultFolder()

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

活動

onChanged

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

當 bytesReceived 和 estimatedEndTime 以外的任何 DownloadItem 屬性變更時，系統會使用 downloadId 和包含已變更屬性的物件觸發這個事件。

參數

onCreated

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

系統會在開始下載時透過 DownloadItem 物件觸發這個事件。

參數

onDeterminingFilename

chrome.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

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

清除歷史記錄中的下載內容時，使用 downloadId 觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (downloadId: number)=>void

    • downloadId

      號碼