一、说明及权限申请

chrome.downloads API 能够通过扩展程序以编程的方式启动、监听或者是搜索下载相关的信息以及下载具体文件。

权限申请:

 "permissions": [ "downloads"],

二、属性及其值

1、FilenameConflictAction

文件名冲突的处理方式,Enum 类型,可选值包括 uniquifyoverwriteprompt

  • uniquify:如果冲突了在文件后缀的前面加上计数,比如 filename1.jpg, filename2.jpg
  • overwrite: 新文件覆盖旧的文件
  • prompt:用户会受到一个 dialog 确认操作

2、InterruptReason

表示文件下载中断的原因:

"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"

3、DangerType

可选值:

"file", "url", "content", "uncommon", "host", "unwanted", "safe", or "accepted"
  • file: 下载的文件名是可疑的
  • url:已知下载的 URL 是恶意的
  • content:已知下载的内容是恶意的
  • uncommon:下载的 URL 可能是危险的,一般不会选择下载
  • host:从一个恶意主机下载文件
  • unwanted:下载的文件不受欢迎或者是不安全的,能够更改计算机的配置等
  • safe:下载的文件已知没有危险
  • accepted: 用户同意下载危险软件

4、State

Enum 可选值:

"in_progress", "interrupted", or "complete"
  • in_progress: 正在从服务端接受数据中
  • interrupted: 下载中断,出现错误
  • complete: 下载成功且已经完成

三、方法

1、chrome.downloads.download(object options, function callback)

通过一个 URL 下载文件,如果使用的是 HTTP[S] 会将主机的 cookie 带上去。如果同时指定了 filenamesaveAs,会显示 另存为 的对话框,并且使用指定的文件名进行填充。

如果下载成功,会使用新的 DownloadItem 的 download 调用回调。

如果开始下载时出错,则将使用 downloadId = undefined 调用会掉, runtime.lastError 将包含描述性字符串。

错误信息不保证向后兼容,因此扩展程序不能去解析这个错误信息。

下面是最简单的调用方式,初次之外,还可以指定 filename、conflictAction 或者是 method 等等

方法调用:

btn1.onclick = () => {
    const url = document.querySelector('#url').value;
    const options = {
        url
    }
    chrome.downloads.download(options, (res) => {
        console.log(res);
    })
};

结果示例:

可以发现每次默认的文件名冲突就是通过加 counter 的方式解决的

1.jpg

2、chrome.downloads.search(object query, function callback)

查找可供下载的对象,如果参数 query 是空对象,则会查找所有能够下载的对象,如果只需要获取特定的可下载对象,可以通过设置 id 参数。

如果要查找大量项目,可以通过 orderBy:['-startTime'] 设置每页的项目数,并且将 startedAfter 设置为最后一页中最后一项的 startTime。

代码示例:

btn2.onclick = () => {
    const options = { }
    chrome.downloads.search(options, (res) => {
        console.log(res);
    })
};

结果:

2.jpg

如果只是查询 zip 结尾的文件:

btn2.onclick = () => {
    const options = {
        finalUrlRegex: '.zip$'
     }
    chrome.downloads.search(options, (res) => {
        console.log(res);
    })
};

结果:

3.jpg

3、chrome.downloads.pause(integer downloadId, function callback)

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

 chrome.downloads.pause(id, (res) =>{
            console.log(res);
        });

4、chrome.downloads.resume(integer downloadId, function callback)

恢复暂停的下载。如果请求成功,则下载正在进行且取消暂停。否则 runtime.lastError 包含错误消息。如果下载未激活,请求将失败。
扩展程序选项更多

5、chrome.downloads.cancel(integer downloadId, function callback)

取消下载。运行回调时,下载将被取消,完成,中断或不再存在。

四、完整代码仓库

https://github.com/postbird/chrome-extensions-demo/tree/master/demo14-downloads