downloads.download()
Die download()
Funktion der downloads
API lädt eine Datei herunter, basierend auf ihrer URL und weiteren optionalen Präferenzen.
Wenn die URL das HTTP- oder HTTPS-Protokoll verwendet, beinhaltet die Anfrage alle relevanten Cookies, d.h. jene, die für den Hostnamen der URL, das Sicherheitskennzeichen, den Pfad und so weiter gesetzt wurden. Die Standard-Cookies, also die Cookies aus der normalen Browsersitzung, werden verwendet, es sei denn:
- die Option
incognito
wird verwendet, dann werden die Cookies des privaten Browsens verwendet. - die Option
cookieStoreId
wird verwendet, dann werden die Cookies aus dem angegebenen Speicher verwendet.
Wenn sowohl filename
als auch saveAs
angegeben sind, wird der "Speichern unter"-Dialog angezeigt und mit dem filename
ausgefüllt.
Dies ist eine asynchrone Funktion, die ein Promise
zurückgibt.
Syntax
let downloading = browser.downloads.download(
options // object
)
Parameter
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 istfalse
. 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). -
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
vonobjects
, die zusätzliche HTTP-Header darstellen, die mit der Anfrage gesendet werden sollen. Jeder Header wird als ein Wörterbuchobjekt dargestellt, das die Schlüsselname
und entwedervalue
oderbinaryValue
enthält. Die Header, die vonXMLHttpRequest
undfetch
ausgeschlossen sind, können nicht angegeben werden, allerdings ermöglicht Firefox 70 und später die Verwendung desReferer
-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 dieurl
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
auftrue
gesetzt ist. Der Parameter wird ignoriert, wennsaveAs
false
oder nicht eingeschlossen ist. url
-
Ein
string
, der die URL repräsentiert, die heruntergeladen werden soll.
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 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.
Browser-Kompatibilität
BCD tables only load in the browser
Beispiele
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);
Hinweis: Diese API basiert auf der chrome.downloads
API von Chromium.