Alert

Обязательные свойства

onClosed

Свойство onClosed принимает функцию, которая вызовется после завершения анимации закрытия компонента. Обязательно удаляйте из DOM-дерева компонент Alert в обработчике onClosed, иначе это будет мешать дальнейшему взаимодействию с элементами и повторному открытию компонента.

Шапка

В компоненте есть возможность задать заголовок и описание для уведомления с помощью свойств title и description соответственно:

<Alert title="Удаление документа" description="Вы уверены что хотите удалить этот документ?" />

Кнопки действий

Через свойство actions можно задать набор кнопок, который будет отрисован:

const actions = [
  { title: 'Отмена', mode: 'cancel' },
  {
    title: 'Удалить',
    mode: 'destructive',
    action: () => console.log('Документ удален.'),
  },
];
 
<Alert
  actions={actions}
  dismissLabel="Отмена"
  onClosed={closePopout}
  title="Удаление документа"
  description="Вы уверены, что хотите удалить этот документ?"
/>;

Каждая кнопка описывается объектом, позволяя задать текст кнопки, её тип и дополнительные параметры. Кнопки могут быть ссылками (передайте href) или другим компонентом (передайте Component).

Свойство mode отвечает за внешний вид кнопки:

• "default" — стандартный стиль отображения текста;
• "destructive" — стиль критических действий (чаще всего красный);
• "cancel" — стиль действия отмены.

Стиль "cancel" используется для действия, возвращающего пользователя к состоянию на момент открытия компонента, без выполнения каких-либо операций. Кнопка с таким стилем должна быть одна на Alert и располагаться либо слева, либо снизу. ССЫЛКА

Стиль "destructive" используется в случае, когда выполнение действия влечёт за собой какие-то деструктивные последствия, которые пользователь намеренно не выбирал.

Во всех остальных случаях используйте стиль "default".

Свойство title позволяет задать текст кнопке. Старайтесь указывать конкретное действие (глагол), описывающее что произойдет при нажатии. Например, “Удалить”, “Отменить подписку”. Избегайте формулировок “Да” и “Нет”, потому что они могут путать пользователя. Если необходимо подчеркнуть разницу между подтверждением действия и его отменой, допускается кнопку со стилем "cancel" переименовать в похожее по смыслу действие:

const actions = [
  { title: 'Не сейчас', mode: 'cancel' },
  {
    title: 'Отменить подписку',
    mode: 'destructive',
    action: () => console.log('Подписка отменена.'),
  },
];
 
<Alert
  actions={actions}
  dismissLabel="Не сейчас"
  onClosed={closePopout}
  title="Отмена подписки"
  description="Вы уверены, что хотите отменить подписку?"
/>;

Свойство action принимает обработчик нажатия на кнопку. Если свойство autoCloseDisabled включено, то в аргументы action передаётся объект с функцией close, вызвав которую можно закрыть Alert вручную.

По умолчанию нажатие на опцию вызывает переданную в Alert функцию onClosed, свойство autoCloseDisabled позволяет отключить такое поведение.

Свойство actionsAlign позволяет поменять тип выравнивания кнопок:

• "left" — выравнивание по левому краю;
• "center" — выравнивание по центру;
• "right" — выравнивание по правому краю (по умолчанию).

Свойство actionsLayout отвечает за вертикально или горизонтально расположение действий:

• "horizontal" — горизональное расположение (по умолчанию).
• "vertical" — вертикальное расположение;

Пользовательские кнопки

Управлять отрисовкой кнопок можно через свойство renderAction. Это полезно, когда нужно поддержать одинаковый внешний вид вне зависимости от платформы.

const renderAction = ({ mode, ...restProps }) => {
  return <Button mode={mode === 'cancel' ? 'secondary' : 'primary'} size="m" {...restProps} />;
};
 
<Alert
  actions={[
    { title: 'Лишить права', mode: 'destructive' },
    { title: 'Отмена', mode: 'cancel' },
  ]}
  dismissLabel="Отмена"
  renderAction={renderAction}
  title="Подтвердите действие"
  description="Вы уверены, что хотите лишить пользователя права на модерацию контента?"
/>;

Кнопка закрытия

Благодаря свойству dismissButtonMode можно управлять положением кнопки закрытия.

• "outside" — кнопка закрытия располагается снаружи элемента (по умолчанию);
• "inside" — кнопка закрытия располагается внутри элемента;
• "none" — кнопка закрытия не отображается.

Дополнительно ознакомьтесь в информацией по поддержке доступности кнопки.

Управление фокусом

autoFocus

Автоматически устанавливает фокус на первом интерактивном элементе при открытии всплывающего элемента. По умолчанию включено; отключается через autoFocus={false}.

Чтобы установить фокус на контейнере меню, передайте autoFocus="root". Это полезно, когда у первого интерактивного элемента есть подсказка, активируемая при фокусе, и её появление сразу после открытия нежелательно. Значение "root" поддерживает такой сценарий, не ломая доступность.

restoreFocus

Восстанавливает фокус после закрытия меню на последний активный элемент. По умолчанию включено; отключается через restoreFocus={false}.

В restoreFocus можно передать функцию, возвращающую HTMLElement или boolean: HTMLElement — фокус вернётся на этот элемент, false — не восстанавливается, true — поведение по умолчанию.

Управление порталами

VKUI использует порталы ↗ для рендеринга Alert.

Свойство usePortal позволяет настраивать порталы:

• true — использует свойство portalRoot, указанное в компоненте AppRoot, , если не указано, то document.body (по умолчанию);
• false/null — отключает рендер компонента в отдельном контейнере, он будет рендериться непосредственно по месту определения;

Также можно указать конкретный DOM-элемент (полученный, например, через document.getElementById) или ссылку на DOM-элемент (ref-объект ↗).

Браузерные события

Click Event

По умолчанию событие click не всплывает, что позволяет изолировать компонент от остального приложения. Если нужно обрабатывать это событие (например, есть глобальный обработчик клика для аналитики), используйте свойство allowClickPropagation.

Тестирование (e2e)

Для тестирования доступны свойства с постфиксом *TestId — они помогают находить нужные части компонента:

• titleTestId — id для заголовка;
• descriptionTestId — id для описания;
• dismissButtonTestId — id для кнопки закрытия.

Доступность (a11y)

Alert является модальным окном (role="dialog"), а значит у него обязательно должно быть имя — его краткое название. Благодаря этому пользователи ассистивных технологий знают, что это за элемент и какое у него содержимое.

Задать имя можно с помощью следующих способов:

• используя свойство title;
• используя свойство aria-label;
• используя свойство aria-labelledby;

Доступные имена кнопок

Если две кнопки находятся в разных местах, но выполняют одну функцию, то лучше дать им одинаковые имена. Это относится, например, к кнопке закрытия, имя которой можно задать через свойство dismissLabel. Если у вас среди кнопок действия есть кнопка Отмена, которая без дополнительного действия просто закрывает Alert, ровно как и кнопка закрытия, то кнопке закрытия следует дать то же имя Отмена через свойство dismissLabel.

<Alert
  dismissLabel="Отмена"
  actions={[
    { title: 'Отмена', mode: 'cancel' },
    { title: 'Удалить', mode: 'destructive', action: () => addActionLogItem('Документ удален.') },
  ]}
  title="Удаление документа"
  description="Вы уверены, что хотите удалить этот документ?"
/>

Свойства и методы