chrome.downloads

說明

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

權限

downloads

如要使用這項 API，必須在擴充功能資訊清單中聲明 "downloads" 權限。

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

範例

您可以在 examples/api/downloads 目錄中，找到使用 chrome.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」

DoubleDelta

屬性

  • 執行中

    號碼 選填

  • 上一個

    號碼 選填

DownloadDelta

屬性

  • canResume

    BooleanDelta optional

    變更的 canResume (如有)。

  • 危險

    StringDelta 選用

    變更的 danger (如有)。

  • endTime

    StringDelta 選用

    變更的 endTime (如有)。

  • 錯誤

    StringDelta 選用

    變更的 error (如有)。

  • 存在

    BooleanDelta optional

    變更的 exists (如有)。

  • fileSize

    DoubleDelta 選用

    變更的 fileSize (如有)。

  • filename

    StringDelta 選用

    變更的 filename (如有)。

  • finalUrl

    StringDelta 選用

    Chrome 54 以上版本

    變更的 finalUrl (如有)。

  • id

    數字

    變更的DownloadItemid。

  • 默劇

    StringDelta 選用

    變更的 mime (如有)。

  • 已暫停

    BooleanDelta optional

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

    下載作業的絕對網址 (經過所有重新導向)。

  • id

    數字

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

  • 無痕

    布林值

    如果這項下載記錄在記錄中，則為 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 允許的標頭。

  • method

    HttpMethod 選用

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

  • saveAs

    布林值 選填

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

  • 網址

    字串

    下載網址。

DownloadQuery

屬性

  • bytesReceived

    號碼 選填

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

  • 危險

    DangerType optional

    表示系統認為這個下載內容安全無虞，還是已知有可疑之處。

  • endTime

    字串 選填

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

  • endedAfter

    字串 選填

    將結果限制為 DownloadItem，這些結果的結束時間必須晚於以 ISO 8601 格式指定的毫秒

  • endedBefore

    字串 選填

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

  • 錯誤

    InterruptReason 選填

    下載作業中斷的原因。

  • 存在

    布林值 選填

    下載的檔案是否存在；

  • fileSize

    號碼 選填

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

  • filename

    字串 選填

    絕對本機路徑。

  • filenameRegex

    字串 選填

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

  • finalUrl

    字串 選填

    Chrome 54 以上版本

    下載作業的絕對網址 (經過所有重新導向)。

  • finalUrlRegex

    字串 選填

    Chrome 54 以上版本

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

  • id

    號碼 選填

    要查詢的 DownloadItem id。

  • 限制

    號碼 選填

    傳回的相符 DownloadItem 數量上限。預設值為 1000。如要傳回所有相符的 DownloadItem，請設為 0。如要逐頁查看結果，請參閱 search。

  • 默劇

    字串 選填

    檔案的 MIME 類型。

  • orderBy

    字串陣列 選用

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

  • 已暫停

    布林值 選填

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

  • 查詢

    字串陣列 選用

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

  • startTime

    字串 選填

    下載開始時間，採用 ISO 8601 格式。

  • startedAfter

    字串 選填

    將結果限制為 DownloadItem，這些結果的開始時間必須晚於以 ISO 8601 格式指定的毫秒。

  • startedBefore

    字串 選填

    將結果限制為 DownloadItem，這些結果的開始時間早於以 ISO 8601 格式指定的毫秒。

  • 州

    州 (選填)

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

  • totalBytes

    號碼 選填

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

  • totalBytesGreater

    號碼 選填

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

  • totalBytesLess

    號碼 選填

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

  • 網址

    字串 選填

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

  • urlRegex

    字串 選填

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

FilenameConflictAction

uniquify

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

覆寫

現有檔案會遭到新檔案覆寫。

提示詞

系統會提示使用者開啟檔案選擇器對話方塊。

列舉

「uniquify」

「overwrite」

「提示」

FilenameSuggestion

屬性

  • conflictAction

    FilenameConflictAction 選用

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

  • filename

    字串

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

GetFileIconOptions

屬性

  • 大小

    號碼 選填

    傳回的圖示大小。圖示為正方形，尺寸為 size * size 像素。圖示的預設大小和最大尺寸為 32x32 像素。系統僅支援 16 和 32。指定任何其他大小都會發生錯誤。

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

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

中斷

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

完成

下載完成。

列舉

「in_progress」

「interrupted」

「complete」

StringDelta

屬性

  • 執行中

    字串 選填

  • 上一個

    字串 選填

UiOptions

Chrome 105 以上版本

屬性

  • 已啟用

    布林值

    啟用或停用下載 UI。

方法

acceptDanger()

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

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

參數

傳回

  • Promise<void>

    Chrome 96 以上版本

cancel()

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

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

參數

  • downloadId

    數字

    要取消的下載作業 ID。

傳回

  • Promise<void>

    Chrome 96 以上版本

download()

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

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

參數

傳回

  • Promise<number>

    Chrome 96 以上版本

erase()

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

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

參數

傳回

  • Promise<number[]>

    Chrome 96 以上版本

getFileIcon()

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

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

參數

傳回

  • Promise<string | undefined>

    Chrome 96 以上版本

open()

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

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

參數

  • downloadId

    數字

    下載檔案的 ID。

傳回

  • Promise<void>

    Chrome 123 以上版本

pause()

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

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

參數

  • downloadId

    數字

    要暫停的下載作業 ID。

傳回

  • Promise<void>

    Chrome 96 以上版本

removeFile()

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

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

參數

  • downloadId

    數字

傳回

  • Promise<void>

    Chrome 96 以上版本

resume()

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

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

參數

  • downloadId

    數字

    要繼續下載的 ID。

傳回

  • Promise<void>

    Chrome 96 以上版本 
chrome.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

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

參數

傳回

setShelfEnabled()

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

請改用 setUiOptions。

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

參數

  • 已啟用

    布林值

setUiOptions()

Chrome 105 以上版本 
chrome.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

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

參數

  • 選項

    UiOptions

    封裝下載 UI 的變更。

傳回

  • Promise<void>

show()

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

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

參數

  • downloadId

    數字

    下載檔案的 ID。

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

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

事件

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

    函式

    callback 參數如下： 

    (downloadId: number) => void

    • downloadId

      數字