chrome.downloads

說明

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

權限

downloads

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

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

範例

您可以在 examples/api/downloads 找到 chrome.downloads API 的簡單使用範例。 目錄。如需其他範例及瞭解如何查看原始碼，請參閱「範例」。

類型

BooleanDelta

屬性

  • 執行中

    布林值 選填

  • 上一個

    布林值 選填

DangerType

檔案

下載的檔案名稱很可疑。

網址

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

內容

下載的檔案是惡意檔案。

不常見

一般使用者不常下載下載的網址，可能含有危險內容。

主機

下載來源是已知會散佈惡意二進位檔，且可能有危險性。

不需要

下載項目可能不需要或不安全。例如：變更可能是瀏覽器或電腦的設定變更。

安全

下載的檔案並不會對使用者的電腦造成已知的危險。

已接受

使用者已接受危險的下載項目。

列舉

"asyncScanning"

"asyncLocalPasswordScanning"

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

  • 州

    StringDelta 選用

    state 中的變更 (如果有的話)。

  • totalBytes

    DoubleDelta 選用

    totalBytes 中的變更 (如果有的話)。

  • 網址

    StringDelta 選用

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

DownloadItem

屬性

  • byExtensionId

    string optional

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

  • byExtensionName

    string optional

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

  • bytesReceived

    數字

    至今從主機收到的位元組數，不含檔案壓縮。

  • canResume

    布林值

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

  • 危險

    DangerType

    指出這項下載內容是否安全或已知。

  • endTime

    string optional

    下載結束時間 (採用 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

    string optional

    完成下載的預估時間 (採用 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 以上版本

    這項下載作業的絕對網址 (在所有重新導向之後)。

  • id

    數字

    這個 ID 會在瀏覽器工作階段內永久有效。

  • 無痕模式

    布林值

    如果這項下載內容記錄在歷史記錄中，則為「False」；如未記錄，則為「true」。

  • 默劇

    字串

    檔案的 MIME 類型。

  • 已暫停

    布林值

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

  • 參照網址

    字串

    絕對網址。

  • startTime

    字串

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

  • 州

    狀態

    指出下載中、中斷還是已完成。

  • totalBytes

    數字

    整個檔案中的位元組數，在未考慮檔案壓縮的情況下，如果不明，則為 -1。

  • 網址

    字串

    這項下載作業在任何重新導向前啟動的絕對網址。

DownloadOptions

屬性

  • body

    string optional

    貼文內文。

  • conflictAction

    FilenameConflictAction 選用

    filename 已存在時要採取的動作。

  • filename

    string optional

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

  • 標題

    HeaderNameValuePair[] 選用

    如果網址使用 HTTP[s] 通訊協定，與要求一起傳送的額外 HTTP 標頭。每個標頭都會表示為包含 name 和 value 或 binaryValue 索引鍵的字典，範圍僅限 XMLHttpRequest 允許的索引鍵。

  • method

    HttpMethod 選用

    網址使用 HTTP[S] 通訊協定時要使用的 HTTP 方法。

  • saveAs

    布林值 選填

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

  • 網址

    字串

    要下載的網址。

DownloadQuery

屬性

  • bytesReceived

    編號 選填

    至今從主機收到的位元組數，不含檔案壓縮。

  • 危險

    DangerType 選用

    指出這項下載內容是否安全或已知。

  • endTime

    string optional

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

  • endedAfter

    string optional

    將在指定毫秒後結束 (採用 ISO 8601 格式) 的結果限制為 DownloadItem

  • endedBefore

    string optional

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

  • 錯誤

    InterruptReason 選用

    下載中斷的原因。

  • 存在

    布林值 選填

    下載的檔案是否存在：

  • fileSize

    編號 選填

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

  • filename

    string optional

    絕對本機路徑。

  • filenameRegex

    string optional

    將結果限制為 filename 與指定規則運算式相符的 DownloadItem。

  • finalUrl

    string optional

    Chrome 54 以上版本

    這項下載作業的絕對網址 (在所有重新導向之後)。

  • finalUrlRegex

    string optional

    Chrome 54 以上版本

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

  • id

    編號 選填

    要查詢的 DownloadItem 的 id。

  • 限制

    編號 選填

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

  • 默劇

    string optional

    檔案的 MIME 類型。

  • orderBy

    string[] 選填

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

  • 已暫停

    布林值 選填

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

  • 查詢

    string[] 選填

    這個搜尋字詞陣列將限制為 DownloadItem，其 filename、url 或 finalUrl 包含所有開頭不是破折號「-」的搜尋字詞而且搜尋字詞中並非以破折號開頭

  • startTime

    string optional

    開始下載的時間 (採用 ISO 8601 格式)。

  • startedAfter

    string optional

    將 DownloadItem 的結果限制為在指定毫秒後開始，以 ISO 8601 格式表示。

  • startedBefore

    string optional

    將 DownloadItem 的結果限制為在指定毫秒之前開始，以 ISO 8601 格式表示。

  • 州

    State (州/省) 選填

    指出下載中、中斷還是已完成。

  • totalBytes

    編號 選填

    整個檔案中的位元組數，在未考慮檔案壓縮的情況下，如果不明，則為 -1。

  • totalBytesGreater

    編號 選填

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

  • totalBytesLess

    編號 選填

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

  • 網址

    string optional

    這項下載作業在任何重新導向前啟動的絕對網址。

  • urlRegex

    string optional

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

FilenameConflictAction

統一

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

覆寫

新檔案將會覆寫現有檔案。

提示

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

列舉

FilenameSuggestion

屬性

  • conflictAction

    FilenameConflictAction 選用

    filename 已存在時要採取的動作。

  • filename

    字串

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

GetFileIconOptions

屬性

  • 大小

    編號 選填

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

HeaderNameValuePair

屬性

  • 名稱

    字串

    HTTP 標頭的名稱。

  • 值

    字串

    HTTP 標頭的值。

HttpMethod

列舉

InterruptReason

列舉

State

in_progress

目前正在下載伺服器的資料。

已中斷

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

完成

下載成功。

列舉

StringDelta

屬性

  • 執行中

    string optional

  • 上一個

    string optional

UiOptions

Chrome 105 以上版本

屬性

  • 已啟用

    布林值

    啟用或停用下載 UI。

方法

acceptDanger()

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

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

參數

  • downloadId

    數字

    DownloadItem 的 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

cancel()

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

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

參數

  • downloadId

    數字

    要取消下載的項目 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

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

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

erase()

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

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

參數

  • 查詢

    DownloadQuery

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (erasedIds: number[]) => void

    • erasedIds

      數字 []

傳回

  • Promise<number[]>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getFileIcon()

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

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

參數

  • downloadId

    數字

    下載項目的 ID。

  • 選項

    GetFileIconOptions 選用

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (iconURL?: string) => void

    • iconURL

      string optional

傳回

  • Promise<string |未定義>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

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

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

pause()

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

暫停下載。如果請求成功，目前處於暫停狀態。否則 runtime.lastError 會包含錯誤訊息。如果下載未啟用，要求就會失敗。

參數

  • downloadId

    數字

    要暫停的下載項目 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

removeFile()

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

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

參數

  • downloadId

    數字

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

resume()

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

繼續已暫停的下載。如果請求成功，表示正在進行下載並取消暫停。否則 runtime.lastError 會包含錯誤訊息。如果下載未啟用，要求就會失敗。

參數

  • downloadId

    數字

    要繼續下載的 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

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

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

參數

傳回

  • Promise<DownloadItem[]>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setShelfEnabled()

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

請改用 setUiOptions。

在與目前瀏覽器設定檔相關聯的每個視窗底部，啟用或停用灰色檔案櫃。只要至少有一個擴充功能停用，這個專區就會停用。如果您至少啟用另外一個擴充功能，而啟用檔案櫃，則會透過 runtime.lastError 傳回錯誤。除了 "downloads" 權限以外，需要 "downloads.shelf" 權限。

參數

  • 已啟用

    布林值

setUiOptions()

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

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

參數

  • 選項

    UiOptions

    將變更封裝至下載 UI。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

show()

chrome.downloads.show(
  downloadId: number,
)

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

參數

  • downloadId

    數字

    下載檔案的 ID。

showDefaultFolder()

chrome.downloads.showDefaultFolder()

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

活動

onChanged

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

當 DownloadItem 的任何屬性 (bytesReceived 和 estimatedEndTime 除外) 變更時，系統會透過 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

      數字