Перейти к основному содержанию

Обзор

Toast отображает одно уведомление. Ваше приложение управляет моментом его появления, его положением и моментом его удаления.

Использование

Визуальные параметры

Сравните нейтральную, успешную, ошибочную, информационную и предупреждающую обратную связь с одинаковыми сообщением и ходом выполнения. Для уведомлений приложения оберните приложение в ToastProvider, разместите внутри него Toaster и используйте useToast() в дочерних компонентах. Каждый провайдер имеет независимое хранилище уведомлений, таймеры обратного отсчета и жизненный цикл закрытия. Несколько Toaster могут дублировать один и тот же провайдер.

Уведомления приложения

enqueueToast принимает свойства Toast и необязательный dedupeKey, а возвращает ID уведомления. Совпадающий видимый ключ возвращает существующий ID без добавления другого уведомления. updateToast({ id, ...changes }) обновляет это активное уведомление. closeToast(id) закрывает одно уведомление; closeToast() закрывает все видимые уведомления в провайдере. По умолчанию провайдер отображает три уведомления. limit должен быть положительным целым числом и может изменяться, пока провайдер смонтирован. При его уменьшении или добавлении уведомлений сверх него сначала закрываются самые старые видимые уведомления. При увеличении существующие уведомления не изменяются, а закрытые уведомления не восстанавливаются. Изменения конфигурации сохраняют хранилище, сохранившиеся идентификаторы, порядок и оставшееся время обратного отсчета.

Жизненный цикл провайдера

Несколько Toaster внутри провайдера отображают одни и те же уведомления. Обновления и закрытие применяются к каждому зеркальному экземпляру, а каждое уведомление имеет один общий обратный отсчет. Наведение или фокус внутри любого зеркального экземпляра приостанавливает его; отсчет возобновляется, когда все зеркальные экземпляры освобождают и наведение, и фокус. Монтирование другого Toaster не перезапускает обратный отсчет и не создает другой жизненный цикл обратного вызова. Используйте отдельные провайдеры для независимых очередей. Для уведомлений провайдера истечение срока, кнопка закрытия, closeToast и вытеснение из-за лимита один раз вызывают последнюю версию onClose. Когда выполняется обратный вызов, уведомление уже закрыто, поэтому обновления и повторные запросы на закрытие для этого идентификатора не дают эффекта. onCancel остается отдельным обратным вызовом действия и не закрывает уведомление автоматически. Закрытые уведомления неактивны во время анимаций выхода. Их записи удаляются после того, как все отображаемые зеркальные экземпляры завершат анимацию выхода или будут размонтированы. Размонтирование последнего Toaster очищает записи закрытых уведомлений и приостанавливает оставшееся время для видимых уведомлений. Повторное монтирование Toaster возобновляет этот отсчет времени. Размонтирование провайдера удаляет его уведомления и отменяет обратный отсчет и анимацию выхода без вызова onClose. Сохраненные операции enqueueToast, updateToast и closeToast этого провайдера не дают эффекта после его размонтирования. getToastProps адаптирует содержимое и представление каждого уведомления. Задайте duration и progress в enqueueToast или updateToast, чтобы все зеркальные экземпляры использовали одинаковую конфигурацию времени. Существующие переопределения времени через getToastProps по-прежнему поддерживаются, если все зеркальные экземпляры возвращают одинаковые длительность и прогресс для уведомления. Провайдер сохраняет идентификатор, обработчик закрытия и общий обратный отсчет. container выбирает назначение портала Toaster. Если параметр опущен, используется окружающий контейнер темы или document.body. Явно заданный элемент отображается там; null откладывает отображение. Видимые уведомления остаются в очереди, а их обратный отсчет приостанавливается, пока не отображается ни один Toaster. Порталы сохраняют окружающие тему и направление. Задайте aria-label для каждого Toaster, чтобы локализовать имя его региона по умолчанию, “Уведомления”, и присвоить зеркальным регионам подходящие имена.

Обновление активного уведомления

Используйте ID, возвращаемый enqueueToast, чтобы обновить содержимое, статус обратной связи, действия или обратные вызовы на месте. Обновления сохраняют идентификатор и положение уведомления. Неизвестные или закрытые идентификаторы не имеют эффекта, в том числе во время выполнения анимации закрытия. Каждый вызов useToast() нацелен на ближайший провайдер.
ToastUpdate требует id и принимает частичные параметры Toast. Пропущенные поля сохраняют текущие значения. Явное значение undefined очищает необязательное поле или восстанавливает значение компонента по умолчанию, например progress: undefined или status: undefined. Передайте null, чтобы удалить слот содержимого, включая description, icon или action. Установка cancelLabel: null скрывает элемент управления отменой, сохраняя его обратный вызов. Изменения обратного вызова применяются к существующему уведомлению. dedupeKey относится к постановке в очередь и не может быть обновлён.

