chrome.downloads

refresh date: 2026-09-25 robots: noindex

此权限会触发警告

说明

使用 chrome.downloads API，以编程方式启动、监控、操纵和搜索下载内容。

权限

downloads

清单

您必须在扩展程序清单中声明 "downloads" 权限，才能使用此 API。

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

示例

您可以在 examples/api/downloads 目录中找到使用 chrome.downloads API 的简单示例。如需查看其他示例以及查看源代码方面的帮助，请参阅示例。

类型

BooleanDelta

属性

  • 当前

    布尔值 （可选）

  • 上一页

    布尔值 （可选）

DangerType

枚举

“file”
下载的文件名可疑。

"url"
已知下载内容的网址是恶意网址。

"content"
已知下载的文件是恶意文件。

“uncommon”
下载内容的网址不常被下载，可能具有危险性。

“host”
下载内容来自已知会分发恶意二进制文件的主机，可能存在危险。

“垃圾内容”
下载内容可能是垃圾内容或不安全。例如，它可能会更改浏览器或计算机设置。

“safe”
下载内容对用户的计算机没有已知危险。

"accepted"
用户已接受危险下载。

"allowlistedByPolicy"
企业相关值。

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

"forceSaveToGdrive"
供安全企业浏览器扩展程序使用。必要时，Chrome 会阻止下载到磁盘，而是直接将文件下载到 Google 云端硬盘。

"forceSaveToOnedrive"
供安全企业浏览器扩展程序使用。必要时，Chrome 会阻止下载到磁盘，而是直接将文件下载到 OneDrive。

DoubleDelta

属性

  • 当前

    number 可选

  • 上一页

    number 可选

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

    字符串 可选

    如果此下载是由扩展程序发起的，则为发起此下载的扩展程序的标识符。一经设置便不会更改。

  • 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

    数值

    在浏览器会话之间保持不变的标识符。

  • 无痕模式

    布尔值

    如果此下载记录在历史记录中，则为 false；如果未记录，则为 true。

  • 哑剧

    字符串

    文件的 MIME 类型。

  • 已暂停

    布尔值

    如果下载已停止从主机读取数据，但保持连接处于打开状态，则为 true。

  • referrer

    字符串

    绝对网址。

  • startTime

    字符串

    下载开始的时间，采用 ISO 8601 格式。可直接传递给 Date 构造函数：chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • 州

    状态

    指示下载是正在进行、已中断还是已完成。

  • totalBytes

    数值

    整个文件中的字节数（不考虑文件压缩），如果未知，则为 -1。

  • 网址

    字符串

    此下载在任何重定向之前发起的绝对网址。

DownloadOptions

属性

  • 正文

    字符串 可选

    博文正文。

  • conflictAction

    FilenameConflictAction 可选

    如果 filename 已存在，则要执行的操作。

  • filename

    字符串 可选

    相对于“下载”目录的文件路径，用于包含下载的文件，可能包含子目录。绝对路径、空路径以及包含反向引用“..”的路径会导致错误。onDeterminingFilename 允许在确定文件的 MIME 类型和暂定文件名后建议文件名。

  • 标头

    HeaderNameValuePair[] 可选

    如果网址使用 HTTP[s] 协议，则需要随请求一起发送的额外 HTTP 标头。每个标头都表示为一个字典，其中包含键 name 以及 value 或 binaryValue，仅限于 XMLHttpRequest 允许的键。

  • 方法

    HttpMethod 可选

    如果网址使用 HTTP[S] 协议，则要使用的 HTTP 方法。

  • saveAs

    布尔值 （可选）

    使用文件选择器，让用户能够选择文件名，无论 filename 是否已设置或已存在。

  • 网址

    字符串

    要下载的网址。

DownloadQuery

