Пустое состояние

<sf-empty-state> — то, что список, панель или страница показывает, когда показать нечего. Одна причина — один вид: значок, заголовок, пояснение и, если нужно, действие.

Пример

<div class="grid grid-col-1 md:grid-col-2 gap-3">
  <div class="p-2 radius-2 border border-outline-variant"><sf-empty-state kind="no-data" size="1/2" heading-level="4"></sf-empty-state></div>
  <div class="p-2 radius-2 border border-outline-variant"><sf-empty-state kind="nothing-found" size="1/2" heading-level="4"></sf-empty-state></div>
  <div class="p-2 radius-2 border border-outline-variant"><sf-empty-state kind="no-access" size="1/2" heading-level="4"></sf-empty-state></div>
  <div class="p-2 radius-2 border border-outline-variant flex flex-col gap-2">
    <sf-empty-state id="empty-state-error" kind="error" size="1/2" heading-level="4"></sf-empty-state>
    <output class="text-1/2 color-on-surface-variant" id="empty-state-log" aria-live="polite"></output>
  </div>
  <div class="p-2 radius-2 border border-outline-variant flex flex-col gap-1 md:col-span-2">
    <span class="text-1/2 color-on-surface-variant">Компактная форма — в списке поиска</span>
    <sf-empty-state kind="nothing-found" layout="inline" text="Ничего не найдено по «счёт»"></sf-empty-state>
  </div>
</div>

const failed = document.querySelector('#empty-state-error');
const log = document.querySelector('#empty-state-log');
failed?.addEventListener('sf-empty-state-action', (event) => {
  if (event.detail.id === 'retry') log.textContent = 'Приложение повторяет загрузку';
});

Применение

Причина

Тексты по умолчанию следуют языку страницы. icon, title и text заменяют их, когда причина конкретнее: «Машин пока нет», «Создайте первую». title здесь — общий атрибут HTML, поэтому браузер показывает его и всплывающей подсказкой при наведении на блок.

Размер и место

• size="1/2" — внутри таблицы или панели;
• size="1" — по умолчанию;
• size="2" — целая страница.

От размера зависят значок, роль заголовка, текст и промежутки. Ширина — не больше 28rem, её меняет переменная --sf-empty-state-max-inline-size.

heading-level (от 2 до 6, по умолчанию 3) ставит заголовок на нужный уровень структуры страницы: на целой странице это обычно 2, в панели — 3 или 4. Вид заголовка от уровня не зависит.

Компактная форма

layout="inline" (и всегда size="1/3") — одна строка высотой с контрол 1/2 с отступом строки списка: маленький значок, текст (text, а без него — заголовок причины) и не больше одного действия-ссылки, без заголовка. Её ставят в списки меню, выпадающих списков и поиска; внутри listbox или меню — вне элемента списка, чтобы она не считалась пунктом.

<sf-empty-state kind="nothing-found" layout="inline" text="Ничего не найдено по «счёт»"></sf-empty-state>

Действия

Действия передают в слот actions — любые sf-button — или свойством actions со списком [{id, text, appearance}]. Кнопки из свойства рисуются в размере компонента и сообщают sf-empty-state-action с {id}. У kind="error" без своих действий есть «Повторить» (id: retry). Пустой массив actions = [] и кнопки в слоте actions тоже считаются своими действиями, и «Повторить» не появится; чтобы вернуть его, присвойте actions = null.

<sf-empty-state kind="nothing-found" size="1/2" heading-level="4"></sf-empty-state>
<sf-empty-state kind="error" id="failed"></sf-empty-state>
<script>
  failed.addEventListener('sf-empty-state-action', (event) => {
    if (event.detail.id === 'retry') reload();
  });
</script>

Доступность

• live="auto" (по умолчанию): «Ничего не найдено» и ошибка объявляются вежливо (role="status"), остальные причины не объявляются. live="alert" — для ошибки, вызванной действием человека, live="off" — когда объявляет сам хост.
• Заголовок — настоящий заголовок уровня heading-level, поэтому состояние видно в оглавлении страницы.
• Значок декоративный.

Справочник API

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

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

Атрибуты

• kind — string, по умолчанию no-data, значения: no-data, nothing-found, no-access, error. Причина: от неё зависят значок, заголовок и текст по умолчанию, а у error — действие «Повторить».
• size — string, по умолчанию 1, значения: 1/3, 1/2, 1, 2. 1/3 — всегда компактная форма; 1/2 — внутри таблицы или панели, 2 — для целой страницы; от размера зависят значок, роль заголовка, текст и промежутки.
• icon — string, по умолчанию пусто.
• title — string, по умолчанию пусто.
• text — string, по умолчанию пусто.
• heading-level — string, по умолчанию 3, значения: 2, 3, 4, 5, 6. Уровень заголовка в структуре страницы; его вид зависит от размера.
• layout — string, по умолчанию block, значения: block, inline. inline — одна строка для списка в меню, выпадающем списке или поиске: маленький значок, текст и не больше одного действия-ссылки, без заголовка.
• live — string, по умолчанию auto, значения: auto, alert, off. auto — nothing-found и error объявляются вежливо, остальные молчат; alert — ошибка, вызванная действием человека; off — объявляет хост.
• root-class — string, по умолчанию пусто.
• template — string, по умолчанию default.

Методы

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

События

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

• sf-empty-state-action — detail: { id: string }. Человек нажал одно из действий (retry — у ошибки без собственных действий).

Доступность

• Роль: status.
• Доступное имя: внутренний.
• Клавиши: Tab, Enter, Space.
• Фокус: Заголовок полной формы — настоящий заголовок уровня heading-level; у компактной заголовка нет. При live=auto nothing-found и error объявляются вежливо (role=status), остальные — нет; live=alert делает объявление срочным, live=off — беззвучным. Значок декоративный; действия — обычные кнопки в порядке Tab. Внутри listbox или меню ставьте его вне элемента списка, чтобы он не считался пунктом.

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

<sf-empty-state kind="nothing-found" size="1/2" heading-level="4"></sf-empty-state>

Источник

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

См. также

• Пустые состояния в составных компонентах

• Скелетон

• Представление данных