chrome.downloads

Description

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

Permissions

downloads

# Manifest

您必须在扩展清单中声明“downloads”权限才能使用此 API。

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

# Examples

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

Summary

• Types

  BooleanDelta

  DangerType

  DoubleDelta

  DownloadDelta

  DownloadItem

  DownloadOptions

  DownloadQuery

  FilenameConflictAction

  FilenameSuggestion

  GetFileIconOptions

  HeaderNameValuePair

  HttpMethod

  InterruptReason

  State

  StringDelta

• Methods

  acceptDanger

  cancel

  download

  erase

  getFileIcon

  open

  pause

  removeFile

  resume

  search

  setShelfEnabled

  show

  showDefaultFolder

• Events

  onChanged

  onCreated

  onDeterminingFilename

  onErased

Types

BooleanDelta

PROPERTIES

• current

  boolean optional

• previous

  boolean optional

DangerType

file

下载的文件名可疑。

url

已知下载的 URL 是恶意的。

content

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

uncommon

下载的 URL 不常下载，可能很危险。

host

下载来自已知分发恶意二进制文件的主机，并且可能是危险的。

unwanted

下载可能不需要或不安全。例如。它可以更改浏览器或计算机设置。

safe

下载不会对用户的计算机造成已知危险。

accepted

用户已接受危险下载。

TYPE

"file", "url", "content", "uncommon", "host", "unwanted", "safe", or "accepted"

DoubleDelta

PROPERTIES

• current

  number optional

• previous

  number optional

DownloadDelta

PROPERTIES

• canResume

  BooleanDelta optional

  canResume 中的更改（如果有）。

• danger

  StringDelta optional

  危险的变化，如果有的话。

• endTime

  StringDelta optional

  endTime 的更改（如果有）。

• error

  StringDelta optional

  错误的变化，如果有的话。

• exists

  BooleanDelta optional

  变化存在，如果有的话。

• fileSize

  DoubleDelta optional

  文件大小的变化，如果有的话。

• filename

  StringDelta optional

  文件名的更改（如果有）。

• finalUrl

  StringDelta optional

  Chrome 54+

  finalUrl 中的更改（如果有）。

• id

  number

  更改的 DownloadItem 的 id。

• mime

  StringDelta optional

  Mime的变化，如果有的话。

• paused

  BooleanDelta optional

  暂停的变化，如果有的话。

• startTime

  StringDelta optional

  startTime 的更改（如果有）。

• state

  StringDelta optional

  状态的变化，如果有的话。

• totalBytes

  DoubleDelta optional

  totalBytes 的变化，如果有的话。

• url

  StringDelta optional

  url 的更改（如果有）。

DownloadItem

PROPERTIES

• byExtensionId

  string optional

  如果此下载是由扩展程序启动的，则为启动此下载的扩展程序的标识符。一旦设置就不会改变。

• byExtensionName

  string optional

  如果此下载是由扩展程序启动的，则为启动此下载的扩展程序的本地化名称。如果扩展程序更改其名称或用户更改其语言环境，则可能会更改。

• bytesReceived

  number

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

• canResume

  boolean

  如果下载正在进行并暂停，则为真，否则如果下载被中断并且可以从中断处开始恢复。

• danger

  DangerType

  指示此下载是否被认为是安全的或已知是可疑的。

• endTime

  string optional

  下载以 ISO 8601 格式结束的时间。可以直接传递给 Date 构造函数：chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

• error

  InterruptReason optional

  为什么下载被中断。几种 HTTP 错误可以归入以 SERVER_ 开头的错误之一。与网络相关的错误以 NETWORK_ 开头，与将文件写入文件系统的过程相关的错误以 FILE_ 开头，用户发起的中断以 USER_ 开头。

• estimatedEndTime

  string optional

  以 ISO 8601 格式完成下载的预计时间。可以直接传递给 Date 构造函数：chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

• exists

  boolean

  下载的文件是否还存在。此信息可能已过时，因为 Chrome 不会自动监视文件删除。调用 search() 以触发文件存在检查。当存在检查完成时，如果文件已被删除，则将触发 onChanged 事件。请注意，search() 不会等待存在检查完成后再返回，因此 search() 的结果可能无法准确反映文件系统。此外，可以根据需要经常调用 search()，但不会比每 10 秒一次更频繁地检查文件是否存在。

• fileSize

  number

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

• filename

  string

  绝对本地路径。

• finalUrl

  string

  Chrome 54+

  在所有重定向之后，此下载的绝对 URL。

• id

  number

  跨浏览器会话持久的标识符。

• incognito

  boolean

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

• mime

  string

  文件的 MIME 类型。

• paused

  boolean

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

• referrer

  string

  绝对网址。

• startTime

  string

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

• state

  State

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

