Toast

<sf-toast> показывает одно короткое сообщение о результате действия: статус, заголовок, пояснение, необязательное действие и кнопку закрытия. Для постоянного текста внутри страницы берите уведомление, для выбора, без которого работу не продолжить, — модальное окно.

Пример

<div class="flex flex-col gap-2">
  <sf-toast status="success" icon="check_circle" title="Изменения сохранены" supporting-text="Новая версия доступна участникам проекта."></sf-toast>
  <sf-toast status="info" icon="delete" title="Файл перемещён в корзину" action-text="Отменить" action="undo"></sf-toast>
</div>

Применение

Статус

status принимает общий словарь статусов: neutral, info, success, warning, error. Выбирайте его по смыслу сообщения, а не по желаемому цвету. Иконку статус не добавляет: её задаёт атрибут icon.

Время жизни

По умолчанию сообщение остаётся до закрытия. duration задаёт время жизни в миллисекундах; отсчёт приостанавливается, пока указатель или фокус находится внутри сообщения. Сообщение с действием оставляйте без duration: пользователь должен успеть его выполнить.

<sf-toast status="success" title="Ссылка скопирована" duration="5000" role="status"></sf-toast>

Действие и закрытие

action-text показывает одну кнопку действия, action — машинное значение, которое приходит в событии. Нажатие отправляет sf-toast-action с detail.action; закрытие отправляет sf-toast-close и удаляет элемент. Бизнес-действие выполняет приложение.

const toast = document.querySelector('sf-toast');
toast.onAction((action) => {
  if (action === 'undo') restoreFile();
});
toast.onClose(() => console.log('Сообщение закрыто'));

closable="false" убирает кнопку закрытия; закрыть такое сообщение может только таймер или метод close().

Размещение

Результат действия показывайте через SF.notify: у страницы одна область уведомлений, и она лежит выше открытого модального окна. Свой контейнер с <sf-toast> нужен, когда приложение само управляет местом и набором сообщений.

Toast отвечает за одно сообщение. Позицию на экране, порядок и число одновременно показанных сообщений задаёт контейнер приложения. Обычный контейнер — фиксированный столбец в углу экрана: fixed block-end-b6 inline-end-b6 z-9 flex flex-col gap-2. Сообщения добавляются в него через append() и сами удаляются при закрытии или по истечении duration.

Это правило — только для своего контейнера. Открытое модальное окно лежит выше слоя z-9, поэтому сообщение из своего контейнера окажется под окном: результат действия в окне показывайте из него после close(). SF.notify можно вызывать и при открытом окне — его область лежит выше окна.

Пример: контейнер сообщений

<button type="button" id="toast-container-trigger" class="sf-button sf-button--default sf-button--primary sf-button--size-1">
  <span class="sf-button-text-container">Сохранить черновик</span>
</button>

<div id="toast-container-demo" class="fixed block-end-b6 inline-end-b6 z-9 flex flex-col gap-2" role="status"></div>

// The container is on the page from the first load and is the live region:
// a toast put into it is read out, so the toast itself needs no role. The
// container decides the corner, the order and the gap; each toast removes
// itself when closed or when its time is up.
const initializeToastContainer = () => {
  const trigger = document.getElementById('toast-container-trigger');
  const container = document.getElementById('toast-container-demo');
  if (!trigger || !container || trigger.dataset.exampleReady === 'true') return;
  trigger.dataset.exampleReady = 'true';

  trigger.addEventListener('click', () => {
    const toast = document.createElement('sf-toast');
    toast.setAttribute('status', 'success');
    toast.setAttribute('icon', 'check_circle');
    toast.setAttribute('title', 'Черновик сохранён');
    toast.setAttribute('duration', '5000');
    toast.setAttribute('close-label', 'Закрыть сообщение');
    container.append(toast);
  });
};

initializeToastContainer();

Доступность

• Сообщению, которое вставляется динамически, нужна живая область. Надёжнее всего контейнер, который есть на странице с первой загрузки и несёт role="status", как в примере: вставленное в него сообщение зачитывается, и своя роль сообщению не нужна. Живую область, которая появляется на странице сразу с текстом, не все программы чтения экрана озвучивают. Без такого контейнера задайте самому сообщению role="status" для обычного результата и role="alert" для срочной ошибки. Сообщению, которое есть на странице с первой загрузки, живая роль не нужна.
• close-label задаёт доступное имя кнопки закрытия; по умолчанию оно на языке страницы («Закрыть сообщение»), передавайте его, только чтобы заменить текст.
• Не помещайте в исчезающее сообщение обязательный шаг или сведения, которые легко пропустить: таймер приостанавливается при фокусе и наведении, но не ждёт, пока пользователь доберётся до сообщения.
• Кнопки действия и закрытия — нативные кнопки в обычном порядке Tab.

Справочник API

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

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

Атрибуты

• status — string, по умолчанию neutral, значения: neutral, info, success, warning, error. О чём сообщает сообщение, в общем словаре статусов. Также принимаются значения default и primary; они означают neutral и info.
• icon — string, по умолчанию пусто. Необязательное имя декоративной иконки.
• title — string, по умолчанию пусто. Короткий заголовок результата.
• supporting-text — string, по умолчанию пусто. Краткий вспомогательный текст обычного размера основного текста.
• action-text — string, по умолчанию пусто. Видимая подпись единственного необязательного действия.
• action — string, по умолчанию action. Стабильное значение действия, передаваемое в sf-toast-action.
• closable — boolean, по умолчанию true. Отображает явно названное действие закрытия.
• close-label — string, по умолчанию пусто. Доступное имя действия закрытия на языке страницы. Пусто — текст на языке страницы (по-английски «Close message»).
• duration — number, по умолчанию 0, значения: от 0. Явное время жизни в миллисекундах. Ноль оставляет сообщение до закрытия.
• role — string, по умолчанию пусто, значения: пусто, status, alert. Роль живой области только для динамически вставляемой обратной связи.
• root-class — string, по умолчанию пусто.

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

Методы

• close() — возвращает object. То же, что dismiss: отправляет sf-toast-close и удаляет уведомление.
• setState(nextState: object) — возвращает object. Записывает каждый ключ как атрибут в kebab-case: false, null, undefined или пустое значение удаляет его, true устанавливает пустым, всё остальное приводится к строке.
• onAction(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик sf-toast-action; обработчик вызывается с (action, detail, event). Обработчик, не являющийся функцией, игнорируется.
• onClose(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик sf-toast-close; обработчик вызывается с (detail, event). Обработчик, не являющийся функцией, игнорируется.

События

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

• sf-toast-action — detail: { action: string, toast: object, trigger: object }. Отправляется один раз при активации необязательного доступного действия.
• sf-toast-close — detail: { toast: object, trigger: object|null }. Отправляется один раз, перед тем как закрытие по токену удалит владельца уведомления.

Доступность

• Доступное имя: внутренний.
• Клавиши: Tab.
• Фокус: Нативные действия используют focus-visible; уведомление с таймером приостанавливается, пока фокус внутри него.

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

<sf-toast status="success" title="Сохранено" supporting-text="Изменения доступны." role="status"></sf-toast>

Источник

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

См. также

• Всплывающие сообщения — сообщения на классах без Smart-элемента.
• Alert — сообщение, которое остаётся в потоке страницы.