说明
使用 chrome.downloads
API 以编程方式启动、监控、操纵和搜索下载内容。
权限
downloads
您必须在扩展程序清单中声明 "downloads"
权限,才能使用此 API。
{
"name": "My extension",
...
"permissions": [
"downloads"
],
}
示例
您可以在 examples/api/downloads 目录中找到使用 chrome.downloads
API 的简单示例。如需查看其他示例以及在查看源代码方面获得帮助,请参阅示例。
类型
BooleanDelta
属性
-
当前
布尔值 选填
-
返回
布尔值 选填
DangerType
文件
下载内容的文件名可疑。
网址
下载内容的网址是已知的。
内容
下载的文件是已知恶意文件。
不常见
下载内容的网址不常被下载,可能具有危险性。
主办方
下载内容来自已知会传播恶意二进制文件的主机,很可能存在危险。
不受欢迎
下载内容可能不合适或不安全。例如,它可能会更改浏览器或计算机设置。
安全
下载内容不会给用户计算机带来任何已知危险。
已接受
用户已接受危险的下载内容。
枚举
"file"
"url"
"host"
"safe"
"accepted"
"allowlistedByPolicy"
"asyncScanning"
"asyncLocalPasswordScanning"
"blockedTooLarge"
"sensitiveContentWarning"
"sensitiveContentBlock"
"deepScannedSafe"
"deepScannedOpenedDangerous"
"promptForScanning"
"promptForLocalPasswordScanning"
"blockedScanFailed"
DoubleDelta
属性
-
当前
数字可选
-
返回
数字可选
DownloadDelta
属性
-
canResume
BooleanDelta(可选)
canResume
中的更改(如果有)。 -
危险
StringDelta(可选)
danger
中的更改(如果有)。 -
endTime
StringDelta(可选)
endTime
中的更改(如果有)。 -
error
StringDelta(可选)
error
中的更改(如果有)。 -
存在
BooleanDelta(可选)
exists
中的更改(如果有)。 -
fileSize
DoubleDelta(可选)
fileSize
中的更改(如果有)。 -
filename
StringDelta(可选)
filename
中的更改(如果有)。 -
finalUrl
StringDelta(可选)
Chrome 54 及更高版本finalUrl
中的更改(如果有)。 -
id
number
发生更改的
DownloadItem
的id
。 -
哑剧
StringDelta(可选)
mime
中的更改(如果有)。 -
已暂停
BooleanDelta(可选)
paused
中的更改(如果有)。 -
startTime
StringDelta(可选)
startTime
中的更改(如果有)。 -
state
StringDelta(可选)
state
中的更改(如果有)。 -
totalBytes
DoubleDelta(可选)
totalBytes
中的更改(如果有)。 -
网址
StringDelta(可选)
url
中的更改(如果有)。
DownloadItem
属性
-
byExtensionId
字符串(可选)
启动此下载的扩展程序的标识符(如果此下载是由扩展程序启动的)。设置后不会更改。
-
byExtensionName
字符串(可选)
启动此下载的扩展程序的本地化名称(如果此下载是由扩展程序启动的)。如果扩展程序更改了名称或用户更改了语言区域,则可能会更改。
-
bytesReceived
number
到目前为止从主机接收的字节数(不考虑文件压缩)。
-
canResume
boolean
如果下载正在进行且已暂停,或者下载中断,可以从中断的地方恢复,则为 true。
-
危险
指明此下载内容是否安全或已知可疑。
-
endTime
字符串(可选)
下载结束的时间(ISO 8601 格式)。可以直接传递给 Date 构造函数:
chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})
-
error
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))})})
-
存在
boolean
已下载的文件是否仍然存在。此信息可能已过时,因为 Chrome 不会自动监测文件移除情况。调用
search
() 以触发检查文件是否存在。完成存在性检查后,如果相应文件已被删除,则会触发onChanged
事件。请注意,search
() 不会等待存在性检查完成再返回,因此search
() 的结果可能无法准确反映文件系统。此外,可以根据需要随时调用search
(),但检查文件是否存在的频率不会超过每 10 秒一次。 -
fileSize
number
整个文件解压缩后的字节数,如果未知,则为 -1。
-
filename
string
绝对本地路径。
-
finalUrl
string
Chrome 54 及更高版本进行此下载时使用的绝对网址(经过所有重定向之后)。
-
id
number
一种跨浏览器会话永久的标识符。
-
无痕模式
boolean
如果此下载记录在历史记录中,则为 false;如果未记录,则为 true。
-
哑剧
string
文件的 MIME 类型。
-
已暂停
boolean
如果下载已停止从主机读取数据,但连接保持打开状态,则为 true。
-
referrer
string
绝对网址。
-
startTime
string
开始下载的时间(ISO 8601 格式)。可以直接传递给 Date 构造函数:
chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})
-
state
指明下载是正在进行、中断还是已完成。
-
totalBytes
number
整个文件中的字节数(不考虑文件压缩),如果未知,则为 -1。
-
网址
string
发起下载时所在的绝对网址(在进行任何重定向之前)。
DownloadOptions
属性
-
body
字符串(可选)
帖子正文。
-
conflictAction
filename
已存在时要执行的操作。 -
filename
字符串(可选)
相对于“下载内容”目录的文件路径,用于包含所下载的文件,其中可能包含子目录。绝对路径、空路径以及包含反向引用“..”的路径都将引发错误。
onDeterminingFilename
允许在确定文件的 MIME 类型和暂定文件名后建议文件名。 -
headers
HeaderNameValuePair[] 可选
如果网址使用 HTTP[s] 协议,则随请求发送的额外 HTTP 标头。每个标头都表示为一个字典,其中包含
name
和value
或binaryValue
键,并且仅限于 XMLHttpRequest 允许使用键。 -
method
HttpMethod 可选
在网址使用 HTTP[S] 协议时使用的 HTTP 方法。
-
saveAs
布尔值 选填
使用文件选择器允许用户选择文件名,而不管
filename
是否已设置或已存在。 -
网址
string
要下载的网址。
DownloadQuery
属性
-
bytesReceived
数字可选
到目前为止从主机接收的字节数(不考虑文件压缩)。
-
危险
DangerType 可选
指明此下载内容是否安全或已知可疑。
-
endTime
字符串(可选)
下载结束的时间(ISO 8601 格式)。
-
endedAfter
字符串(可选)
将结果限制为在给定毫秒数后结束的
DownloadItem
,采用 ISO 8601 格式 -
endedBefore
字符串(可选)
将结果限制为在指定毫秒之前结束的
DownloadItem
,采用 ISO 8601 格式。 -
error
InterruptReason(可选)
下载中断的原因。
-
存在
布尔值 选填
已下载的文件是否存在;
-
fileSize
数字可选
整个文件解压缩后的字节数,如果未知,则为 -1。
-
filename
字符串(可选)
绝对本地路径。
-
filenameRegex
字符串(可选)
将结果限制为其
filename
与指定正则表达式匹配的DownloadItem
。 -
finalUrl
字符串(可选)
Chrome 54 及更高版本进行此下载时使用的绝对网址(经过所有重定向之后)。
-
finalUrlRegex
字符串(可选)
Chrome 54 及更高版本将结果限制为其
finalUrl
与指定正则表达式匹配的DownloadItem
。 -
id
数字可选
要查询的
DownloadItem
的id
。 -
限制
数字可选
返回的最大匹配
DownloadItem
数量。默认值为 1,000。设置为 0 可返回所有匹配的DownloadItem
。如需了解如何对结果进行分页,请参阅search
。 -
哑剧
字符串(可选)
文件的 MIME 类型。
-
orderBy
string[] 可选
将此数组的元素设置为
DownloadItem
属性,以便对搜索结果进行排序。例如,如果设置orderBy=['startTime']
,系统会按开始时间对DownloadItem
进行升序排序。如需指定降序,请在前面加上连字符:'-startTime'。 -
已暂停
布尔值 选填
如果下载已停止从主机读取数据,但连接保持打开状态,则为 true。
-
个查询
string[] 可选
此搜索字词数组将结果限制为
DownloadItem
,其filename
、url
或finalUrl
包含不以短划线“-”开头的所有搜索字词,并且不包含以短划线开头的搜索字词。 -
startTime
字符串(可选)
开始下载的时间(ISO 8601 格式)。
-
startedAfter
字符串(可选)
将结果限制为在给定毫秒数之后开始的
DownloadItem
,采用 ISO 8601 格式。 -
startedBefore
字符串(可选)
将结果限制为在指定毫秒之前开始的
DownloadItem
,采用 ISO 8601 格式。 -
state
状态(可选)
指明下载是正在进行、中断还是已完成。
-
totalBytes
数字可选
整个文件中的字节数(不考虑文件压缩),如果未知,则为 -1。
-
totalBytesGreater
数字可选
将结果限制为
totalBytes
大于给定整数的DownloadItem
。 -
totalBytesLess
数字可选
将结果限制为
totalBytes
小于指定整数的DownloadItem
。 -
网址
字符串(可选)
发起下载时所在的绝对网址(在进行任何重定向之前)。
-
urlRegex
字符串(可选)
将结果限制为其
url
与指定正则表达式匹配的DownloadItem
。
FilenameConflictAction
统一
为避免重复,更改 filename
以在文件扩展名前添加计数器。
改写
新文件会覆盖现有文件。
提示
系统会显示一个文件选择器对话框来提示用户。
枚举
"uniquify"
FilenameSuggestion
属性
-
conflictAction
filename
已存在时要执行的操作。 -
filename
string
DownloadItem
的新目标DownloadItem.filename
,作为相对于用户默认“Downloads”目录的路径,可能包含子目录。绝对路径、空路径以及包含反向引用“..”的路径将被忽略。如果有任何扩展程序注册了任何onDeterminingFilename
监听器,filename
会被忽略。
GetFileIconOptions
属性
-
大小
可选
返回的图标的大小。该图标将为方形,尺寸为 * 尺寸(像素)。此图标的默认尺寸和最大尺寸为 32x32 像素。仅支持的尺寸为 16 和 32。指定任何其他尺寸会导致出错。
HeaderNameValuePair
属性
-
name
string
HTTP 标头的名称。
-
值
string
HTTP 标头的值。
HttpMethod
枚举
InterruptReason
枚举
"FILE_TOO_LARGE"
"FILE_VIRUS_INFECTED"
"FILE_HASH_MISMATCH"
State
in_progress
下载内容目前正在从服务器接收数据。
已中断
错误中断了与文件主机的连接。
complete
下载已成功完成。
枚举
"in_progress"
StringDelta
属性
-
当前
字符串(可选)
-
返回
字符串(可选)
UiOptions
属性
-
已启用
boolean
启用或停用下载界面。
方法
acceptDanger()
chrome.downloads.acceptDanger(
downloadId: number,
callback?: function,
)
提示用户接受危险的下载内容。只能从可见上下文(标签页、窗口或页面/浏览器操作弹出式窗口)中调用。不自动接受危险下载内容。如果下载被接受,则会触发 onChanged
事件,否则不会执行任何操作。当所有数据都被提取到临时文件中,并且下载内容不存在危险或危险已被接受后,临时文件将重命名为目标文件名,state
会更改为“complete”,并且 onChanged
会触发。
参数
-
downloadId
number
DownloadItem
的标识符。 -
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
cancel()
chrome.downloads.cancel(
downloadId: number,
callback?: function,
)
取消下载。当 callback
运行时,下载会被取消、已完成、中断或不再存在。
参数
-
downloadId
number
要取消的下载的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
download()
chrome.downloads.download(
options: DownloadOptions,
callback?: function,
)
下载网址。如果网址使用 HTTP[S] 协议,则请求将包含当前为其主机名设置的所有 Cookie。如果同时指定了 filename
和 saveAs
,系统会显示“另存为”对话框,其中预先填充了指定的 filename
。如果下载成功开始,系统将使用新的 DownloadItem
的 downloadId
调用 callback
。如果开始下载时出错,系统将使用 downloadId=undefined
调用 callback
,并且 runtime.lastError
将包含描述性字符串。不保证错误字符串在不同版本之间保持向后兼容性。扩展程序不得对其进行解析。
参数
-
下载内容和操作方法。
-
callback
函数(可选)
callback
参数如下所示:(downloadId: number) => void
-
downloadId
number
-
返回
-
Promise<数字>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
erase()
chrome.downloads.erase(
query: DownloadQuery,
callback?: function,
)
将匹配的DownloadItem
从历史记录中清除,但不删除已下载的文件。对于每个与 query
匹配的 DownloadItem
,会触发 onErased
事件,然后调用 callback
。
参数
-
个查询
-
callback
函数(可选)
callback
参数如下所示:(erasedIds: number[]) => void
-
erasedIds
数值 []
-
返回
-
Promise<number[]>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getFileIcon()
chrome.downloads.getFileIcon(
downloadId: number,
options?: GetFileIconOptions,
callback?: function,
)
检索指定下载的图标。对于新的下载内容,我们会在收到 onCreated
事件后提供文件图标。下载过程中此函数返回的图片可能与下载完成后返回的图片不同。图标检索通过查询底层操作系统或工具包完成,具体取决于平台。因此,返回的图标取决于多种因素,包括下载状态、平台、注册的文件类型以及视觉主题。如果无法确定文件图标,runtime.lastError
将包含错误消息。
参数
-
downloadId
number
下载内容的标识符。
-
选项
-
callback
函数(可选)
callback
参数如下所示:(iconURL?: string) => void
-
iconURL
字符串(可选)
-
返回
-
Promise<string | undefined>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
open()
chrome.downloads.open(
downloadId: number,
callback?: function,
)
在 DownloadItem
完成后立即打开下载的文件;否则通过 runtime.lastError
返回错误。除了 "downloads"
权限外,此方法还需要 "downloads.open"
权限。onChanged
事件会在内容首次打开时触发。此方法只能在响应用户手势时调用。
参数
-
downloadId
number
已下载文件的标识符。
-
callback
函数(可选)
Chrome 123 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 123 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
pause()
chrome.downloads.pause(
downloadId: number,
callback?: function,
)
暂停下载。如果请求成功,下载会处于暂停状态。否则,runtime.lastError
包含错误消息。如果下载无效,请求将失败。
参数
-
downloadId
number
要暂停的下载的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
removeFile()
chrome.downloads.removeFile(
downloadId: number,
callback?: function,
)
移除已下载的文件(若该文件存在且 DownloadItem
已完成);否则通过 runtime.lastError
返回错误。
参数
-
downloadId
number
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
resume()
chrome.downloads.resume(
downloadId: number,
callback?: function,
)
恢复已暂停的下载。如果请求成功,则下载正在进行并解除暂停。否则,runtime.lastError
包含错误消息。如果下载无效,请求将失败。
参数
-
downloadId
number
要恢复的下载的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
search()
chrome.downloads.search(
query: DownloadQuery,
callback?: function,
)
找到 DownloadItem
。将 query
设置为空对象,以获取所有 DownloadItem
。如需获取特定的 DownloadItem
,请仅设置 id
字段。如需对大量项进行分页,请设置 orderBy: ['-startTime']
,将 limit
设置为每页的项数,并将 startedAfter
设置为最后一页中最后一项的 startTime
。
参数
-
个查询
-
callback
函数(可选)
callback
参数如下所示:(results: DownloadItem[]) => void
-
结果
-
返回
-
Promise<DownloadItem[]>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setShelfEnabled()
chrome.downloads.setShelfEnabled(
enabled: boolean,
)
请改用 setUiOptions
。
在与当前浏览器配置文件相关联的每个窗口底部,启用或停用灰色任务栏。只要至少有一个扩展程序将其停用,该搁架就会被停用。如果在至少另外一个扩展程序已停用的情况下启用任务栏,则会通过 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
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
show()
chrome.downloads.show(
downloadId: number,
)
在文件管理器的相应文件夹中显示已下载的文件。
参数
-
downloadId
number
已下载文件的标识符。
showDefaultFolder()
chrome.downloads.showDefaultFolder()
在文件管理器中显示默认的“下载内容”文件夹。
活动
onChanged
chrome.downloads.onChanged.addListener(
callback: function,
)
当 DownloadItem
的任何属性(bytesReceived
和 estimatedEndTime
除外)发生更改时,此事件会触发 downloadId
,还会触发一个包含已更改属性的对象。
参数
-
callback
功能
callback
参数如下所示:(downloadDelta: DownloadDelta) => void
-
downloadDelta
-
onCreated
chrome.downloads.onCreated.addListener(
callback: function,
)
下载开始时,此事件会通过 DownloadItem
对象触发。
参数
-
callback
功能
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
功能
callback
参数如下所示:(downloadItem: DownloadItem, suggest: function) => void
-
downloadItem
-
suggest
功能
suggest
参数如下所示:(suggestion?: FilenameSuggestion) => void
-
建议
-
-
onErased
chrome.downloads.onErased.addListener(
callback: function,
)
当下载内容从历史记录中清除时,使用 downloadId
触发。
参数
-
callback
功能
callback
参数如下所示:(downloadId: number) => void
-
downloadId
number
-