HTMLAreaElement.download — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAreaElement.download

Beschreibung

Die Eigenschaft download der Schnittstelle HTMLAreaElement spiegelt das HTML-Attribut download eines <area>-Elements innerhalb einer Image-Map wider. Ist das Attribut vorhanden, lädt der Browser beim Klick auf den Bereich die unter href angegebene Ressource herunter, statt dorthin zu navigieren.

Der Wert ist ein String. Ein leerer String bedeutet, dass zwar heruntergeladen wird, der Browser den Dateinamen aber selbst bestimmt (aus dem Content-Disposition-Header, der URL oder dem MIME-Typ). Ein nicht leerer String dient als Vorschlag für den Dateinamen. Ungültige Zeichen wie / oder \ ersetzt der Browser dabei.

Praktisch ist die Eigenschaft bei klickbaren Grafiken wie Landkarten, Produktbildern oder Infografiken, deren Bereiche auf herunterladbare Dateien verweisen (PDF-Datenblätter, Bilder in hoher Auflösung, CSV-Exporte). Per JavaScript lässt sich der Dateiname dynamisch anpassen, zum Beispiel mit einem Datum oder der Benutzersprache.

Wird der Eigenschaft ein Wert zugewiesen, setzt der Browser das Attribut download entsprechend. Um den Download-Modus ganz abzuschalten, muss das Attribut mit removeAttribute('download') entfernt werden. Das Setzen eines leeren Strings entfernt es nicht.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des download-Attributs. Fehlt das Attribut, ist das Ergebnis ein leerer String "". Mit hasAttribute('download') unterscheidet man „Attribut fehlt“ von „Attribut ist leer“.

Beispiele

Dateinamen eines Bereichs auslesen

// HTML:
// <img src="karte.png" usemap="#regionen" alt="Karte">
// <map name="regionen">
//   <area id="nord" shape="rect" coords="0,0,200,100"
//         href="/files/nord.pdf" download="Region-Nord.pdf" alt="Nord">
// </map>

const area = document.getElementById('nord');
console.log(area.download);
console.log(area.hasAttribute('download'));

Region-Nord.pdf true

Dateinamen dynamisch mit Datum setzen

const area = document.querySelector('area[href$=".csv"]');

const datum = new Date().toISOString().slice(0, 10);
area.download = `export-${datum}.csv`;

console.log(area.getAttribute('download'));

export-2024-05-17.csv

Download-Modus ein- und ausschalten

const area = document.querySelector('#nord');

const setzeDownload = (el, aktiv, name = '') => {
  if (aktiv) {
    el.download = name; // leerer String: Browser wählt Namen
  } else {
    el.removeAttribute('download'); // normale Navigation
  }
};

setzeDownload(area, false);
console.log(area.hasAttribute('download'), JSON.stringify(area.download));

setzeDownload(area, true);
console.log(area.hasAttribute('download'), JSON.stringify(area.download));

false "" true ""

Blob-Inhalt über einen Bereich herunterladen

const area = document.querySelector('#nord');

const daten = [['Region', 'Umsatz'], ['Nord', 12500]]
  .map((zeile) => zeile.join(';'))
  .join('\n');

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

area.href = url;
area.download = 'umsatz-nord.csv';

// Speicher nach dem Klick wieder freigeben
area.addEventListener('click', () => {
  setTimeout(() => URL.revokeObjectURL(url), 1000);
}, { once: true });

// Wichtig · Fallstricke

Same-Origin-Beschränkung: download wirkt nur bei Ressourcen derselben Herkunft sowie bei blob:- und data:-URLs. Bei Ressourcen anderer Herkunft ignorieren die Browser das Attribut meist und navigieren normal. Dann muss der Server Content-Disposition: attachment senden.
Serverseitiger Vorrang: Gibt der Server einen Dateinamen per Content-Disposition vor, hat dieser in der Regel Vorrang vor dem Wert von download.
Leerer String ≠ entfernt: area.download = '' lässt das Attribut bestehen, es wird also weiterhin heruntergeladen. Zum Deaktivieren removeAttribute('download') verwenden.
Ohne href keine Wirkung: Ein <area> ohne href ist kein Link, download bleibt dann folgenlos.
Sandbox: In <iframe sandbox> sind Downloads nur mit allow-downloads erlaubt.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Safari kann download erst ab Version 10.1, der Internet Explorer gar nicht. Mobile Browser, besonders iOS, öffnen manche Dateitypen trotzdem in einer Vorschau.
Speicher: Mit URL.createObjectURL() erzeugte URLs nach dem Download mit URL.revokeObjectURL() wieder freigeben.

Siehe auch

HTMLAreaElement.hostname HTMLAreaElement.coords HTMLAreaElement.password HTMLAreaElement.alt HTMLAreaElement.host