chrome.downloads

参数

options ( object )

下载的内容与方式。

属性

url ( string )

要下载的 URL。

filename ( optional string )

相对于下载文件夹的路径，包含下载得到的文件，可以包含子目录。绝对路径、空路径以及包含向前引用“..”的路径会导致错误。onDeterminingFilename 允许在文件 MIME 类型和待定文件名确定后推荐文件名。

conflictAction ( optional FilenameConflictAction )

filename 已经存在时进行的操作。

saveAs ( optional boolean )

使用选择文件对话框，允许用户选择文件名（无论 filename 是否设置或已经存在）。

method ( optional enum of "GET", or "POST" )

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

headers ( optional array of object )

如果 URL 使用 HTTP[S] 协议，则包含要与请求一起发送的附加 HTTP 头信息。每一条头信息都由词典表示，包含键 name 以及 value 或 binaryValue 中的某一个，仅限于 XMLHttpRequest 中允许的头信息。

每一个对象的属性

name ( string )

HTTP 头信息的名称。

value ( string )

HTTP 头信息的值。

body ( optional string )

POST 方法的正文。

callback ( optional function )

调用时传递新的 DownloadItem 的标识符。

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function(integer downloadId) {...};

downloadId ( integer )

寻找 DownloadItem（下载项）。将 query 设置为空对象可以获取所有下载项。要获得某个特定的下载项，只要设置 id 字段。要为大量项目分页，请设置 orderBy: ['-startTime']，将 limit 设置为每一页的项目数目，并将 startedAfter 设置为上一页最后一个项目的 startTime 属性。

参数

query ( object )

属性

query ( optional array of string )

这一搜索条目数组将结果限制为文件名（filename）或 URL 包含所有不以减号（'-'）开始的搜索条目并且不包含所有以减号（'-'）开始的搜索条目。

startedBefore ( optional string )

将结果限制为下载开始时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之前的 DownloadItem。

startedAfter ( optional string )

将结果限制为下载开始时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之后的 DownloadItem。

endedBefore ( optional string )

将结果限制为下载结束时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之前的 DownloadItem。

endedAfter ( optional string )

将结果限制为下载结束时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之后的 DownloadItem。

totalBytesGreater ( optional integer )

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

totalBytesLess ( optional integer )

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

filenameRegex ( optional string )

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

urlRegex ( optional string )

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

limit ( optional integer )

返回匹配 DownloadItem（下载项）的最大数目，默认为 1000，设置为 0 则返回所有匹配的 DownloadItem（下载项）。有关如何为结果分页，请参见 search。

orderBy ( optional array of string )

将该数组的元素设置为 DownloadItem 的属性，为搜索结果排序。例如，设置 orderBy: ['startTime'] 将使下载项按开始时间升序排列。如果要降序排列，请在前面使用连字符：'-startTime'。

id ( optional integer )

要查询的 DownloadItem 的标识符。

url ( optional string )

绝对 URL。

filename ( optional string )

绝对本地路径。

danger ( optional DangerType )

表示该下载项是否被识别为安全的或者已知是可疑的。

mime ( optional string )

文件的 MIME 类型。

startTime ( optional string )

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

endTime ( optional string )

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

state ( optional State )

表示下载项处于正在进行、已中断还是已完成的状态。

paused ( optional boolean )

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

error ( optional InterruptReason )

下载项中断的原因。

bytesReceived ( optional integer )

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

totalBytes ( optional integer )

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

fileSize ( optional integer )

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

exists ( optional boolean )

下载的文件是有存在。

callback ( function )

callback 参数应该指定一个如下形式的函数：

function(array of DownloadItem results) {...};

results ( array of DownloadItem )

暂停下载。如果请求成功，下载项将进入暂停状态。否则，runtime.lastError 将包含错误消息。如果下载项不处于活动状态，该调用会失败。

参数

downloadId ( integer )

要暂停的下载项标识符。

callback ( optional function )

暂停请求完成时调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function() {...};

恢复已暂停的下载。如果请求成功，下载项将继续进行，不再处于暂停状态。否则，runtime.lastError 将包含错误消息。如果下载项不处于活动状态，该调用会失败。

参数

downloadId ( integer )

要恢复的下载项标识符。

callback ( optional function )

恢复请求完成后调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function() {...};

取消下载。回调函数运行时，下载已取消、已完成、已中断或者不再存在。

参数

downloadId ( integer )

要取消的下载项标识符。

callback ( optional function )

取消请求完成后调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function() {...};

获取指定下载项的图标。对于新的下载项，文件图标将在 onCreated 事件收到后才可用。在下载进行时该函数返回的图像可能与下载完成后返回的图像不同。获取图标的方式取决于平台，通过查询下层操作系统或工具包的方式进行。因此，返回的图标取决于各种因素，包括下载状态、平台、已注册的文件类型以及视觉主题。如果无法确定文件图标，runtime.lastError 将会包含错误消息。

参数

downloadId ( integer )

下载项的标识符。

options ( optional object )

属性

size ( optional integer )

图标大小。返回图标的大小为 size×size 像素，图标的默认大小为 32×32 像素。有效的值包括 16 和 32。

callback ( function )

调用时传递代表下载项的图标。

callback 参数应该指定一个如下形式的函数：

function(string iconURL) {...};

iconURL ( optional string )