• totalBytes

  number

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

• url

  string

  在任何重定向之前，此下载启动的绝对 URL。

DownloadOptions

PROPERTIES

• body

  string optional

  Post body.

• conflictAction

  FilenameConflictAction optional

  如果文件名filename已存在，则采取的操作。

• filename

  string optional

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

• headers

  HeaderNameValuePair[] optional

  如果 URL 使用 HTTP[s] 协议，则与请求一起发送的额外 HTTP 标头。每个标头都表示为包含键名称name和值value或二进制值binaryValue的字典，仅限于 XMLHttpRequest 允许的那些。

• method

  HttpMethod optional

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

• saveAs

  boolean optional

  使用文件选择器允许用户选择文件名，而不管文件名是否已设置或已存在。

• url

  string

  要下载的 URL。

DownloadQuery

PROPERTIES

• bytesReceived

  number optional

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

• danger

  DangerType optional

  指示此下载是否被认为是安全的或已知是可疑的。

• endTime

  string optional

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

• endedAfter

  string optional

  将结果限制为自纪元以来在给定 ms 之后结束的 DownloadItem。

• endedBefore

  string optional

  将结果限制为自纪元以来在给定毫秒之前结束的 DownloadItem。

• error

  InterruptReason optional

  为什么下载被中断。

• exists

  boolean optional

  下载的文件是否存在；

• fileSize

  number optional

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

• filename

  string optional

  绝对本地路径。

• filenameRegex

  string optional

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

• finalUrl

  string optional

  Chrome 54+

  在所有重定向之后，此下载的绝对 URL。

• finalUrlRegex

  string optional

  Chrome 54+

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

• id

  number optional

  要查询的 DownloadItem 的 id。

• limit

  number optional

  返回的最大匹配下载项数。默认为 1000。设置为 0 以返回所有匹配的 DownloadItem。请参阅搜索search以了解如何翻阅结果。

• mime

  string optional

  文件的 MIME 类型。

• orderBy

  string[] optional

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

• paused

  boolean optional

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

• query

  string[] optional

  这组搜索词将结果限制为 DownloadItem，其文件名filename或 url 或 finalUrl 包含所有不以破折号“-”开头的搜索词，并且没有以破折号开头的搜索词。

• startTime

  string optional

  以 ISO 8601 格式开始下载的时间。

• startedAfter

  string optional

  将结果限制为自纪元以来在给定毫秒之后开始的 DownloadItem。

• startedBefore

  string optional

  将结果限制为自纪元以来在给定毫秒之前开始的 DownloadItem。

• state

  State optional

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

• totalBytes

  number optional

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

• totalBytesGreater

  number optional

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

• totalBytesLess

  number optional

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

• url

  string optional

  在任何重定向之前，此下载启动的绝对 URL。

• urlRegex

  string optional

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

FilenameConflictAction

uniquify

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

overwrite

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

prompt

系统将提示用户一个文件选择器对话框。

TYPE

"uniquify", "overwrite", or "prompt"

FilenameSuggestion

PROPERTIES

• conflictAction

  FilenameConflictAction optional

  如果文件名已存在，则采取的操作。

• filename

  string

  DownloadItem 的新目标 DownloadItem.filename，作为相对于用户默认下载目录的路径，可能包含子目录。绝对路径、空路径和包含反向引用“..”的路径将被忽略。如果任何扩展注册了任何 onDeterminingFilename 侦听器，则忽略文件名。

GetFileIconOptions

PROPERTIES

• size

  16 | 32 optional

返回图标的大小。图标将是正方形，尺寸为 size * size 像素。图标的默认和最大尺寸为 32x32 像素。唯一支持的大小是 16 和 32。指定任何其他大小都是错误的。

HeaderNameValuePair

PROPERTIES

• name

  string

  HTTP 标头的名称。

• value

  string

  HTTP 标头的值。

HttpMethod

TYPE

"GET", or "POST"

InterruptReason

TYPE

"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", or "CRASH"

State

in_progress

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

interrupted

一个错误中断了与文件主机的连接。

complete

下载成功完成。

TYPE

"in_progress", "interrupted", or "complete"

StringDelta

PROPERTIES

• current

  string optional

• previous

  string optional

Methods

acceptDanger

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

Promise

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

PARAMETERS

• downloadId

  number

  DownloadItem 的标识符。

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

cancel

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

Promise

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

PARAMETERS

• downloadId

  number

  要取消的下载的 ID。

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

download

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

Promise

下载一个网址。如果 URL 使用 HTTP[S] 协议，则请求将包括当前为其主机名设置的所有 cookie。如果同时指定了文件名和另存为，则将显示另存为对话框，其中预先填充了指定的文件名。如果下载成功开始，回调将使用新的 DownloadItem 的 downloadId 调用。如果开始下载时出现错误，则将使用 downloadId=undefined 调用回调，并且 runtime.lastError 将包含一个描述性字符串。错误字符串不能保证在版本之间保持向后兼容。扩展不能解析它。

