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

    數字

    已變更的 DownloadItemid

  • 默劇

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

  • 危險

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

  • endTime

    string optional

    下載結束時間 (採用 ISO 8601 格式)。可直接傳遞至 Date 建構函式:chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • 錯誤

    下載中斷的原因。多種 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

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

  • filename

    string optional

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

  • 標題

    如果網址使用 HTTP[s] 通訊協定,與要求一起傳送的額外 HTTP 標頭。每個標頭都會表示為包含 namevaluebinaryValue 索引鍵的字典,範圍僅限 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 結果。

  • 錯誤

    下載中斷的原因。

  • 存在

    布林值 選填

    下載的檔案是否存在:

  • fileSize

    編號 選填

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

  • filename

    string optional

    絕對本機路徑。

  • filenameRegex

    string optional

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

  • finalUrl

    string optional

    Chrome 54 以上版本

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

  • finalUrlRegex

    string optional

    Chrome 54 以上版本

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

  • id

    編號 選填

    要查詢的 DownloadItemid

  • 限制

    編號 選填

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

  • 默劇

    string optional

    檔案的 MIME 類型。

  • orderBy

    string[] 選填

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

  • 已暫停

    布林值 選填

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

  • 查詢

    string[] 選填

    這個搜尋字詞陣列會將以下字詞限制在 DownloadItem,其 filenameurlfinalUrl 包含所有開頭不是破折號「-」的搜尋字詞而且搜尋字詞中並非以破折號開頭

  • startTime

    string optional

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

  • startedAfter

    string optional

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

  • startedBefore

    string optional

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

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

  • totalBytes

    編號 選填

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

  • totalBytesGreater

    編號 選填

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

  • totalBytesLess

    編號 選填

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

  • 網址

    string optional

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

  • urlRegex

    string optional

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

FilenameConflictAction

統一

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

覆寫

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

提示

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

列舉

"統一"

"覆寫"

"提示"

FilenameSuggestion

屬性

  • conflictAction

    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。如果同時指定 filenamesaveAs,系統會顯示「Save As」對話方塊,並預先填入指定的 filename。如果成功開始下載,系統就會使用新 DownloadItemdownloadId 呼叫 callback。如果開始下載時發生錯誤,系統會使用 downloadId=undefined 呼叫 callbackruntime.lastError 則會包含描述性字串。錯誤字串不保證會在各版本之間保有回溯相容性。擴充功能不得剖析。

參數

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

  • 回呼

    函式 選用

    callback 參數如下所示:

    (downloadId: number) => void

    • downloadId

      數字

傳回

  • Promise&lt;number&gt;

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。

erase()

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

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

參數

  • 查詢
  • 回呼

    函式 選用

    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。

  • 選項
  • 回呼

    函式 選用

    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 及以上版本,其他平台需要使用回呼。

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

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

參數

傳回

  • Promise&lt;DownloadItem[]&gt;

    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" 權限。

參數

  • 選項

    將變更封裝至下載 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 的任何屬性 (bytesReceivedestimatedEndTime 除外) 變更時,系統會透過 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

      數字