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<字符串|未定义>

    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