HTMLAnchorElement.download — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAnchorElement.download

Beschreibung

Die Eigenschaft download spiegelt das gleichnamige HTML-Attribut eines <a>-Elements wider. Ist sie gesetzt, soll der Browser beim Klick die verlinkte Ressource als Datei speichern, statt sie zu öffnen. Der zugewiesene String ist ein Vorschlag für den Dateinamen. Ein leerer String ("") bedeutet: herunterladen, aber den Dateinamen selbst aus URL oder Server-Antwort ableiten.

Besonders nützlich ist die Eigenschaft für Dateien, die im Client erzeugt werden, etwa CSV-Exporte, JSON-Backups, Canvas-Bilder oder generierte PDFs. Dazu erzeugt man mit URL.createObjectURL() eine blob:-URL oder baut eine data:-URL, weist sie href zu, setzt download und löst per click() den Download aus.

Wichtig: Das Attribut greift nur bei gleicher Herkunft (Same-Origin) sowie bei blob:- und data:-URLs. Bei Links auf andere Domains ignorieren moderne Browser den Dateinamen oder das ganze Attribut und navigieren normal. Ein vom Server gesendeter Content-Disposition-Header hat Vorrang vor dem Namen im Attribut.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen der vorgeschlagene Dateiname, z. B. `"bericht.csv"`. Ein leerer String aktiviert den Download ohne festen Namen. Unzulässige Zeichen wie `/` oder `\` ersetzt der Browser.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des download-Attributs. Fehlt das Attribut, ist der Wert ein leerer String "". Ob das Attribut wirklich existiert, prüft man mit hasAttribute('download').

Beispiele

CSV-Export aus Daten im Client erzeugen

const rows = [['Name', 'Punkte'], ['Anna', 42], ['Ben', 37]];
const csv = rows.map(r => r.join(';')).join('\n');

const blob = new Blob([csv], { type: 'text/csv;charset=utf-8' });
const url = URL.createObjectURL(blob);

const a = document.createElement('a');
a.href = url;
a.download = 'punkte.csv';
document.body.append(a);
a.click();
a.remove();

// Speicher wieder freigeben
setTimeout(() => URL.revokeObjectURL(url), 0);
console.log(a.download);

punkte.csv

Canvas-Inhalt als PNG herunterladen

const canvas = document.querySelector('canvas');

canvas.toBlob(blob => {
  const url = URL.createObjectURL(blob);
  const link = Object.assign(document.createElement('a'), {
    href: url,
    download: `zeichnung-${Date.now()}.png`
  });
  link.click();
  URL.revokeObjectURL(url);
}, 'image/png');

Vorhandenen Link auslesen und anpassen

// HTML: <a id="doc" href="/files/handbuch.pdf" download>Handbuch</a>
const link = document.getElementById('doc');

console.log(link.download);                 // leerer String
console.log(link.hasAttribute('download')); // Attribut vorhanden

link.download = 'Handbuch-v2.pdf';
console.log(link.getAttribute('download'));

true Handbuch-v2.pdf

JSON-Backup über data:-URL

const settings = { theme: 'dark', lang: 'de' };
const a = document.createElement('a');
a.href = 'data:application/json;charset=utf-8,' +
  encodeURIComponent(JSON.stringify(settings, null, 2));
a.download = 'einstellungen.json';
a.click();

// Wichtig · Fallstricke

Nur Same-Origin: Bei Links auf andere Origins ignorieren Chrome, Firefox und Safari den Dateinamen oder das Attribut ganz. Fremde Dateien lädt man besser per fetch() mit CORS, wandelt sie in einen Blob um und nutzt dann eine blob:-URL.
Content-Disposition hat Vorrang: Sendet der Server Content-Disposition: attachment; filename=..., verwendet der Browser diesen Namen. Bei inline kann das Attribut je nach Browser überstimmt werden.
Leerer String ist nicht gleich fehlendem Attribut: a.download = '' setzt das Attribut und aktiviert den Download. Zum Abschalten dient a.removeAttribute('download').
Speicherlecks: Jede mit URL.createObjectURL() erzeugte URL mit URL.revokeObjectURL() wieder freigeben, sonst bleibt der Blob im Speicher.
data:-URLs: Sehr große data:-URLs sind langsam und können an Längengrenzen scheitern. Für größere Dateien sind Blobs besser.
Sandbox und Kompatibilität: In <iframe sandbox> sind Downloads nur mit allow-downloads erlaubt. Programmatisches click() kann ohne Nutzeraktion von Pop-up- oder Mehrfach-Download-Schutz blockiert werden. Der Internet Explorer unterstützt das Attribut nicht (dort gab es navigator.msSaveBlob).
Sicherheit: Den Dateinamen niemals ungeprüft aus Benutzereingaben übernehmen. Browser bereinigen zwar Pfadzeichen, irreführende Endungen wie rechnung.pdf.exe bleiben aber möglich.

Siehe auch

HTMLAnchorElement.password HTMLAnchorElement.host HTMLAnchorElement.hostname HTMLAnchorElement.hreflang HTMLAnchorElement.origin