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

瀏覽器相容性