File Preview

<sf-file-preview> показывает один уже выбранный или прикреплённый файл: значок или миниатюру, имя, размер и две кнопки — скачать и удалить. Элемент строится на классах компонента Предпросмотр файла. Выбирает и загружает файлы Smart-загрузка файлов.

Пример

<div class="flex flex-col gap-2">
  <sf-file-preview file-name="Отчёт за квартал.pdf" file-size="1,2 МБ" icon="picture_as_pdf" download-label="Скачать: Отчёт за квартал.pdf" remove-label="Удалить: Отчёт за квартал.pdf"></sf-file-preview>
  <sf-file-preview surface kind="image" file-name="Логотип.svg" file-size="2 КБ" image-url="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96'%3E%3Crect width='100%25' height='100%25' fill='%239bbcff'/%3E%3C/svg%3E" download-action="false" remove-label="Удалить: Логотип.svg"></sf-file-preview>
</div>

Применение

Имя, размер и превью

file-name — видимое имя файла, file-size — размер готовым текстом («1,2 МБ»); компонент его не вычисляет. Слева показывается значок из icon (по умолчанию description) или миниатюра. kind решает, что именно:

• auto — миниатюра, если mime-type начинается с image/ или адрес (image-url, затем href, затем имя файла) оканчивается расширением изображения; иначе значок;
• image — всегда миниатюра из image-url, а без него — из href;
• icon — всегда значок.

Для адреса без расширения, например data: или адреса хранилища, задайте kind="image" явно, как во второй строке примера. surface добавляет строке фон — для файла, который стоит отдельно, а не в списке.

Действия

download-action="false" и remove-action="false" убирают одну кнопку, actions="false" — обе. disabled выключает кнопки.

Нажатие на кнопку отправляет всплывающее событие с возможностью отмены: sf-file-preview:download или sf-file-preview:remove. В event.detail:

Если событие скачивания не отменено и задан href, компонент сам переходит по адресу: при download (по умолчанию) браузер сохраняет файл под именем из file-name, при download="false" открывает его в окне из target (по умолчанию _blank). Удаление — только намерение: строку убирает приложение, когда удаление подтверждено.

const file = document.querySelector('sf-file-preview');
file.onRemove(async (event) => {
  if (await api.deleteAttachment(event.detail.value.href)) file.remove();
});
file.onDownload((event) => {
  event.preventDefault();
  api.downloadAttachment(event.detail.value);
});

getValue() возвращает те же данные, что приходят в event.detail.value.

Доступность

• Пока у строки есть кнопки, она — группа (role="group"), названная именем файла; aria-label заменяет это имя.
• Кнопки названы «Скачать файл» и «Удалить файл» на русской странице и «Download file», «Remove file» на остальных. В списке из нескольких файлов такие имена одинаковы: передайте в download-label и remove-label имя с названием файла, как в примере.
• Значок и миниатюра декоративны; файл называет видимый текст.
• После удаления строки верните фокус на соседний файл или на поле выбора файлов: удалённая кнопка фокуса не сохранит.

Справочник API

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

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

Атрибуты

• template — string, по умолчанию default.
• name — string, по умолчанию File.
• file-name — string, по умолчанию File.
• file-size — string, по умолчанию пусто. Размер файла в виде текста, например 12 KB.
• icon — string, по умолчанию description.
• href — string, по умолчанию пусто.
• kind — string, по умолчанию auto, значения: auto, icon, image. Что показывает превью: иконку, само изображение или то, что подходит файлу.
• mime-type — string, по умолчанию пусто.
• image-url — string, по умолчанию пусто.
• avatar-size — string, по умолчанию пусто.
• open — boolean, по умолчанию false.
• surface — boolean, по умолчанию false.
• download — boolean, по умолчанию true.
• target — string, по умолчанию _blank.
• actions — boolean, по умолчанию true.
• download-action — boolean, по умолчанию true.
• remove-action — boolean, по умолчанию true.
• disabled — boolean, по умолчанию false.
• compact — boolean, по умолчанию false. Только ведущий значок высотой со строку списка: изображение или расширение файла в плитке. Для файла в ячейке таблицы.
• aria-label — string, по умолчанию пусто. Пусто — текст на языке страницы (по-английски «File»).
• download-label — string, по умолчанию пусто. Пусто — текст на языке страницы (по-английски «Download file»).
• remove-label — string, по умолчанию пусто. Пусто — текст на языке страницы (по-английски «Remove file»).

Прежние имена:

Методы

• getValue() — возвращает object. Возвращает текущий идентификатор файла и значение для отображения.
• setOpen() — возвращает object. Сеттер для совместимости; действия остаются видимыми.
• toggleOpen() — возвращает object. Переключатель для совместимости; действия остаются видимыми.
• onDownload() — возвращает object. Регистрирует обработчик события скачивания.
• onRemove() — возвращает object. Регистрирует обработчик события удаления.

События

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

• sf-file-preview:download — detail: { action?: any, value?: object }. Запрошено действие скачивания. Всплывает, с composed: true и отменяемое: preventDefault() останавливает встроенный переход по href.
• sf-file-preview:remove — detail: { action?: any, value?: object }. Запрошено действие удаления. Всплывает, с composed: true и отменяемое; компонент сам ничего не удаляет.

Доступность

• Роль: группа (group).
• Доступное имя: обязательно.
• Клавиши: Tab, Enter, Space.
• Фокус: Нативные действия с файлами сами отвечают за отображение focus-visible.

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

<sf-file-preview file-name="File.pdf"></sf-file-preview>

Источник

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

См. также

• Предпросмотр файла — та же строка на классах.
• Smart-загрузка файлов — выбор и загрузка файлов.