downloads.download()

options

Ein object, das angibt, welche Datei Sie herunterladen möchten, und alle anderen Präferenzen, die Sie für den Download festlegen 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 können beispielsweise Serverfehlermeldungen heruntergeladen werden. Standardwert ist false. Wenn gesetzt auf:

• false, wird der Download abgebrochen, wenn ein HTTP-Fehler auftritt.
• true, geht der Download weiter, wenn ein HTTP-Fehler auftritt, und der HTTP-Serverfehler wird nicht gemeldet. Wenn der Download jedoch aufgrund von datei-, netzwerk-, benutzerbezogenen oder anderen Fehlern fehlschlägt, wird dieser Fehler gemeldet.

body Optional

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

conflictAction Optional

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

cookieStoreId Optional

Die Cookie-Store-ID der kontextuellen Identität, mit der der Download verknüpft ist. Wenn weggelassen, wird der Standard-Cookie-Speicher verwendet. Die Verwendung 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-Download-Verzeichnis darstellt — dies gibt den Speicherort an, an dem die Datei gespeichert werden soll, 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 weggelassen, wird dieser Wert standardmäßig auf den bereits gegebenen Dateinamen der herunterzuladenden Datei und einen Speicherort direkt im Download-Verzeichnis gesetzt.

headers Optional

Wenn die URL das HTTP- oder HTTPS-Protokoll verwendet, ein array von objects, die zusätzliche HTTP-Header darstellen, die mit der Anfrage gesendet werden sollen. Jeder Header wird als ein Wörterbuchobjekt dargestellt, das die Schlüssel name und entweder value oder binaryValue enthält. Die Header, die von XMLHttpRequest und fetch ausgeschlossen sind, können nicht angegeben werden, allerdings ermöglicht Firefox 70 und später die Verwendung des Referer-Headers. Der Versuch, einen nicht erlaubten 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. Das bedeutet, dass er nur im Download-Manager für aktuell geöffnete private Fenster erscheint.

method Optional

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

saveAs Optional

Ein boolean, der angibt, ob ein Dateiauswahldialog angezeigt werden soll, um dem Benutzer zu ermöglichen, einen Dateinamen auszuwählen (true) oder nicht (false).

Wenn diese Option weggelassen wird, zeigt der Browser den Dateiauswahldialog entweder an oder nicht, basierend auf der allgemeinen Benutzereinstellung für dieses Verhalten (in Firefox ist diese Einstellung mit "Immer fragen, wo Dateien gespeichert werden sollen" unter about:preferences bezeichnet oder browser.download.useDownloadDir in about:config).

Hinweis: Firefox für Android erhöht einen Fehler, wenn saveAs auf true gesetzt ist. Der Parameter wird ignoriert, wenn saveAs false oder nicht eingeschlossen ist.

url

Ein string, der die URL repräsentiert, die heruntergeladen werden soll.

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 aus downloads.InterruptReason entnommen wird.

Wenn Sie URL.createObjectURL() verwenden, um in JavaScript erstellte Daten herunterzuladen, und Sie möchten die Objekt-URL später aufheben (mit revokeObjectURL), wie es dringend empfohlen wird, müssen Sie das tun, nachdem der Download abgeschlossen ist. Dazu hören Sie auf das Ereignis downloads.onChanged.

Der folgende Codeabschnitt versucht, eine Beispieldatei herunterzuladen, außerdem wird ein Dateiname und Speicherort angegeben, in dem sie gespeichert werden soll, sowie uniquify als Wert der conflictAction-Option.

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