chrome.downloads

此权限会触发警告

说明

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

权限

downloads

清单

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

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

示例

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

类型

BooleanDelta

属性

• 当前

  布尔值（可选）

• 返回

  布尔值（可选）

DangerType

文件

下载内容的文件名可疑。

网址

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

内容

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

不常见

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

主机

下载内容来自已知会分发恶意二进制文件的主机，这可能具有危险性。

不想要的

下载内容可能不受欢迎或不安全。例如：它可能会更改浏览器或计算机设置。

安全

下载内容不会给用户计算机带来已知的危险。

已接受

用户已接受危险下载内容。

枚举

"asyncScanning"

"asyncLocalPasswordScanning"

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

  number

  发生更改的 DownloadItem 的 id。

• 哑剧

  StringDelta 选填

  mime 的更改（如果有）。

• 已暂停

  BooleanDelta 可选

  paused 的更改（如果有）。

• startTime

  StringDelta 选填

  startTime 的更改（如果有）。

• 州

  StringDelta 选填

  state 的更改（如果有）。

• totalBytes

  DoubleDelta 可选

  totalBytes 的更改（如果有）。

• 网址

  StringDelta 选填

  url 的更改（如果有）。

DownloadItem

属性

• byExtensionId

  字符串（可选）

  启动此下载的扩展程序的标识符（如果此下载是由扩展程序启动的）。设置后不会更改。

• byExtensionName

  字符串（可选）

  启动此下载的扩展程序的本地化名称（如果此下载是由扩展程序启动的）。在扩展程序更改名称或用户更改其语言区域时，可能会发生变化。

• bytesReceived

  number

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

• canResume

  布尔值

  如果下载正在进行中并已暂停，则为 true；否则，如果下载中断，可以从中断的位置恢复下载。

• 危险

  DangerType

  指明此下载内容是否安全或已知可疑。

• 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))})})

• 存在

  布尔值

  下载的文件是否仍然存在。此信息可能已过期，因为 Chrome 不会自动监测文件移除情况。调用 search() 以触发检查文件是否存在的功能。存在性检查完成后，如果文件已被删除，则会触发 onChanged 事件。请注意，search() 不会等待存在性检查完成后再返回，因此来自 search() 的结果可能无法准确反映文件系统。此外，可以根据需要频繁调用 search()，但检查文件是否存在的频率不会超过每 10 秒一次。

• fileSize

  number

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

• filename

  字符串

  本地绝对路径。

• finalUrl

  字符串

  Chrome 54 及更高版本

  完成所有重定向后，发起此下载的绝对网址。

• id

  number

  在各个浏览器会话间永久保留的标识符。

• 无痕模式

  布尔值

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

• 哑剧

  字符串

  文件的 MIME 类型。

• 已暂停

  布尔值

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

• referrer

  字符串

  绝对网址。

• startTime

  字符串

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

• 州

  状态

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

• totalBytes

  number

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

• 网址

  字符串

  进行任何重定向之前启动此下载操作的绝对网址。

DownloadOptions

属性

• body

  字符串（可选）

  博文正文。

• conflictAction

  FilenameConflictAction（可选）

  在 filename 已存在时执行的操作。

• filename

  字符串（可选）

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

• 标头

  HeaderNameValuePair[] 可选

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

• method

  HttpMethod 可选

  网址使用 HTTP[S] 协议时使用的 HTTP 方法。

• saveAs

  布尔值（可选）

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

• 网址

  字符串

  要下载的网址。

DownloadQuery

属性

• bytesReceived

  编号（选填）

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

• 危险

  DangerType 可选

  指明此下载内容是否安全或已知可疑。

• endTime

  字符串（可选）

  下载的结束时间（ISO 8601 格式）。

• endedAfter

  字符串（可选）

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

• endedBefore

  字符串（可选）

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

• 错误

  InterruptReason（可选）

  下载中断的原因。

• 存在

  布尔值（可选）

  下载的文件是否存在；

• fileSize

  编号（选填）

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

• filename

  字符串（可选）

  本地绝对路径。

• filenameRegex

  字符串（可选）

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

• finalUrl

  字符串（可选）

  Chrome 54 及更高版本

  完成所有重定向后，发起此下载的绝对网址。

• finalUrlRegex

  字符串（可选）

  Chrome 54 及更高版本

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

• 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 格式）。

• 州

  州/省级行政区（可选）

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

• totalBytes

  编号（选填）

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

• totalBytesGreater

  编号（选填）

  将结果限制为 DownloadItem，其中 totalBytes 大于给定整数。

• totalBytesLess

  编号（选填）

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

• 网址

  字符串（可选）

  进行任何重定向之前启动此下载操作的绝对网址。

• urlRegex

  字符串（可选）

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

FilenameConflictAction

唯一

为避免重复，filename 已更改为在文件扩展名前添加一个计数器。

覆盖

新文件将覆盖现有文件。

提示符

系统会显示文件选择器对话框来提示用户。

枚举

FilenameSuggestion

属性

• conflictAction

  FilenameConflictAction（可选）

  在 filename 已存在时执行的操作。

• filename

  字符串

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

GetFileIconOptions

属性