Время закрытия

Обратный отсчёт по умолчанию составляет 6000 миллисекунд. Он приостанавливается, когда указатель находится над уведомлением или фокус клавиатуры находится внутри него, и возобновляется только после того, как исчезнут оба условия. При использовании нескольких Toaster состояние паузы является общим для их зеркальных экземпляров. Визуальный обратный отсчёт отображает оставшееся время до закрытия. Автоматическое закрытие также работает, когда уменьшение движения отключает анимацию. Например, updateToast({ id, children: 'Still saving' }) сохраняет оставшееся время, а updateToast({ id, duration: 6000 }) дает читателю еще шесть секунд. Эти правила применяются к существующему уведомлению без изменения его идентификатора или позиции.

Закрываемое уведомление

onClose вызывается один раз кнопкой закрытия или после завершения обратного отсчета. Удалите toast в этом обратном вызове. Используйте duration={0} для уведомления, которое остается открытым до закрытия.

Ход выполнения и отмена

Передача progress задаёт процентное значение и отключает обратный отсчёт. Удалите его после завершения операции, чтобы запустить новый отсчет длительности. При отмене вызывается onCancel; родительский компонент управляет отменой и удалением. cancelLabel принимает React-узел для содержимого кнопки. Дочерние элементы, description, icon и action также принимают React-узлы, принадлежащие вызывающему коду. Используйте элементы управления Twenty для интерактивных действий и указывайте их доступные имена.

Внешний вид и объявления

status принимает neutral, info, success, warning или error; по умолчанию используется neutral. Он выражает смысл обратной связи и выбирает значок и палитру темы. Toast поддерживает один внешний вид, поэтому не предоставляет параметр variant для внешнего вида или параметр color для палитры. Используйте icon для замены значка, icon={null} для его исключения и iconLabel, когда значку по умолчанию требуется собственное доступное имя. Роль по умолчанию — status с ненавязчивыми объявлениями. Используйте role="alert" для срочной обратной связи. Укажите cancelLabel и closeLabel, чтобы локализовать элементы управления, и предоставьте достаточно времени для чтения содержимого или взаимодействия с его действиями.

Свойства

Справочник создан на основе публичных типов компонента. Нативные атрибуты, стили, имена классов, обработчики событий и ссылки нацелены на корневой элемент. Используйте render, чтобы скомпоновать другой элемент или компонент, сохранив эти свойства и ссылку. Порталы Toaster наследуют окружающую тему и направление текста.
ReactNode
Optional footer node, such as a Button with a caller-owned action.
ReactNode
по умолчанию:"Cancel"
Cancel button content node. Defaults to Cancel. Pass null to hide the control.
ReactNode
Main message node. Callers own its content and accessible text.
string
Additional class names merged onto the root.
string
по умолчанию:"Close"
Accessible name of the close button. Defaults to Close.
ReactNode
Optional supporting content node rendered below the message.
number
по умолчанию:"6000"
Milliseconds before onClose is called, defaulting to 6000. Zero keeps the toast open. Changes restart the countdown; live updateToast duration patches restart it even when unchanged. Hover and keyboard focus pause it until both leave.
ReactNode
Leading icon node. Defaults to the status icon. Pass null to omit it.
string
Accessible name of the default icon. Without it, the icon is decorative.
(() => void)
Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button.
(() => void)
For standalone Toast, called once per mount by the close button or expiry. For provider notifications, called once on close, expiry, closeToast, or limit eviction, after dismissal and before exit cleanup. Provider teardown does not call it.
number
Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration.
Ref<HTMLDivElement>
Ref to the root div, or the element supplied through render.
RenderProp<Record<string, unknown>>
Element or callback composition for the root. Native props and the ref target the rendered element.
"error" | "info" | "neutral" | "success" | "warning"
по умолчанию:"neutral"
Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette.
CSSProperties
Inline styles forwarded to the root.

ToastProvider

ReactNode
Application content and any Toasters sharing this provider’s independent notification store and lifecycle.
number
по умолчанию:"3"
Reactive maximum number of visible toasts, defaulting to three. Must be a positive integer. Lowering it or adding above it dismisses the oldest visible notifications and calls their onClose once. Surviving IDs, order, and countdowns are preserved.

Toaster

Нативные атрибуты div, стили, имена классов и refs применяются к области уведомлений.
HTMLElement | null
Portal destination. Omit to use the theme container or document.body; null defers rendering. The provider retains visible notifications and pauses their countdowns while no Toaster is rendered.
((toast: ToastNotification) => Partial<Omit<ToastProps, "ref" | "id" | "onClose">>)
Adapts notification content and presentation. The provider owns id, dismissal, and the shared countdown. Set timing through enqueueToast or updateToast; duration and progress overrides must match across Toasters sharing a provider.
RenderProp<Record<string, unknown>>
Custom root element composed through Base UI.