本頁面由 Cloud Translation API 翻譯而成。

chrome.downloads

說明

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

權限

downloads

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

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

範例

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

類型

BooleanDelta

屬性

執行中

布林值選填
上一個

布林值選填

DangerType

檔案

下載的檔案名稱很可疑。

網址

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

內容

下載的檔案是惡意檔案。

不常見

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

主機

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

不需要

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

安全

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

已接受

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

列舉

「檔案」

"url"

"內容"

"uncommon"

"主機"

「unwanted」

"安全"

「已接受」

"allowlistedByPolicy"

「asyncScanning」

「asyncLocalPasswordScanning」

「passwordProtected」

"blockedTooLarge"

"sensitiveContentWarning" (敏感內容警告)

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

「deepScannedOpened 危險」

"promptForScanning"

"promptForLocalPasswordScanning"

"帳戶入侵"

"blockedScanFailed"

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

列舉

「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」

「當機」

State

in_progress

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

已中斷

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

完成

下載成功。

列舉

"in_progress"

"已中斷"

"complete"

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
```

傳回

承諾<void>

Chrome 96 以上版本

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

cancel()

Promise

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

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

參數

downloadId

數字

要取消下載的項目 ID。
回呼

函式選用

callback 參數如下所示：
```
() => void
```

傳回

承諾<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 則會包含描述性字串。錯誤字串不保證會在各版本之間保有回溯相容性。擴充功能不得剖析。

參數

選項

DownloadOptions

下載的內容及下載方式。
回呼

函式選用

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
  
  數字 []

傳回

承諾<數字 []>

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<字串 |未定義>

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
```

傳回

承諾<void>

Chrome 123 以上版本

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

pause()

Promise

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

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

參數

downloadId

數字

要暫停的下載項目 ID。
回呼

函式選用

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 96 以上版本

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

removeFile()

Promise

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

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

參數

downloadId

數字
回呼

函式選用

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 96 以上版本

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

resume()

Promise

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

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

參數

downloadId

數字

要繼續下載的 ID。
回呼

函式選用

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 96 以上版本

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

search()

Promise

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

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

參數

查詢

DownloadQuery
回呼

函式選用

callback 參數如下所示：
```
(results: DownloadItem[]) => void
```
- 結果
  
  DownloadItem[]

傳回

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
```

傳回

承諾<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 和包含已變更屬性的物件觸發這個事件。

參數

回呼

函式

callback 參數如下所示：
```
(downloadDelta: DownloadDelta) => void
```
- downloadDelta
  
  DownloadDelta

onCreated

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

下載作業開始時，這個事件會使用 DownloadItem 物件觸發。

參數

回呼

函式

callback 參數如下所示：
```
(downloadItem: DownloadItem) => void
```
- downloadItem
  
  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。

參數

回呼

函式

callback 參數如下所示：
```
(downloadItem: DownloadItem, suggest: function) => void
```
- downloadItem
  
  DownloadItem
- suggest
  
  函式
  
  suggest 參數如下所示：
```
(suggestion?: FilenameSuggestion) => void
```
  - 建議
    
    FilenameSuggestion (選用)

onErased

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

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

參數

回呼

函式

callback 參數如下所示：
```
(downloadId: number) => void
```
- downloadId
  
  數字