属性

  • bytesReceived

    number 可选

    到目前为止从主机接收的字节数，不考虑文件压缩。

  • 危险

    DangerType 可选

    指明此下载内容是被认为安全还是已知可疑。

  • endTime

    字符串 可选

    下载结束时间，采用 ISO 8601 格式。

  • endedAfter

    字符串 可选

    将结果限制为在给定毫秒数（采用 ISO 8601 格式）之后结束的 DownloadItem

  • endedBefore

    字符串 可选

    将结果限制为在给定毫秒数（采用 ISO 8601 格式）之前结束的 DownloadItem。

  • 错误

    InterruptReason 可选

    下载中断的原因。

  • 存在

    布尔值 （可选）

    下载的文件是否存在；

  • fileSize

    number 可选

    解压缩后整个文件中的字节数；如果未知，则为 -1。

  • filename

    字符串 可选

    绝对本地路径。

  • filenameRegex

    字符串 可选

    将结果限制为 filename 与给定正则表达式匹配的 DownloadItem。

  • finalUrl

    字符串 可选

    Chrome 54 及更高版本

    在所有重定向后，此下载来源的绝对网址。

  • finalUrlRegex

    字符串 可选

    Chrome 54 及更高版本

    将结果限制为 finalUrl 与给定正则表达式匹配的 DownloadItem。

  • id

    number 可选

    要查询的 DownloadItem 的 id。

  • 限制

    number 可选

    返回的匹配 DownloadItem 的数量上限。默认值为 1000。设置为 0 可返回所有匹配的 DownloadItem。如需了解如何对结果进行分页，请参阅 search。

  • 哑剧

    字符串 可选

    文件的 MIME 类型。

  • orderBy

    string[] 可选

    将此数组的元素设置为 DownloadItem 属性，以便对搜索结果进行排序。例如，设置 orderBy=['startTime'] 会按开始时间升序对 DownloadItem 进行排序。如需指定降序，请添加连字符前缀：“-startTime”。

  • 已暂停

    布尔值 （可选）

    如果下载已停止从主机读取数据，但保持连接处于打开状态，则为 true。

  • 查询

    string[] 可选

    此搜索字词数组会将结果限制为 DownloadItem，其 filename、url 或 finalUrl 包含所有不以短划线“-”开头的搜索字词，且不包含任何以短划线开头的搜索字词。

  • startTime

    字符串 可选

    下载开始的时间，采用 ISO 8601 格式。

  • startedAfter

    字符串 可选

    将结果限制为在给定毫秒数（采用 ISO 8601 格式）之后开始的 DownloadItem。

  • startedBefore

    字符串 可选

    将结果限制为在给定毫秒数（采用 ISO 8601 格式）之前开始的 DownloadItem。

  • 州

    State（州/省/自治区/直辖市）可选

    指示下载是正在进行、已中断还是已完成。

  • totalBytes

    number 可选

    整个文件中的字节数（不考虑文件压缩），如果未知，则为 -1。

  • totalBytesGreater

    number 可选

    将结果限制为 totalBytes 大于给定整数的 DownloadItem。

  • totalBytesLess

    number 可选

    将结果限制为 totalBytes 小于给定整数的 DownloadItem。

  • 网址

    字符串 可选

    此下载在任何重定向之前发起的绝对网址。

  • urlRegex

    字符串 可选

    将结果限制为 url 与给定正则表达式匹配的 DownloadItem。

FilenameConflictAction

去重

为避免重复，filename 会更改为在文件扩展名前包含一个计数器。

覆盖

现有文件将被新文件覆盖。

提示

系统会向用户显示一个文件选择器对话框。

枚举

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

属性

  • conflictAction

    FilenameConflictAction 可选

    如果 filename 已存在，则要执行的操作。

  • filename

    字符串

    DownloadItem 的新目标 DownloadItem.filename，作为相对于用户默认下载目录的路径，可能包含子目录。系统会忽略绝对路径、空路径以及包含反向引用“..”的路径。如果任何扩展程序注册了任何 onDeterminingFilename 监听器，系统会忽略 filename。

GetFileIconOptions

属性

  • 大小

    number 可选

    返回的图标的大小（以密度无关像素 [DIP] 为单位）。必须为 16 或 32（默认为 32）。在高 DPI 显示屏上，返回的图片会根据设备缩放比例进行缩放（例如，在 2 倍显示屏上，尺寸为 32 的图片会缩放为 64x64 像素）。来自后台 Service Worker 的调用默认采用 1 倍缩放比例。

HeaderNameValuePair

属性

  • name

    字符串

    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

下载任务目前正在从服务器接收数据。

已中断

发生错误，导致与文件主机的连接中断。

complete

下载已成功完成。

枚举

"in_progress"

"interrupted"

"complete"

StringDelta

属性

  • 当前

    字符串 可选

  • 上一页

    字符串 可选

UiOptions

Chrome 105 及更高版本

属性

  • 已启用

    布尔值

    启用或停用下载界面。

方法

acceptDanger()

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

提示用户接受危险下载。只能从可见上下文（标签页、窗口或页面/浏览器操作弹出式窗口）中调用。不会自动接受危险下载内容。如果下载被接受，则会触发 onChanged 事件，否则不会发生任何情况。当所有数据都提取到临时文件中，并且下载不危险或危险已被接受时，临时文件将重命名为目标文件名，state 更改为“complete”，并触发 onChanged。

参数

  • downloadId

    数值

    DownloadItem 的标识符。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会在危险提示对话框关闭时解析。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

cancel()

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

取消下载。运行 callback 时，下载已取消、已完成、已中断或已不存在。

参数

  • downloadId

    数值

    要取消的下载任务的 ID。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会在取消请求完成时解析。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

download()

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