如果 DownloadItem（下载项）已完成则立即打开下载的文件，否则通过 runtime.lastError 返回错误。该方法除了需要 "downloads" 权限外还需要 "downloads.open" 权限。项目第一次打开时将产生 onChanged 事件。

参数

downloadId ( integer )

已下载文件的标识符。

在文件管理器中，打开已下载文件所在的文件夹并显示它。

参数

downloadId ( integer )

已下载文件的标识符。

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

从历史记录中删除匹配的 DownloadItem（下载项），但不会删除已下载的文件，匹配 query 的每一个 DownloadItem 都会产生一次 onErased 事件，然后调用 callback。

参数

query ( object )

属性

query ( optional array of string )

这一搜索条目数组将结果限制为文件名（filename）或 URL 包含所有不以减号（'-'）开始的搜索条目并且不包含所有以减号（'-'）开始的搜索条目。

startedBefore ( optional string )

将结果限制为下载开始时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之前的 DownloadItem。

startedAfter ( optional string )

将结果限制为下载开始时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之后的 DownloadItem。

endedBefore ( optional string )

将结果限制为下载结束时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之前的 DownloadItem。

endedAfter ( optional string )

将结果限制为下载结束时间在给定时间（以 1970 年 1 月 1 日午夜以来所经过的毫秒数表示）之后的 DownloadItem。

totalBytesGreater ( optional integer )

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

totalBytesLess ( optional integer )

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

filenameRegex ( optional string )

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

urlRegex ( optional string )

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

limit ( optional integer )

返回匹配 DownloadItem（下载项）的最大数目，默认为 1000，设置为 0 则返回所有匹配的 DownloadItem（下载项）。有关如何为结果分页，请参见 search。

orderBy ( optional array of string )

将该数组的元素设置为 DownloadItem 的属性，为搜索结果排序。例如，设置 orderBy: ['startTime'] 将使下载项按开始时间升序排列。如果要降序排列，请在前面使用连字符：'-startTime'。

id ( optional integer )

要查询的 DownloadItem 的标识符。

url ( optional string )

绝对 URL。

filename ( optional string )

绝对本地路径。

danger ( optional DangerType )

表示该下载项是否被识别为安全的或者已知是可疑的。

mime ( optional string )

文件的 MIME 类型。

startTime ( optional string )

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

endTime ( optional string )

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

state ( optional State )

表示下载项处于正在进行、已中断还是已完成的状态。

paused ( optional boolean )

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

error ( optional InterruptReason )

下载项中断的原因。

bytesReceived ( optional integer )

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

totalBytes ( optional integer )

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

fileSize ( optional integer )

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

exists ( optional boolean )

下载的文件是有存在。

callback ( optional function )

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function(array of integer erasedIds) {...};

erasedIds ( array of integer )

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

参数

downloadId ( integer )

callback ( optional function )

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function() {...};

提示用户接受有风险的下载，不会自动接受有风险的下载。如果下载项被接受，将产生 onChanged 事件，否则什么都不会发生。当所有数据都获取至临时文件后，如果下载项没有风险或者已被接受，该临时文件将被重命名为目标文件名，state 更改为 'complete'，并产生 onChanged 事件。

参数

downloadId ( integer )

DownloadItem 的标识符。

callback ( optional function )

风险提示对话框关闭时调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数：

function() {...};

开始将已下载的文件拖动到另一个应用程序，在 JavaScript 的 ondragstart 事件处理程序中调用。

参数

downloadId ( integer )

启用或禁用窗口底部与当前浏览器的用户配置文件相关联的灰色下载框，只要有至少一个扩展程序禁用它则下载框就会被禁用，在其他扩展程序禁用下载框时启用它会导致错误，通过 runtime.lastError 返回。除了 "downloads" 权限以外还需要 "downloads.shelf" 权限。

参数

enabled ( boolean )

下载开始时产生该事件，并传递 DownloadItem 对象。

function(DownloadItem downloadItem) {...};

当下载项从历史记录中删除时产生，并传递 downloadId。

function(integer downloadId) {...};

除 bytesReceived 和 estimatedEndTime 以外，当某个 DownloadItem（下载项）的任何属性更改时，会产生该事件，并传递 downloadId 以及描述属性更改的对象。

function(object downloadDelta) {...};

在确定文件名的过程中，扩展程序有机会修改目标 DownloadItem.filename（文件名）。每一个扩展程序不能为该事件注册一个以上的监听器，每个监听器必须恰好调用一次 suggest，既可以是同步地，也可以是异步地。如果监听器异步地调用 suggest，它必须返回 true。如果监听器既没有同步地调用 suggest，也没有返回 true，则会自动调用 suggest。在所有监听器调用 suggest 前，DownloadItem（下载项）不会完成。监听器应该不传递任何参数调用 suggest，允许下载项使用 downloadItem.filename 作为它的文件名，或者向 suggest 传递一个 suggestion 对象，修改目标文件名。如果不止一个扩展程序修改文件名，最后安装并且向 suggest 传递 suggestion 对象的扩展程序优先。为了避免哪个扩展程序优先造成的混淆，用户不应该安装可能会导致冲突的扩展程序。如果下载由 download 发起，并且在 MIME 类型和待定文件名确定前就指定了文件名，请将 filename 传递给 download。

function(DownloadItem downloadItem, function suggest) {...};