downloads.download()

downloads API 的 download() 函数根据给出的URL和其他首选项下载一个文件。

  • 如果指定的 url 使用HTTP或者HTTPS协议, 那么下载请求将会包含当前为该域名所设置的所有cookie。
  • 如果filenamesaveAs 都已经指定,那么将会弹出“保存为” 对话框,并且默认名称显示为filename.

这是一个异步函数,其返回值为 Promise.

语法

var downloading = browser.downloads.download(
  options                   // object
)

参数

options
一个 object ,用来指定你想要下载的文件和其他想要在下载时设置的首选项。可以包含以下属性:
allowHttpErrors可选
一个 boolean,启用后即使遇到HTTP错误仍然继续下载。 例如,可以使用该标志下载服务错误页面。默认值为false. 当设置为以下值时:
  • false,遇到HTTP错误时下载会被取消。
  • true, 即使遇到HTTP错误也会继续下载,并且不会弹出HTTP服务错误报告。但是,如果下载失败的原因是文件相关,网络相关,用户相关,或者说其他错误,仍然会报错。
body可选
一个 string,代表请求的内容。
conflictAction可选
一个字符串,表示如果存在命名冲突时你希望进行的操作,字符串内容所代表的类型由 downloads.FilenameConflictAction (en-US) 定义(未指定时默认为 "uniquify" )。
filename可选
一个 string ,表示相对默认保存位置的文件路径——这里提供你希望文件保存的位置,和你想要使用的文件名。绝对路径,空路径,以及包含反向引用的路径 (../) 会导致错误产生。 如果省略,该值将默认为已经提供给下载文件的文件名,并且直接保存到下载文件夹中。
headers可选
如果URL使用HTTP或者HTTPS协议, 保存在 array 中的一系列 objects 表示与请求一起发送的额外HTTP请求头。每一个请求头表示为字典对象,包含有关键字 name 还有 valuebinaryValue中的一个。 无法指定 XMLHttpRequestfetch禁止的请求头,但是 Firefox 70 之后允许使用Referer请求头。尝试使用被禁止的请求头会产生一个错误。
incognito可选
一个 boolean:如果被设置为 true,那么这次下载会建立一个隐私浏览会话。 这意味着它只会出现在当前打开的任意隐私窗口的下载管理器。
method可选
一个 string,表示url使用HTTP[S] 协议时使用的HTTP方法。其值可能是 "GET" 或 "POST"。
saveAs可选

一个boolean 指定是(true)否(false)提供一个文件选择对话框允许用户选择文件名。.

如果该选项省略, 浏览器会根据用户对于该行为的偏好设置决定是否提供一个文件选择对话框 (在火狐这项设置标签在about:preferences里为"每次都问您要存到哪" ,或者about:config里 browser.download.useDownloadDir )。

Note: 如果 saveAs 被设置为 true,Firefox for Android 将会引发一个错误。 当 saveAsfalse 或空时这个参数会被忽略.

url
一个 string,表示需要下载的链接地址。

返回值

一个 Promise. 如果成功开始下载,promise会被新创建的downloads.DownloadItemid 填充。否则 promise 会被拒绝并产生一条downloads.InterruptReason (en-US)错误信息.

如果你使用 URL.createObjectURL() 下载由 JavaScript 创建的数据并且之后想要(使用 revokeObjectURL)撤销对象链接(并且强烈推荐这么做),你必须在下载完成后再这么做。监听 downloads.onChanged 事件来判断是否下载完成。

浏览器兼容性

BCD tables only load in the browser

例子

下面这段代码尝试下载一个example文件,同时指定文件名和保存位置,还有 uniquify conflictAction 选项。

function onStartedDownload(id) {
  console.log(`Started downloading: ${id}`);
}

function onFailed(error) {
  console.log(`Download failed: ${error}`);
}

var downloadUrl = "https://example.org/image.png";

var downloading = browser.downloads.download({
  url : downloadUrl,
  filename : 'my-image-again.png',
  conflictAction : 'uniquify'
});

downloading.then(onStartedDownload, onFailed);

Acknowledgements

这个 API 基于 Chromium的 chrome.downloads API.