downloads.download()

语法

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

参数

options

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

allowHttpErrors 可选

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

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

body 可选

一个 string，表示请求的 post body。

conflictAction 可选

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

cookieStoreId 可选

下载关联的 上下文身份 的 Cookie 存储区 ID。如果省略，则使用默认 Cookie 存储区。使用此项需要 "cookies" API 权限。有关更多信息，请参阅 使用上下文身份。

filename 可选

一个 string，表示相对于默认下载目录的路径——这提供了您希望文件保存的位置以及您希望使用的文件名。绝对路径、空路径、以点（.）开头和/或结尾的路径组件以及包含反向引用的路径（../）将导致错误。如果省略，此值将默认为已分配给下载文件的文件名，并保存在下载目录内的位置。

headers 可选

如果 URL 使用 HTTP 或 HTTPS 协议，则为一个 object 数组，表示要与请求一起发送的其他 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 中标记为“始终询问保存文件的位置”，或在 about:config 中为 browser.download.useDownloadDir）。

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

url

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

返回值

一个 Promise。如果下载成功启动，则 Promise 将使用新 downloads.DownloadItem 的 id 来 fulfill。否则，Promise 将使用 downloads.InterruptReason 中的错误消息来 reject。

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

示例

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

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);

浏览器兼容性