HTML атрибут download
Атрибут HTML download указывает, что целевой файл будет загружен при клике на гиперссылку. Узнайте, на каких элементах он используется.
Атрибут HTML download сообщает браузеру, что нужно скачать связанный ресурс как файл, а не переходить к нему. По умолчанию клик по ссылке на PDF, изображение или текстовый файл открывает его в браузере; добавление download заставляет браузер открыть диалог «Сохранить как». Атрибут добавляется к гиперссылке, и ему можно опционально задать значение, предлагающее имя для сохраняемого файла.
Когда использовать? Используйте download, когда ссылка ведёт на файл, который пользователь должен сохранить, а не просматривать — PDF-отчёт, экспорт в CSV, изображение из <canvas>, ZIP-архив или любое действие типа «сохранить это». Атрибут работает только при наличии атрибута href.
Атрибут download можно использовать на следующих элементах: <a> и <area>.
Предложение имени файла
Значение атрибута задаёт имя скачиваемого файла. Браузер использует его в точности так, как указано, без автоматического добавления расширения — поэтому указывайте расширение самостоятельно. Если значение не указано, браузер использует исходное имя файла из URL (или имя, определённое из ответа сервера).
<!-- 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>Переопределение имени файла особенно удобно, когда сервер хранит файлы под хэшированными или нечитаемыми именами, а пользователю нужно получить понятное, удобочитаемое имя.
Синтаксис
<a href="url" download="filename">link text</a>Значение filename необязательно. <a href="url" download> тоже работает и сохраняет исходное имя.
Пример использования атрибута HTML download на элементе <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>Ограничение одного источника
Это наиболее распространённая причина, по которой download «не работает». По соображениям безопасности атрибут download учитывается только для:
- URL одного источника — файл обслуживается с той же схемы, хоста и порта, что и текущая страница.
blob:URL — созданных в JavaScript с помощьюURL.createObjectURL().data:URL — встроенных данных, закодированных непосредственно вhref.
Для стороннего URL (файл, размещённый на другом домене) атрибут игнорируется: браузер просто переходит к ресурсу, как если бы download не было. Переопределение имени файла тоже отбрасывается. Таким образом, <a href="https://other-site.com/file.pdf" download="report.pdf"> не сохранит report.pdf — он просто откроет удалённый файл.
Обходное решение: получить файл и создать blob URL
Чтобы принудительно загрузить файл со стороннего источника (при условии, что удалённый сервер разрешает это через CORS), нужно загрузить его в память, обернуть в blob URL и запустить загрузку с его помощью:
<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>Удалённый сервер должен отправлять разрешающие заголовки CORS (например, Access-Control-Allow-Origin: *), чтобы fetch выполнился успешно.
Генерация загрузок с помощью data: URL
Поскольку data: URL по определению относятся к тому же источнику, можно загружать контент, созданный полностью в браузере, без обращения к серверу — это удобно для экспорта CSV или сохранения рисунка из <canvas> в виде изображения:
<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>Для более крупных файлов предпочтительнее использовать подход с blob URL вместо data: URL, поскольку очень длинные строки data: требуют много памяти, а некоторые браузеры ограничивают их длину.
Использование download на элементе image map area
Атрибут download также работает на элементе <area> внутри карты изображения, благодаря чему отдельные кликабельные области изображения могут загружать разные файлы.
Пример использования атрибута HTML download на элементе <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>