下载网址。如果网址使用 HTTP[S] 协议，则请求将包含当前为其主机名设置的所有 Cookie。如果同时指定了 filename 和 saveAs，系统会显示“另存为”对话框，并预先填充指定的 filename。如果下载成功启动，系统会使用新 DownloadItem 的 downloadId 调用 callback。如果开始下载时出错，系统会使用 downloadId=undefined 调用 callback，并且 runtime.lastError 将包含描述性字符串。我们不保证错误字符串在不同版本之间保持向后兼容。扩展程序不得对其进行解析。

参数

  • 下载内容和下载方式。

  • callback

    函数可选

    callback 参数如下所示： 

    (downloadId: number) => void

    • downloadId

      数值

返回

  • <number>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会解析为新 DownloadItem 的 ID。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

erase()

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

从历史记录中清除匹配的 DownloadItem，而不删除下载的文件。系统会为与 query 匹配的每个 DownloadItem 触发一个 onErased 事件，然后调用 callback。

参数

  • 查询

    DownloadQuery

  • callback

    函数可选

    callback 参数如下所示： 

    (erasedIds: number[]) => void

    • erasedIds

      number[]

返回

  • <number[]>

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getFileIcon()

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

检索指定下载内容的图标。对于新下载，文件图标会在下载的目标文件名确定后（例如，当 onChanged 触发且 filename 发生更改时）可用。如果在确定文件名之前尝试检索图标，则会通过 runtime.lastError 导致错误。此函数在下载过程中返回的图片可能与下载完成后返回的图片不同。图标检索是通过查询底层操作系统或工具包（具体取决于平台）来完成的。因此，返回的图标将取决于多种因素，包括下载状态、平台、注册的文件类型和视觉主题。如果无法确定文件图标，runtime.lastError 将包含一条出错提示。

参数

  • downloadId

    数值

    下载内容的标识符。

  • 选项

    GetFileIconOptions 可选

  • callback

    函数可选

    callback 参数如下所示： 

    (iconURL?: string) => void

    • iconURL

      字符串 可选

返回

  • Promise<string | undefined>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会解析为指向代表下载内容的图片的网址。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

open()

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

如果 DownloadItem 已完成，则立即打开下载的文件；否则通过 runtime.lastError 返回错误。除了 "downloads" 权限之外，此方法还需要 "downloads.open" 权限。当商品首次打开时，系统会触发 onChanged 事件。此方法只能在响应用户手势时调用。

参数

  • downloadId

    数值

    已下载文件的标识符。

  • callback

    函数可选

    Chrome 123 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 123 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

pause()

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

暂停下载。如果请求成功，下载将处于暂停状态。否则，runtime.lastError 会包含出错提示。如果下载未处于活动状态，请求将会失败。

参数

  • downloadId

    数值

    要暂停的下载任务的 ID。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会在暂停请求完成时解析。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

removeFile()

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

如果下载的文件存在且 DownloadItem 已完成，则移除该文件；否则通过 runtime.lastError 返回错误。

参数

  • downloadId

    数值

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

resume()

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

继续已暂停的下载。如果请求成功，则下载正在进行中且未暂停。否则，runtime.lastError 会包含出错提示。如果下载未处于活动状态，请求将会失败。

参数

  • downloadId

    数值

    要继续下载的下载任务的 ID。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    返回一个 Promise，该 Promise 会在恢复请求完成时解析。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

Promise 
chrome.downloads.search(
  query: DownloadQuery,
  callback?: function,
): Promise<DownloadItem[]>

找到 DownloadItem。将 query 设置为空对象，以获取所有 DownloadItem。如需获取特定 DownloadItem，请仅设置 id 字段。如需对大量内容进行分页，请设置 orderBy: ['-startTime']，将 limit 设置为每页的内容数量，并将 startedAfter 设置为上一页中最后一项内容的 startTime。

参数

返回

  • Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setShelfEnabled()

自 Chrome 117 起已弃用
chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

请改用 setUiOptions。

启用或停用与当前浏览器个人资料关联的每个窗口底部的灰色书架。只要至少有一个扩展程序停用了该书架，该书架就会被停用。如果至少有一个其他扩展程序已停用书架，则启用书架会通过 runtime.lastError 返回错误。除了 "downloads" 权限之外，还需要 "downloads.shelf" 权限。

参数

  • 已启用

    布尔值

setUiOptions()

Promise Chrome 105 及更高版本 
chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
): Promise<void>

更改与当前浏览器配置文件关联的每个窗口的下载界面。只要至少有一个扩展程序将 UiOptions.enabled 设置为 false，下载界面就会隐藏。如果至少有一个其他扩展程序已停用 UiOptions.enabled，则将其设置为 true 会通过 runtime.lastError 返回错误。除了 "downloads" 权限之外，还需要 "downloads.ui" 权限。

参数

  • 选项

    UiOptions

    封装对下载界面的更改。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    返回一个在界面更新完成后解析的 Promise。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

show()

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

在文件管理器中显示已下载文件所在的文件夹。

参数

  • downloadId

    数值

    已下载文件的标识符。

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

      数值