downloads.download()

Syntax

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

Parameter

options

Ein object, das angibt, welche Datei Sie herunterladen möchten und welche weiteren Einstellungen für den Download gelten sollen. Es kann die folgenden Eigenschaften enthalten:

allowHttpErrors Optional

Ein boolean-Flag, das bewirkt, dass Downloads auch bei HTTP-Fehlern fortgesetzt werden. Damit können beispielsweise Serverfehlerseiten heruntergeladen werden. Der Standardwert ist false. Bei folgenden Werten gilt:

• false: Der Download wird abgebrochen, wenn ein HTTP-Fehler auftritt.
• true: Der Download wird bei einem HTTP-Fehler fortgesetzt, und der HTTP-Serverfehler wird nicht gemeldet. Schlägt der Download jedoch aufgrund eines datei-, netzwerk- oder benutzerbezogenen Fehlers oder eines anderen Fehlers fehl, wird dieser Fehler gemeldet.

body Optional

Ein string, der den Body der POST-Anfrage enthält.

conflictAction Optional

Ein String, der die gewünschte Aktion bei einem Dateinamenskonflikt angibt, wie im Typ downloads.FilenameConflictAction definiert. Wird kein Wert angegeben, ist der Standardwert „uniquify“.

cookieStoreId Optional

Die ID des Cookie-Speichers der kontextbezogenen Identität, der der Download zugeordnet ist. Wird sie weggelassen, wird der Standard-Cookie-Speicher verwendet. Für die Verwendung ist die API-Berechtigung „cookies“ erforderlich. Weitere Informationen finden Sie unter Mit kontextbezogenen Identitäten arbeiten.

filename Optional

Ein string, der einen Dateipfad relativ zum standardmäßigen Downloadverzeichnis angibt. Er legt fest, wo die Datei gespeichert werden soll und welchen Dateinamen sie erhalten soll. Absolute oder leere Pfade, Pfadbestandteile, die mit einem Punkt (.) beginnen und/oder enden, sowie Pfade mit Verweisen auf übergeordnete Verzeichnisse (../) führen zu einem Fehler. Wird die Eigenschaft weggelassen, werden standardmäßig der bereits für die herunterzuladende Datei vorgesehene Dateiname und ein Speicherort direkt im Downloadverzeichnis verwendet.

headers Optional

Wenn die URL das HTTP- oder HTTPS-Protokoll verwendet, ein array von objects, die zusätzliche HTTP-Header für die Anfrage angeben. Jeder Header wird durch ein Dictionary-Objekt mit den Schlüsseln name und entweder value oder binaryValue dargestellt. Header, die durch XMLHttpRequest und fetch verboten sind, können nicht angegeben werden. Firefox 70 und höher erlaubt jedoch die Verwendung des Headers Referer. Der Versuch, einen verbotenen Header zu verwenden, löst einen Fehler aus.

incognito Optional

Ein boolean: Wenn die Eigenschaft vorhanden und auf true gesetzt ist, wird der Download einer privaten Browsersitzung zugeordnet. Das bedeutet, dass er nur im Download-Manager der derzeit geöffneten privaten Fenster angezeigt wird.

method Optional

Ein string, der die zu verwendende HTTP-Methode angibt, wenn url das HTTP[S]-Protokoll verwendet. Der Wert kann entweder „GET“ oder „POST“ sein.

saveAs Optional

Ein boolean, der angibt, ob ein Dateiauswahldialog angezeigt werden soll, damit Benutzer einen Dateinamen auswählen können (true), oder nicht (false).

Wird diese Option weggelassen, entscheidet der Browser anhand der allgemeinen Benutzereinstellung für dieses Verhalten, ob er den Dateiauswahldialog anzeigt. In Firefox heißt diese Einstellung unter about:preferences „Immer fragen, wo Dateien gespeichert werden sollen“ beziehungsweise browser.download.useDownloadDir unter about:config.

url

Ein string, der die URL der herunterzuladenden Datei angibt.

Rückgabewert

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 aus downloads.InterruptReason zurückgewiesen.

Wenn Sie mit URL.createObjectURL() in JavaScript erzeugte Daten herunterladen und die Objekt-URL später mit revokeObjectURL freigeben möchten – was dringend empfohlen wird –, müssen Sie dies nach Abschluss des Downloads tun. Registrieren Sie dazu einen Listener für das Ereignis downloads.onChanged.

Beispiele

Der folgende Codeausschnitt versucht, eine Beispieldatei herunterzuladen. Er gibt außerdem einen Dateinamen und einen Speicherort sowie uniquify als Wert der Option conflictAction an.

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

Browser-Kompatibilität