Тост

Когда использовать#

• Человек только что отправил форму, и нужно сказать, чем кончилось: сохранено, отклонено, принято в работу.
• На странице есть состояние, о котором стоит предупредить: лимит, просроченный ключ, режим только для чтения.
• Ошибка касается всей формы, а не одного поля: сервер недоступен, запись изменил кто-то другой.

Не берите тост для ошибки одного поля — она печатается под самим полем. Состояние записи, которое видно всегда, показывает плашка. Необратимое действие предупреждает опасная зона, а не тост после того, как всё уже удалено.

Виды#

Вид задаёт цвет, значок и роль сообщения. Он принимается и по-английски (ok, warn, err, info), и по-русски («успех», «предупреждение», «ошибка»); незнакомое значение станет нейтральным «info».

Успех — вид по умолчанию. Строку вместо структуры кит понимает как текст успеха.

Предупреждение — ничего не сломалось, но скоро сломается или требует внимания.

В дереве холста тост — узел Кит.Уведомление: текст позицией, вид, заголовок, крест и тревога — словами Вид, Заголовок, Закрываемый, Тревога (см. Язык узлов).

Ошибка — действие не выполнено. Только этот вид объявляется скринридеру сразу, прерывая текущее чтение.

Сведения — нейтральное сообщение о том, что происходит: запущен процесс, письмо отправлено.

Заголовок печатается полужирным перед текстом. Он нужен, когда текст длинный и сначала важно сказать, о чём речь.

Закрываемый тост#

Закрываемый печатает крест справа — кнопку с data-close и подписью «Закрыть». По нажатию скрипт кита гасит тост и убирает его со страницы, как Snackbar у MUI. Без скрипта крест ничего не делает, поэтому важное сообщение не прячьте только за ним.

Тост появляется въездом снизу с кривой emphasized-decelerate. Если в системе включено «уменьшить движение», он просто появляется на месте.

Тост из ответа#

После тихой отправки страница не перезагружается, и тост, который сервер напечатал в ответе, мог бы лечь где-то выше экрана — человек не узнал бы, что сохранилось. Поэтому скрипт кита, положив ответ на страницу, поднимает новые тосты из потока вниз экрана, как Snackbar у Material, и показывает их по одному: каждый — 5 секунд, потом тост гаснет и встаёт следующий. Пока на тосте мышь или фокус, время стоит. Крест закрывает раньше. Новый — тот, которого на странице до ответа не было: тост, который уже стоял в потоке и пришёл в ответе тем же (постоянное предупреждение, образец на этой странице), остаётся на месте, и смена темы его не трогает.

Серверу для этого ничего нового не нужно: он кладёт тост в ответ обычным узлом Кит.Уведомление там, где печатал его и раньше. Без скрипта тост остаётся на странице, где его напечатал сервер, и никуда не уходит.

Тост с ролью alert — вид «ошибка» или слово Тревога() — скрипт не поднимает и не закрывает: он остаётся на своём месте, пока человек не закроет его крестом или следующий ответ сервера не уберёт его. Ошибку, которую не успели прочесть, нельзя прятать по таймеру.

Поднятый тост скрипт отмечает признаком data-toast-live: wait — ждёт очереди и не виден, show — виден внизу экрана, gone — гаснет. Морфинг следующего ответа такой тост не трогает. Живой образец с сервером — форма нового проекта: создайте два проекта подряд, и тосты встанут в очередь.

HTML = Кит.Уведомление("Не сохранено: сервер сборки не отвечает").Вид("err").Закрываемый().Рендер();

HTML = Кит.Уведомление("Ключ доступа истекает завтра — продлите его").Вид("warn").Рендер();

Гайдлайны#

HTML = Набор.Тост().Отрисовать("Профиль сохранён");

HTML = Набор.Тост().Отрисовать("Операция выполнена успешно!");

HTML = Набор.Тост().Отрисовать(Новый Структура("Текст, Вид",
	"Не удалось сохранить: сервер не отвечает", "err"));

HTML = Набор.Тост().Отрисовать(Новый Структура("Текст, Вид",
	"Не удалось сохранить: сервер не отвечает", "ok"));

HTML = Набор.Тост().Отрисовать(Новый Структура("Текст, Вид",
	"Не сохранено: проверьте два поля ниже", "err"));

HTML = Набор.Тост().Отрисовать(Новый Структура("Текст, Вид", "Имя не заполнено", "err"))
	+ Набор.Тост().Отрисовать(Новый Структура("Текст, Вид", "Почта не заполнена", "err"))
	+ Набор.Тост().Отрисовать(Новый Структура("Текст, Вид", "Не сохранено", "err"));

Доступность#

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

Узлом холста#

На холсте тост — узел рода «уведомление», а функция холста так и называется: Кит.Уведомление.

Модель#

Структура ниже — прежний вид модели; в дереве холста её поля пишут слова Кит.Уведомление.

Отрисовывает тост.

Параметры:
 Модель - Структура, Строка - текст сообщения либо структура: Текст (экранируется),
          Вид ("ok" | "warn" | "err" | "info", по умолчанию "ok"), Заголовок,
          Закрываемый (показывать кнопку закрытия), Тревога (role="alert" при любом
          виде: скринридер объявляет сразу, а скрипт кита не закрывает такой тост сам).

Возвращаемое значение:
 Строка - фрагмент <div class="toast">.

Уведомление о результате действия; компонент называется «Тост». Слова: Вид, Заголовок,
Закрываемый, Тревога (role="alert" при любом виде; выпуск 0.12). Тост в ответе тихой
отправки скрипт кита показывает внизу экрана по очереди и закрывает через 5 с, кроме
тоста с ролью alert; без скрипта тост стоит на странице, где его напечатал сервер.

Параметры:
 Модель - Строка, Структура - текст уведомления; Структура — прежний вид модели.

Возвращаемое значение:
 ЭлементЭкрана

Приводит вид сообщения к allowlist.

Параметры:
 Вид - Строка - вид из модели.

Возвращаемое значение:
 Строка - "ok" | "warn" | "err" либо "info" для неизвестного значения.