downloads.download()

options

Ein object, das angibt, welche Datei Sie herunterladen möchten und welche anderen Einstellungen Sie bezüglich des Downloads vornehmen möchten. Es kann die folgenden Eigenschaften enthalten:

allowHttpErrors Optional

Ein boolean-Flag, das Downloads ermöglicht, auch wenn sie auf HTTP-Fehler stoßen. Mit diesem Flag lassen sich beispielsweise Serverfehlermeldungen herunterladen. Standardwert ist false. Wenn auf gesetzt:

• false, wird der Download abgebrochen, wenn ein HTTP-Fehler auftritt.
• true, wird der Download fortgesetzt, wenn ein HTTP-Fehler auftritt, und der HTTP-Serverfehler wird nicht gemeldet. Wenn der Download jedoch aufgrund eines Dateifehlers, Netzwerkfehlers, Benutzerfehlers oder eines anderen Fehlers fehlschlägt, wird dieser Fehler gemeldet.

body Optional

Ein string, der den Post-Body der Anfrage darstellt.

conflictAction Optional

Ein String, der die Aktion angibt, die bei einem Dateinamenkonflikt ausgeführt werden soll, wie in der downloads.FilenameConflictAction-Typ definiert (Standard ist "uniquify" wenn nicht angegeben).

cookieStoreId Optional

Die Cookie-Speicher-ID der kontextuellen Identität, mit der der Download verknüpft ist. Wenn nicht angegeben, wird der Standard-Cookie-Speicher verwendet. Die Nutzung erfordert die "cookies" API-Berechtigung. Siehe Arbeiten mit kontextuellen Identitäten für weitere Informationen.

filename Optional

Ein string, der einen Dateipfad relativ zum Standard-Downloads-Verzeichnis darstellt — dies gibt den Speicherort an, wo Sie die Datei speichern möchten, und welchen Dateinamen Sie verwenden möchten. Absolute Pfade, leere Pfade, Pfadkomponenten, die mit einem Punkt beginnen und/oder enden (.) und Pfade, die Rückverweise (../) enthalten, verursachen einen Fehler. Wenn nicht angegeben, wird dieser Wert standardmäßig auf den bereits dem Download zugewiesenen Dateinamen gesetzt und befindet sich unmittelbar innerhalb des Downloads-Verzeichnisses.

headers Optional

Wenn die URL die HTTP- oder HTTPS-Protokolle verwendet, ein array von objects, das zusätzliche HTTP-Header darstellt, die mit der Anfrage gesendet werden sollen. Jeder Header wird als Wörterbuchobjekt dargestellt, das die Schlüssel name und entweder value oder binaryValue enthält. Die Header, die durch XMLHttpRequest und fetch untersagt sind, können nicht angegeben werden. Allerdings ermöglicht Firefox 70 und später die Verwendung des Referer-Headers. Der Versuch, einen verbotenen Header zu verwenden, führt zu einem Fehler.

incognito Optional

Ein boolean: Wenn vorhanden und auf true gesetzt, dann wird dieser Download mit einer privaten Browsersitzung verknüpft. Dies bedeutet, dass er nur im Download-Manager für alle derzeit geöffneten privaten Fenster erscheint.

method Optional

Ein string, der die HTTP-Methode darstellt, die verwendet werden soll, wenn die url das HTTP[S]-Protokoll nutzt. Dies kann entweder "GET" oder "POST" sein.

saveAs Optional

Ein boolean, der angibt, ob ein Dateiauswahldialog angezeigt werden soll, um dem Benutzer die Auswahl eines Dateinamens zu ermöglichen (true), oder nicht (false).

Wenn diese Option nicht angegeben ist, zeigt der Browser je nach allgemeiner Benutzereinstellung für dieses Verhalten den Dateiauswahldialog an oder nicht (in Firefox wird diese Einstellung als "Immer nachfragen, wo Dateien gespeichert werden sollen" in about:preferences oder browser.download.useDownloadDir in about:config bezeichnet).

Hinweis: Firefox für Android gibt einen Fehler aus, wenn saveAs auf true gesetzt ist. Der Parameter wird ignoriert, wenn saveAs false ist oder nicht enthalten ist.

url

Ein string, der die zu herunterladende URL darstellt.

Ein Promise. Wenn der Download erfolgreich gestartet wurde, wird das Promise mit der id des neuen downloads.DownloadItem erfüllt. Andernfalls wird das Promise mit einer Fehlermeldung abgelehnt, die von downloads.InterruptReason stammt.

Wenn Sie URL.createObjectURL() verwenden, um in JavaScript erstellte Daten herunterzuladen und Sie die Objekt-URL später (wie dringend empfohlen) mit revokeObjectURL widerrufen möchten, müssen Sie das tun, nachdem der Download abgeschlossen ist. Um dies zu tun, können Sie das downloads.onChanged-Ereignis nutzen.

Das folgende Beispiel versucht, eine Beispieldatei herunterzuladen, wobei auch ein Dateiname und Speicherort angegeben wird und uniquify als Wert der Option conflictAction verwendet wird.

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