Download File

<sf-download-file> показывает файл, который можно скачать: иконку, имя и размер. С адресом он становится нативной ссылкой, без адреса — кнопкой, по которой приложение само готовит файл. Оформление совпадает с обычным компонентом «Скачать файл».

Пример

<div class="flex flex-col gap-2 items-cross-start" data-download-demo>
  <sf-download-file file-name="Пример.txt" file-size="15 Б" href="data:text/plain;charset=utf-8,SIMAI%20Framework" download></sf-download-file>
  <sf-download-file file-name="Отчёт за квартал.pdf" file-size="PDF" icon="description"></sf-download-file>
  <sf-download-file file-name="Архив проекта.zip" file-size="120 МБ" disabled></sf-download-file>
  <p class="m-0" role="status" data-download-result>Файл ещё не запрошен.</p>
</div>

document.querySelectorAll('[data-download-demo]').forEach((demo) => {
  const result = demo.querySelector('[data-download-result]');
  demo.addEventListener('sf-download-file:click', (event) => {
    const {href, fileName} = event.detail;
    result.textContent = href
      ? `Браузер скачивает «${fileName}».`
      : `Приложение готовит файл «${fileName}».`;
  });
});

Применение

Ссылка на готовый файл

href с адресом файла рисует ссылку. С download браузер скачивает файл под именем из file-name, а не открывает его. Без download ссылка открывается в target, по умолчанию _blank, с rel="noopener noreferrer".

file-name — видимое имя файла, по умолчанию File.pdf, поэтому задавайте его всегда. file-size — размер, как его прочтёт человек: «2,4 МБ». Если file-size пуст, компонент запрашивает адрес методом HEAD и показывает размер из заголовка Content-Length в английских единицах; передавайте размер сами, когда он известен.

Файл, который готовит приложение

Без href компонент рисует кнопку. Нажатие отправляет событие sf-download-file:click, и приложение собирает файл — отчёт, выгрузку, архив. Пока файл не готов, показывайте это рядом или переключите элемент в disabled.

disabled рисует недоступную кнопку без адреса, даже если href задан. icon меняет иконку перед именем, size — размер по шкале 1/3, 1/2, 1, 2, 3.

Событие sf-download-file:click

Событие отправляется с внутренней ссылки или кнопки и всплывает до document. Его event.detail:

Недоступный элемент события не отправляет.

document.addEventListener('sf-download-file:click', async (event) => {
  if (event.detail.href) return;
  const file = await buildReport();
  saveFile(file, event.detail.fileName);
});

Доступность

• Доступное имя ссылки или кнопки складывается из имени и размера файла. aria-label заменяет его целиком: если задаёте его, включите в него имя файла, например «Скачать отчёт за квартал, PDF, 2,4 МБ».
• Ссылка и кнопка — одна остановка Tab; ссылка срабатывает по Enter, кнопка — по Enter и Space. Иконка скрыта от вспомогательных технологий.
• Ссылка без download открывает новую вкладку. Если это важно, скажите об этом в подписи рядом.
• Когда приложение готовит файл, сообщите о готовности или ошибке в области с role="status": само нажатие ничего не объявляет.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• template — string, по умолчанию default.
• size — string, по умолчанию 1, значения: 1/3, 1/2, 1, 2, 3. Существующая шкала размеров компонентов от компактного до крупного.
• file-name — string, по умолчанию File.pdf. Видимое имя файла и нативное имя для скачивания по умолчанию.
• file-size — string, по умолчанию пусто. Известный размер в удобочитаемом виде. Передавайте, если он доступен, чтобы не определять его.
• icon — string, по умолчанию download. Имя декоративной иконки.
• href — string, по умолчанию пусто. Реальное место ресурса; в доступном состоянии отрисовывает нативную ссылку (a).
• download — boolean, по умолчанию false. Применяет к ссылке нативную семантику скачивания.
• disabled — boolean, по умолчанию false. Отображает отключённую кнопку без действующего адреса перехода.
• target — string, по умолчанию _blank.
• aria-label — string, по умолчанию пусто.

Методы

Публичных методов нет.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• sf-download-file:click — detail: { href?: string, fileName?: string, download?: boolean }. Отправляется один раз для доступного нативного назначения или действия, которым управляет приложение, от отрисованного корня .sf-download-file; всплывает до хост-элемента, не с composed: true и не отменяемое.

Доступность

• Доступное имя: рекомендуется.
• Клавиши: Tab.
• Фокус: Сохраняет видимый фокус на активном элементе управления.

Минимальная разметка

<sf-download-file file-name="Report.pdf" file-size="2.4 MB" href="/files/report.pdf" download></sf-download-file>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/download-file
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-download-file

См. также

• Buttons — действие без файла.