Attributo download in HTML

L'attributo HTML download indica al browser di scaricare la risorsa collegata come file anziché navigarvi. Per impostazione predefinita, fare clic su un collegamento a un PDF, un'immagine o un file di testo lo apre nel browser; aggiungendo download si forza invece un download con la finestra "Salva come". Si aggiunge a un collegamento ipertestuale e si può facoltativamente assegnargli un valore per suggerire un nome file per il file salvato.

Quando usarlo? Utilizza download quando il collegamento punta a un file che l'utente dovrebbe conservare piuttosto che visualizzare — un report in PDF, un'esportazione CSV generata, un'immagine salvata da un <canvas>, un archivio ZIP, o qualsiasi azione "salva questo". Viene usato solo se l'attributo href è impostato.

Puoi usare l'attributo download sui seguenti elementi: <a> e <area>.

Suggerire un nome file

Il valore dell'attributo specifica il nome del file scaricato. Il browser usa il valore esattamente come digitato, senza aggiungere automaticamente un'estensione — quindi includi tu stesso l'estensione. Se il valore viene omesso, il browser ricade sul nome file originale dall'URL (o uno dedotto dalla risposta).

<!-- 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>

La sostituzione del nome file è particolarmente utile quando il server archivia i file con nomi hash o criptici, ma si desidera che l'utente riceva un nome file semplice e leggibile.

Sintassi

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

Il valore filename è facoltativo. Anche <a href="url" download> funziona e mantiene il nome originale.

Esempio dell'attributo HTML download usato sull'elemento `<a>`:

<!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>

Provalo tu stesso »

La restrizione della stessa origine

Questa è la ragione più comune per cui download "non funziona". Per motivi di sicurezza, l'attributo download viene rispettato solo per:

URL della stessa origine — il file è servito dallo stesso schema, host e porta della pagina corrente.
URL blob: — creati in JavaScript con URL.createObjectURL().
URL data: — dati inline codificati direttamente nell'href.

Per un URL cross-origin (un file ospitato su un altro dominio), l'attributo viene ignorato: il browser naviga semplicemente verso la risorsa come se download non ci fosse. Anche la sostituzione del nome file viene ignorata. Quindi <a href="https://other-site.com/file.pdf" download="report.pdf"> non salverà report.pdf — aprirà semplicemente il file remoto.

Soluzione alternativa: recupera il file e crea un URL blob

Per forzare il download di un file cross-origin (supponendo che il server remoto lo consenta tramite CORS), recuperalo in memoria, incapsulalo in un URL blob e avvia un download con quello:

<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>

Il server remoto deve inviare intestazioni CORS permissive (ad esempio Access-Control-Allow-Origin: *) affinché il fetch abbia successo.

Generare download con URL `data:`

Poiché gli URL data: sono per definizione della stessa origine, è possibile scaricare contenuti creati interamente nel browser senza alcuna comunicazione con il server — utile per esportazioni CSV o per salvare un disegno da <canvas> come immagine:

<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>

Per file di grandi dimensioni, preferisci l'approccio con URL blob rispetto agli URL data:, poiché stringhe data: molto lunghe richiedono molta memoria e alcuni browser ne limitano la lunghezza.

Usare download su un'area di una mappa immagine

L'attributo download funziona anche sull'elemento <area> all'interno di una mappa immagine, in modo che le singole regioni cliccabili di un'immagine possano ciascuna scaricare un file diverso.

Esempio dell'attributo HTML download usato sull'elemento `<area>`:

<!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>

Provalo tu stesso »

Esercitazione

Pratica

Cosa fa l'attributo HTML download?

Dice al browser di scaricare la risorsa collegata invece di navigarvi.Avvia un conto alla rovescia prima che inizi il download.Quando gli viene assegnato un valore, suggerisce un nome file per il file scaricato.Funziona sugli URL cross-origin nello stesso modo in cui funziona sugli URL della stessa origine.Attiva un evento JavaScript 'download' al clic.