chrome.downloads

说明

使用 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。

  • 危险

    DangerType

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

  • 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

    FilenameConflictAction 可选

    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

    FilenameConflictAction 可选

    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

Chrome 105 及更高版本

属性

  • 已启用

    boolean

    启用或停用下载界面。

方法

acceptDanger()

Promise 
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()

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

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

参数

  • downloadId

    number

    要取消的下载的 ID。

  • callback

    函数（可选）

    callback 参数如下所示：

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

download()

Promise 
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()

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

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

参数

  • 个查询

    DownloadQuery

  • callback

    函数（可选）

    callback 参数如下所示：

    (erasedIds: number[]) => void

    • erasedIds

      数值 []

返回

  • Promise<number[]>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getFileIcon()

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

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

参数

  • downloadId

    number

    下载内容的标识符。

  • 选项

    GetFileIconOptions 可选

  • callback

    函数（可选）

    callback 参数如下所示：

    (iconURL?: string) => void

    • iconURL

      字符串（可选）

返回

  • Promise<string | undefined>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

open()

Promise 
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()

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

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

参数

  • downloadId

    number

    要暂停的下载的 ID。

  • callback

    函数（可选）

    callback 参数如下所示：

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeFile()

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

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

参数

  • downloadId

    number

  • callback

    函数（可选）

    callback 参数如下所示：

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

resume()

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

恢复已暂停的下载。如果请求成功，则下载正在进行并解除暂停。否则，runtime.lastError 包含错误消息。如果下载无效，请求将失败。

参数

  • downloadId

    number

    要恢复的下载的 ID。

  • callback

    函数（可选）

    callback 参数如下所示：

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

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

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

参数

返回

  • Promise<DownloadItem[]>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setShelfEnabled()

从 Chrome 117 开始已废弃
chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

请改用 setUiOptions。

在与当前浏览器配置文件相关联的每个窗口底部，启用或停用灰色任务栏。只要至少有一个扩展程序将其停用，该搁架就会被停用。如果在至少另外一个扩展程序已停用的情况下启用任务栏，则会通过 runtime.lastError 返回错误。除了 "downloads" 权限之外，还需要 "downloads.shelf" 权限。

参数

  • 已启用

    boolean

setUiOptions()

Promise 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<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，还会触发一个包含已更改属性的对象。

参数

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

      number