這項權限會觸發警告
說明
使用 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
如果下載作業正在進行中且暫停,或者下載作業中斷,可從中斷處繼續下載,則為「是」。
-
危險
表示此下載內容是否安全或已知為可疑。
-
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
「
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
「
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
屬性
-
已啟用
boolean
啟用或停用下載使用者介面。
方法
acceptDanger()
chrome.downloads.acceptDanger(
downloadId: number,
callback?: function,
)
提示使用者接受危險的下載項目。只能從可見內容 (分頁、視窗或網頁/瀏覽器動作彈出式視窗) 呼叫。不自動接受危險的下載作業。如果系統接受下載,就會觸發 onChanged
事件,否則不會發生任何變化。將所有資料擷取至暫存檔案,且不危險或接受使用者下載時,暫存檔案會重新命名為目標檔案名稱,state
會變更為「完成」,並觸發 onChanged
。
參數
-
downloadId
號碼
DownloadItem
的 ID。 -
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
cancel()
chrome.downloads.cancel(
downloadId: number,
callback?: function,
)
取消下載。執行 callback
時,下載作業已取消、已完成、中斷或不再存在。
參數
-
downloadId
號碼
要取消的下載 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
download()
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()
chrome.downloads.erase(
query: DownloadQuery,
callback?: function,
)
從記錄中清除相符的 DownloadItem
,但不會刪除已下載的檔案。系統會為每個與 query
相符的 DownloadItem
觸發 onErased
事件,然後呼叫 callback
。
參數
-
項查詢
-
回呼
函式選用
callback
參數如下所示:(erasedIds: number[]) => void
-
erasedIds
數字 []
-
傳回
-
Promise<number[]>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getFileIcon()
chrome.downloads.getFileIcon(
downloadId: number,
options?: GetFileIconOptions,
callback?: function,
)
擷取指定下載的圖示。系統收到 onCreated
事件後,就會顯示新下載的檔案圖示。此函式在下載期間傳回的圖片可能與下載完成後傳回的圖片不同。系統會根據平台查詢基礎作業系統或工具包,藉此擷取圖示。因此,傳回的圖示取決於許多因素,包括下載狀態、平台、已註冊的檔案類型,以及視覺主題。如果系統無法判定檔案圖示,runtime.lastError
就會顯示錯誤訊息。
參數
-
downloadId
號碼
下載的 ID。
-
選項
-
回呼
函式選用
callback
參數如下所示:(iconURL?: string) => void
-
iconURL
字串 選用
-
傳回
-
Promise<string | undefined>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
open()
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()
chrome.downloads.pause(
downloadId: number,
callback?: function,
)
暫停下載。如果要求順利完成下載,就會處於暫停狀態。否則 runtime.lastError
會包含錯誤訊息。如果未進行下載,要求會失敗。
參數
-
downloadId
號碼
要暫停的下載 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
removeFile()
chrome.downloads.removeFile(
downloadId: number,
callback?: function,
)
如果下載的檔案已存在,且 DownloadItem
已完成,請將下載的檔案移除;否則,透過 runtime.lastError
傳回錯誤。
參數
-
downloadId
號碼
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
resume()
chrome.downloads.resume(
downloadId: number,
callback?: function,
)
繼續暫停的下載。如果要求已成功下載,且下載作業已恢復正常,否則 runtime.lastError
會包含錯誤訊息。如果未進行下載,要求會失敗。
參數
-
downloadId
號碼
要繼續執行的下載 ID,
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
search()
chrome.downloads.search(
query: DownloadQuery,
callback?: function,
)
找出 DownloadItem
。將 query
設為空物件,取得所有 DownloadItem
。如要取得特定 DownloadItem
,請只設定 id
欄位。如要將大量項目分頁至頁面,請將 orderBy: ['-startTime']
、將 limit
設為每頁項目數量,並將 startedAfter
設為最後一頁最後一個項目的 startTime
。
參數
-
項查詢
-
回呼
函式選用
callback
參數如下所示:(results: DownloadItem[]) => void
-
結果
-
傳回
-
Promise<DownloadItem[]>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setShelfEnabled()
chrome.downloads.setShelfEnabled(
enabled: boolean,
)
請改用 setUiOptions
。
在每個與目前瀏覽器設定檔相關的視窗下方,啟用或停用灰色檔案櫃。只要至少有 1 個擴充功能停用,這個專區就會遭到停用。如果至少有其他擴充功能停用了檔案櫃,則系統會透過 runtime.lastError
傳回錯誤。除了 "downloads"
權限外,您也必須具備 "downloads.shelf"
權限。
參數
-
已啟用
boolean
setUiOptions()
chrome.downloads.setUiOptions(
options: UiOptions,
callback?: function,
)
針對與目前瀏覽器設定檔相關聯的每個視窗,變更下載使用者介面。只要至少有一個擴充功能將 UiOptions.enabled
設為 false,下載使用者介面就會隱藏。如果將 UiOptions.enabled
設為 true,但至少有一個擴充功能已停用,則系統會透過 runtime.lastError
傳回錯誤。除了 "downloads"
權限外,您也必須具備 "downloads.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,
)
當 bytesReceived
和 estimatedEndTime
以外的任何 DownloadItem
屬性變更時,系統會使用 downloadId
和包含已變更屬性的物件觸發這個事件。
參數
-
回呼
功能
callback
參數如下所示:(downloadDelta: DownloadDelta) => void
-
downloadDelta
-
onCreated
chrome.downloads.onCreated.addListener(
callback: function,
)
系統會在開始下載時透過 DownloadItem
物件觸發這個事件。
參數
-
回呼
功能
callback
參數如下所示:(downloadItem: DownloadItem) => void
-
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
-
suggest
功能
suggest
參數如下所示:(suggestion?: FilenameSuggestion) => void
-
建議
-
-
onErased
chrome.downloads.onErased.addListener(
callback: function,
)
清除歷史記錄中的下載內容時,使用 downloadId
觸發。
參數
-
回呼
功能
callback
參數如下所示:(downloadId: number) => void
-
downloadId
號碼
-