HTML download-Attribut

Das HTML-Attribut download weist den Browser an, die verlinkte Ressource als Datei herunterzuladen, anstatt zu ihr zu navigieren. Standardmäßig öffnet ein Klick auf einen Link zu einer PDF-, Bild- oder Textdatei diese im Browser; durch Hinzufügen von download wird stattdessen ein „Speichern unter"-Download erzwungen. Das Attribut wird einem Hyperlink hinzugefügt, und optional kann ihm ein Wert gegeben werden, um einen Dateinamen für die gespeicherte Datei vorzuschlagen.

Wann sollte man es verwenden? Greifen Sie auf download zurück, wenn der Link auf eine Datei zeigt, die der Nutzer behalten und nicht ansehen soll — einen PDF-Bericht, einen generierten CSV-Export, ein aus einem <canvas> gespeichertes Bild, ein ZIP-Archiv oder jede andere „Diese Datei speichern"-Aktion. Es wird nur verwendet, wenn das href-Attribut gesetzt ist.

Das Attribut download kann auf den folgenden Elementen verwendet werden: <a> und <area>.

Einen Dateinamen vorschlagen

Der Wert des Attributs gibt den Namen der heruntergeladenen Datei an. Der Browser verwendet den Wert genau so, wie er eingegeben wurde, ohne automatisch eine Dateiendung hinzuzufügen — geben Sie die Endung daher selbst an. Wird der Wert weggelassen, greift der Browser auf den ursprünglichen Dateinamen aus der URL zurück (oder auf einen aus der Antwort abgeleiteten Namen).

<!-- Saves with the server's original filename -->
<a href="/files/2024-q4-9f8a7b.pdf" download>Download report</a>

<!-- Overrides the filename: saves as "report.pdf" -->
<a href="/files/2024-q4-9f8a7b.pdf" download="report.pdf">Download report</a>

Die Überschreibung des Dateinamens ist besonders praktisch, wenn Ihr Server Dateien unter gehashten oder kryptischen Namen speichert, Sie dem Nutzer aber einen benutzerfreundlichen, lesbaren Dateinamen bereitstellen möchten.

Syntax

<a href="url" download="filename">link text</a>

Der Wert filename ist optional. <a href="url" download> funktioniert ebenfalls und behält den ursprünglichen Namen.

Beispiel des HTML download-Attributs am `<a>`-Element:

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <h1>Click on the  logo to download it:</h1>
    <p>
      <a href="/uploads/media/default/0001/01/0710cad7a1017902166203def268a0df2a5fd545.png" download="w3docs-logo.png">
        <img src="/uploads/media/default/0001/01/0710cad7a1017902166203def268a0df2a5fd545.png" alt="W3Docs" width="190" height="45" />
      </a>
    </p>
  </body>
</html>

Probier es selbst »

Die Same-Origin-Einschränkung

Dies ist der häufigste Grund, warum download „nicht funktioniert". Aus Sicherheitsgründen wird das Attribut download nur für Folgendes berücksichtigt:

Same-Origin-URLs — die Datei wird vom selben Schema, Host und Port wie die aktuelle Seite bereitgestellt.
blob:-URLs — in JavaScript mit URL.createObjectURL() erstellt.
data:-URLs — direkt in href eingebettete Inline-Daten.

Bei einer Cross-Origin-URL (eine Datei, die auf einer anderen Domain gehostet wird) wird das Attribut ignoriert: Der Browser navigiert einfach zur Ressource, als wäre download nicht vorhanden. Die Überschreibung des Dateinamens wird ebenfalls verworfen. So wird <a href="https://other-site.com/file.pdf" download="report.pdf"> nicht report.pdf speichern — es öffnet lediglich die Remote-Datei.

Workaround: Datei abrufen und eine Blob-URL erstellen

Um den Download einer Cross-Origin-Datei zu erzwingen (vorausgesetzt, der Remote-Server erlaubt dies via CORS), laden Sie sie in den Speicher, verpacken Sie sie in eine Blob-URL und lösen Sie damit einen Download aus:

<button id="dl">Download remote PDF</button>

<script>
  document.getElementById('dl').addEventListener('click', async () => {
    const response = await fetch('https://other-site.com/file.pdf');
    const blob = await response.blob();
    const blobUrl = URL.createObjectURL(blob);

    const a = document.createElement('a');
    a.href = blobUrl;
    a.download = 'report.pdf'; // honored, because blob: is allowed
    document.body.appendChild(a);
    a.click();
    a.remove();

    URL.revokeObjectURL(blobUrl); // free the memory
  });
</script>

Der Remote-Server muss freizügige CORS-Header senden (zum Beispiel Access-Control-Allow-Origin: *), damit der fetch-Aufruf erfolgreich ist.

Downloads mit `data:`-URLs generieren

Da data:-URLs per Definition same-origin sind, können Sie Inhalte, die vollständig im Browser erstellt wurden, herunterladen, ohne einen Server-Roundtrip durchzuführen — nützlich für CSV-Exporte oder das Speichern einer <canvas>-Zeichnung als Bild:

<a id="csv" download="export.csv">Download CSV</a>
<canvas id="c" width="100" height="100"></canvas>
<a id="img" download="drawing.png">Save drawing</a>

<script>
  // 1. A generated CSV file
  const csv = 'Name,Score\nAlice,90\nBob,85';
  document.getElementById('csv').href =
    'data:text/csv;charset=utf-8,' + encodeURIComponent(csv);

  // 2. A canvas saved as a PNG (toDataURL returns a data: URL)
  const canvas = document.getElementById('c');
  document.getElementById('img').href = canvas.toDataURL('image/png');
</script>

Für größere Dateien ist der Blob-URL-Ansatz gegenüber data:-URLs vorzuziehen, da sehr lange data:-Strings speicherintensiv sind und einige Browser deren Länge begrenzen.

download auf einem Bildkarten-Bereich verwenden

Das Attribut download funktioniert auch auf dem Element <area> innerhalb einer Bildkarte, sodass einzelne anklickbare Bereiche eines Bildes jeweils eine andere Datei herunterladen können.

Beispiel des HTML download-Attributs am `<area>`-Element:

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <p>Click on one of the HTML, CSS or PHP logo and download it:</p>
    <img src="/uploads/media/news_gallery/0001/01/thumb_316_news_gallery_list.jpeg"  width="250" height="150" alt="block" usemap="#blockmap" />
    <map name="blockmap">
      <area shape="circle" coords="50,32,25" alt="html" href="/uploads/media/book_gallery/0001/01/d450f0358f947dffb3af91195c3002600d74101b.png" download />
      <area shape="circle" coords="218,115,25" alt="css" href="/uploads/media/book_gallery/0001/01/25521e981b34da57c8f51baddc5b76351b855818.png" download />
      <area shape="circle" coords="195,32,28" alt="php" href="/uploads/media/book_gallery/0001/01/4bbee6698c4884f25c46010d61b658dd62d2c04f.png" download />
    </map>
  </body>
</html>

Probier es selbst »

Übungen

Übung

Was bewirkt das HTML download-Attribut?

Es weist den Browser an, die verlinkte Ressource herunterzuladen, anstatt zu ihr zu navigieren.Es startet einen Countdown, bis der Download beginnt.Wenn ein Wert angegeben wird, schlägt es einen Dateinamen für die heruntergeladene Datei vor.Es funktioniert bei Cross-Origin-URLs genauso wie bei Same-Origin-URLs.Es löst beim Klick ein JavaScript-'download'-Ereignis aus.