PARAMETERS

• options

  DownloadOptions

  下载什么以及如何下载。

• callback

  function optional

  The callback parameter looks like:

  (downloadId: number) => void

  • downloadId

    number

RETURNS

• Promise<number>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

erase

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

Promise

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

PARAMETERS

• query

  DownloadQuery

• callback

  function optional

  The callback parameter looks like:

  (erasedIds: number[]) => void

  • erasedIds

    number[]

RETURNS

• Promise<number[]>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getFileIcon

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

Promise

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

PARAMETERS

• downloadId

  number

  下载的标识符。

• options

  GetFileIconOptions optional

• callback

  function optional

  The callback parameter looks like:

  (iconURL?: string) => void

  • iconURL

    string optional

RETURNS

• Promise<string | undefined>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

open

chrome.downloads.open(
  downloadId: number,
)

如果 DownloadItem 完成，现在打开下载的文件；否则通过runtime.lastError 返回错误。除了“下载downloads”权限之外，还需要“downloads.open”权限。第一次打开项目时将触发 onChanged 事件。

PARAMETERS

• downloadId

  number

  下载文件的标识符。

pause

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

Promise

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

PARAMETERS

• downloadId

  number

  要暂停的下载的 ID。

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

removeFile

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

Promise

如果下载的文件存在并且DownloadItem完整，则删除它；否则通过runtime.lastError 返回错误。

PARAMETERS

• downloadId

  number

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

resume

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

Promise

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

PARAMETERS

• downloadId

  number

  要恢复的下载的 ID。

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

search

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

Promise

找到下载项目。将查询query设置为空对象以获取所有下载项。要获取特定的 DownloadItem，只需设置 id 字段。要翻阅大量项目，请设置 orderBy: ['-startTime']，将限制设置为每页的项目数，并将开始后设置为从最后一页开始的最后一个项目的 startTime。

PARAMETERS

• query

  DownloadQuery

• callback

  function optional

  The callback parameter looks like:

  (results: DownloadItem[]) => void

  • results

    DownloadItem[]

RETURNS

• Promise<DownloadItem[]>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

setShelfEnabled

chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

启用或禁用与当前浏览器配置文件关联的每个窗口底部的灰色架子。只要至少有一个分机禁用了搁板，它就会被禁用。在至少一个其他扩展已禁用时启用架子将通过 runtime.lastError 返回错误。除了“下载downloads”权限之外，还需要“downloads.shelf”权限。

PARAMETERS

• enabled

  boolean

show

chrome.downloads.show(
  downloadId: number,
)

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

PARAMETERS

• downloadId

  number

  下载文件的标识符。

showDefaultFolder

chrome.downloads.showDefaultFolder()

在文件管理器中显示默认的下载文件夹。

Events

onChanged

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

当任何 DownloadItem 的属性（bytesReceived 和estimatedEndTime 除外）发生更改时，此事件将使用 downloadId 和包含更改的属性的对象触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (downloadDelta: DownloadDelta) => void

  • downloadDelta

    DownloadDelta

onCreated

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

当下载开始时，此事件与 DownloadItem 对象一起触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (downloadItem: DownloadItem) => void

  • downloadItem

    DownloadItem

onDeterminingFilename

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

在文件名确定过程中，扩展程序将有机会覆盖目标 DownloadItem.filename。每个扩展不能为此事件注册一个以上的侦听器。每个侦听器必须同步或异步调用一次建议。如果侦听器异步调用建议suggest，则它必须返回 true。如果侦听器既不同步调用suggest 也不返回true，则suggest 将自动调用。在所有侦听器都调用了建议之前，DownloadItem 不会完成。侦听器可以不带任何参数调用建议以允许下载使用 downloadItem.filename 作为其文件名，或传递建议对象以建议以覆盖目标文件名。如果有多个扩展覆盖了文件名，那么最后一个安装的扩展的侦听器将建议对象传递给suggest获胜。为了避免混淆哪个扩展将获胜，用户不应安装可能发生冲突的扩展。如果download是由下载启动的，并且在确定 MIME 类型和暂定文件名之前已知目标文件名，则将文件名filename传递给download。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (downloadItem: DownloadItem, suggest: function) => void

  • downloadItem

    DownloadItem

  • suggest

    function

    The suggest parameter looks like:

    (suggestion?: FilenameSuggestion) => void

    • suggestion

      FilenameSuggestion optional

onErased

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

当从历史记录中删除下载时，使用 downloadId 触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (downloadId: number) => void

  • downloadId

    number

By.一粒技术服务.