Alert

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

onClose

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

Шапка

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

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

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

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

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

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

По умолчанию нажатие на опцию вызывает переданную в Alert функцию onClose, свойство 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="Вы уверены, что хотите удалить этот документ?"
/>

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