downloads.download()

options

一个 object，指定您要下载的文件以及您希望设置的有关下载的其他任何偏好。它可以包含以下属性

allowHttpErrors 可选

一个 boolean 标志，即使下载遇到 HTTP 错误也能继续下载。例如，使用此标志可以下载服务器错误页面。默认值为 false。当设置为

• false 时，下载在遇到 HTTP 错误时会被取消。
• true 时，下载在遇到 HTTP 错误时会继续，并且不会报告 HTTP 服务器错误。但是，如果由于文件相关、网络相关、用户相关或其他错误导致下载失败，则会报告该错误。

body 可选

一个 string，表示请求的 POST 主体。

conflictAction 可选

一个字符串，表示如果文件名冲突您想要采取的操作，如 downloads.FilenameConflictAction 类型中定义的那样（如果未指定，则默认为“uniquify”）。

cookieStoreId 可选

与下载关联的 上下文身份 的 Cookie 存储区 ID。如果省略，则使用默认 Cookie 存储区。使用需要“cookies” API 权限。有关详细信息，请参阅 使用上下文身份。

filename 可选

一个 string，表示相对于默认下载目录的文件路径——它提供了您希望将文件保存到的位置以及您希望使用的文件名。绝对路径、空路径、以点 (.) 开头和/或结尾的路径组件以及包含反向引用 (../) 的路径会导致错误。如果省略，此值将默认为已赋予下载文件的名称，以及下载目录的直接内部位置。

headers 可选

如果 URL 使用 HTTP 或 HTTPS 协议，则为一个 array，表示与请求一起发送的额外 HTTP 标头。每个标头都表示为包含键 name 和 value 或 binaryValue 的字典对象。XMLHttpRequest 和 fetch 禁止的标头无法指定，但是，Firefox 70 及更高版本允许使用 Referer 标头。尝试使用禁止的标头会引发错误。

incognito 可选

一个 boolean：如果存在且设置为 true，则将此下载与私密浏览会话相关联。这意味着它只会显示在当前打开的所有私密窗口的下载管理器中。

method 可选

一个 string，表示如果 url 使用 HTTP[S] 协议，则要使用的 HTTP 方法。这可能是“GET”或“POST”。

saveAs 可选

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

如果省略此选项，浏览器将根据用户对此行为的一般偏好来显示或不显示文件选择器（在 Firefox 中，此偏好标记为“始终询问您将文件保存到哪里”在 about:preferences 中，或 browser.download.useDownloadDir 在 about:config 中）。

注意：Android 版 Firefox 如果 saveAs 设置为 true，则会引发错误。当 saveAs 为 false 或未包含时，该参数将被忽略。

url

一个 string，表示要下载的 URL。

一个 Promise。如果下载成功启动，则 promise 将使用新 downloads.DownloadItem 的 id 完成。否则，promise 将使用来自 downloads.InterruptReason 的错误消息被拒绝。

如果您使用 URL.createObjectURL() 下载在 JavaScript 中创建的数据，并且您希望稍后撤销对象 URL（使用 revokeObjectURL）（强烈建议这样做），您需要在下载完成后执行此操作。为此，请监听 downloads.onChanged 事件。

以下代码段尝试下载一个示例文件，还指定一个文件名和保存位置，以及 uniquify 作为 conflictAction 选项的值。

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

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

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

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

downloading.then(onStartedDownload, onFailed);