Signatur
Beschreibung
Die Eigenschaft downloadRequest des NavigateEvent-Interfaces zeigt, ob eine Navigation ein Download ist. Das ist zum Beispiel der Fall, wenn ein Link mit dem Attribut download angeklickt wird, etwa <a href="bericht.pdf" download="Jahresbericht.pdf">. Dann steht in der Eigenschaft der im Attribut angegebene Dateiname. Bei allen anderen Navigationen ist der Wert null.
Gebraucht wird die Eigenschaft vor allem in Single-Page-Anwendungen, die Navigationen über die Navigation API mit event.intercept() selbst übernehmen. Downloads sollen dabei normalerweise nicht abgefangen werden, sonst würde der Router versuchen, die Datei als Ansicht darzustellen. Deshalb prüft man am Anfang des navigate-Handlers event.downloadRequest !== null und lässt den Browser den Download in diesem Fall ganz normal ausführen.
Wichtig: Hat das Attribut download keinen Wert (<a download>), ist downloadRequest ein leerer String "" und nicht null. Prüfen Sie deshalb immer genau auf null und nicht auf einen „falsy“ Wert.
Rückgabewert
download-Attributs, also der vorgeschlagene Dateiname. Ist das Attribut leer, ist es ein leerer String "". Ist die Navigation kein Download, ist der Wert null.Beispiele
Downloads beim SPA-Routing nicht abfangen
navigation.addEventListener("navigate", (event) => {
// Navigationen, die sich nicht abfangen lassen, übernimmt der Browser
if (!event.canIntercept) return;
// Sprünge zu Ankern und Downloads nicht abfangen
if (event.hashChange || event.downloadRequest !== null) return;
const url = new URL(event.destination.url);
event.intercept({
async handler() {
const res = await fetch(`/partials${url.pathname}`);
document.querySelector("main").innerHTML = await res.text();
}
});
});Angeforderten Dateinamen protokollieren
// HTML: <a href="/files/r-2024.pdf" download="Jahresbericht-2024.pdf">PDF</a>
navigation.addEventListener("navigate", (event) => {
const name = event.downloadRequest;
if (name === null) return;
// Bei leerem download-Attribut ersatzweise den letzten URL-Abschnitt nehmen
const fileName = name || new URL(event.destination.url).pathname.split("/").pop();
console.log(`Download gestartet: ${fileName}`);
});Download nach Rückfrage abbrechen
navigation.addEventListener("navigate", (event) => {
if (event.downloadRequest === null || !event.cancelable) return;
const ok = confirm(`Datei "${event.downloadRequest || "unbenannt"}" herunterladen?`);
if (!ok) {
event.preventDefault(); // Download wird nicht ausgeführt
console.log("Download abgebrochen");
}
});Mit Feature-Erkennung verwenden
if ("navigation" in window) {
navigation.addEventListener("navigate", (event) => {
console.log("Download?", event.downloadRequest !== null);
});
} else {
console.log("Navigation API wird nicht unterstützt");
}// Wichtig · Fallstricke
- Leerer String statt null: Bei
<a download>ohne Wert ist die Eigenschaft"". Die Prüfungif (event.downloadRequest)übersieht solche Downloads. Prüfen Sie immer mit!== null. - Die Eigenschaft ist schreibgeschützt. Den Dateinamen können Sie darüber nicht ändern.
- Der Wert kommt aus dem HTML-Attribut und damit womöglich aus nicht vertrauenswürdigen Inhalten. Fügen Sie ihn nicht ungeprüft per
innerHTMLin die Seite ein, sondern verwenden SietextContent(Schutz vor XSS). - Die Eigenschaft sagt nichts darüber, ob der Download wirklich stattfindet. Der Server kann zum Beispiel mit
Content-Dispositioneinen anderen Dateinamen festlegen, und bei Links zu fremden Ursprüngen ignorieren Browser das Attributdownloadmeist. - Browser-Kompatibilität: Die Navigation API gibt es seit Chromium 102. In Firefox und Safari ist sie erst in neueren Versionen verfügbar. Prüfen Sie vorher mit
"navigation" in window, ob die API vorhanden ist, und sehen Sie einen Ersatzweg vor, etwa Klick-Handler auf Links.