• 大小

  编号（选填）

  返回的图标的尺寸。该图标为正方形，尺寸为大小 * 大小（像素）。图标的默认大小和最大尺寸为 32x32 像素。唯一支持的尺寸为 16 和 32。指定其他尺寸时出错。

HeaderNameValuePair

属性

• name

  字符串

  HTTP 标头的名称。

• 值

  字符串

  HTTP 标头的值。

HttpMethod

枚举

InterruptReason

枚举

State

in_progress

下载内容当前正在从服务器接收数据。

中断

出错了，与文件主机的连接中断。

complete

下载已成功完成。

枚举

StringDelta

属性

• 当前

  字符串（可选）

• 返回

  字符串（可选）

UiOptions

Chrome 105 及更高版本

属性

• 已启用

  布尔值

  启用或停用下载界面。

方法

acceptDanger()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.acceptDanger(
  downloadId: number,
  callback?: function,
)

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

参数

• downloadId

  number

  DownloadItem 的标识符。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 96 及更高版本

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

cancel()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.cancel(
  downloadId: number,
  callback?: function,
)

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

参数

• downloadId

  number

  要取消的下载的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 96 及更高版本

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

download()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.download(
  options: DownloadOptions,
  callback?: function,
)

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

参数

• 选项

  DownloadOptions

  下载内容及下载方式。

• callback

  函数（可选）

  callback 参数如下所示：

  (downloadId: number) => void

  • downloadId

    number

返回

• Promise&lt;number&gt;

  Chrome 96 及更高版本

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

erase()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• 查询

  DownloadQuery

• callback

  函数（可选）

  callback 参数如下所示：

  (erasedIds: number[]) => void

  • erasedIds

    数值 []

返回

• Promise&lt;number[]&gt;

  Chrome 96 及更高版本

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

getFileIcon()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
  callback?: function,
)

检索指定下载的图标。对于新下载，文件图标会在收到 onCreated 事件后显示。下载过程中，此函数返回的图片可能与下载完成后返回的图片不同。图标检索是通过查询底层操作系统或工具包（取决于平台）来完成的。因此，返回的图标取决于多种因素，包括下载状态、平台、注册的文件类型和视觉主题。如果无法确定文件图标，runtime.lastError 将包含错误消息。

参数

• downloadId

  number

  下载的标识符。

• 选项

  GetFileIconOptions 可选

• callback

  函数（可选）

  callback 参数如下所示：

  (iconURL?: string) => void

  • iconURL

    字符串（可选）

返回

• Promise&lt;string |未定义>

  Chrome 96 及更高版本

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

open()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.open(
  downloadId: number,
  callback?: function,
)

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

参数

• downloadId

  number

  已下载文件的标识符。

• callback

  函数（可选）

  Chrome 123 及更高版本

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 123 及更高版本

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

pause()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.pause(
  downloadId: number,
  callback?: function,
)

暂停下载。如果请求成功，则下载会处于暂停状态。否则，runtime.lastError 包含错误消息。如果下载未激活，请求将失败。

参数

• downloadId

  number

  要暂停的下载的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 96 及更高版本

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

removeFile()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.removeFile(
  downloadId: number,
  callback?: function,
)

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

参数

• downloadId

  number

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 96 及更高版本

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

resume()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.downloads.resume(
  downloadId: number,
  callback?: function,
)

恢复已暂停的下载。如果请求成功，则表示正在进行下载并已取消暂停。否则，runtime.lastError 包含错误消息。如果下载未激活，请求将失败。

参数

• downloadId

  number

  要恢复的下载的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  Chrome 96 及更高版本

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

search()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

• 查询

  DownloadQuery

• callback

  函数（可选）

  callback 参数如下所示：

  (results: DownloadItem[]) => void

  • 结果

    DownloadItem[]

返回

• Promise&lt;DownloadItem[]&gt;

  Chrome 96 及更高版本

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

setShelfEnabled()

<ph type="x-smartling-placeholder"></ph> 自 Chrome 117 起弃用

chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

请改用 setUiOptions。

启用或停用与当前浏览器配置文件相关联的每个窗口底部的灰色工具栏。只要至少有一个扩展程序停用了此搁架，它就会一直处于停用状态。如果启用搁架，而至少还有一个其他扩展程序已停用，则系统会通过 runtime.lastError 返回错误。除 "downloads" 权限外，还需要 "downloads.shelf" 权限。

参数

• 已启用

  布尔值

setUiOptions()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 105 及更高版本

chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
)

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

参数

• 选项

  UiOptions

  封装对下载界面的更改。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise&lt;void&gt;

  只有 Manifest V3 及更高版本支持 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

    DownloadDelta

onCreated

chrome.downloads.onCreated.addListener(
  callback: function,
)

下载开始时，此事件通过 DownloadItem 对象触发。

参数

• callback

  函数

  callback 参数如下所示：

  (downloadItem: DownloadItem) => void

  • downloadItem

    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

    DownloadItem

  • suggest

    函数

    suggest 参数如下所示：

    (suggestion?: FilenameSuggestion) => void

    • 建议

      FilenameSuggestion（可选）

onErased

chrome.downloads.onErased.addListener(
  callback: function,
)

当下载内容从历史记录中清除时，通过 downloadId 触发。

参数

• callback

  函数

  callback 参数如下所示：

  (downloadId: number) => void

  • downloadId

    number