﻿---
description: Компонент окна оповещения, для отображения важных сообщений и подтверждения действий пользователя.
tags: notification
---

# Alert \[tag:component]

Компонент окна оповещения, для отображения важных сообщений и подтверждения действий пользователя.
Например, уведомление о том, что выполнение операции ведёт к удалению данных.
Внешний вид компонента зависит от платформы и имитирует поведение [нативного элемента](https://developer.apple.com/design/human-interface-guidelines/alerts).

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

```jsx
const [alert, setAlert] = React.useState(null);

const showAlert = () => {
  if (alert) return;
  setAlert(
    <Alert
      onClosed={() => setAlert(null)}
      dismissLabel="Отмена"
      actions={[
        { title: 'Отмена', mode: 'cancel' },
        { title: 'Удалить', mode: 'destructive' },
      ]}
      title="Удаление документа"
      description="Вы уверены, что хотите удалить этот документ?"
    />,
  );
};

return (
  <>
    <Button onClick={showAlert}>Показать оповещение</Button>
    {alert}
  </>
);
```

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

### `onClosed`

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

## Шапка

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

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

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

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

```jsx
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"` переименовать
в похожее по смыслу действие:

```jsx
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"` — выравнивание по правому краю (по умолчанию).

> Свойство недоступно на платформе iOS.

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

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

> На платформе `vkcom` возможно только горизональное расположение.

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

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

```jsx
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"` — кнопка закрытия не отображается.

> **Обратите внимание**
>
> Кнопка закрытия не отображается на платформе iOS и в мобильном представлении (`regular`-режиме)

Дополнительно [ознакомьтесь](#a11y-buttons) в информацией по поддержке доступности кнопки.

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

### `autoFocus`

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

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

### `restoreFocus`

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

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

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

VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга `Alert`.

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

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

Также можно указать конкретный `DOM`-элемент (полученный, например, через `document.getElementById`)
или ссылку на `DOM`-элемент ([`ref`-объект](https://react.dev/learn/manipulating-the-dom-with-refs)).

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

### Click Event

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

## Тестирование (e2e) \[#e2e]

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

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

## Доступность (a11y) \[#a11y]

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

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

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

### Доступные имена кнопок \[#a11y-buttons]

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

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

## Свойства и методы \[#api]

| Свойство                | Тип                                                                | По умолчанию                                                | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions`               | `AlertActionInterface[]`                                           | `-`                                                         | Список действий.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `actionsAlign`          | `AlignType`                                                        | `-`                                                         | Тип выравнивания действий.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `actionsLayout`         | `"horizontal" \| "vertical"`                                       | `-`                                                         | Расположение действий - вертикально или горизонтально.                                                                                                                                                                                                                                                                                                                                                                                            |
| `allowClickPropagation` | `boolean`                                                          | `-`                                                         | По умолчанию событие onClick не всплывает.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `autoFocus`             | `boolean \| "root"`                                                | `true`                                                      | Управление поведением автофокуса при появлении всплывающего окна. При прокидывании `true` фокус будет установлен на первый элемент. При прокидывании `root` фокус будет установлен в корень.                                                                                                                                                                                                                                                      |
| `description`           | `ReactNode`                                                        | `-`                                                         | Описание модального окна.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `descriptionTestId`     | `string`                                                           | `-`                                                         | Передает атрибут `data-testid` для описания.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `dismissButtonMode`     | `"none" \| "inside" \| "outside"`                                  | `-`                                                         | Расположение кнопки закрытия (внутри и вне `popout'a`) Доступно только в `compact`-режиме, не отображается на `iOS`.  ⚠️ ВНИМАНИЕ: использование `none` скрывает крестик, это негативно сказывается на пользовательском опыте.                                                                                                                                                                                                                    |
| `dismissButtonTestId`   | `string`                                                           | `-`                                                         | Передает атрибут `data-testid` для кнопки закрытия.                                                                                                                                                                                                                                                                                                                                                                                               |
| `dismissLabel`          | `string`                                                           | `-`                                                         | Текст кнопки закрытия. Делает ее доступной для ассистивных технологий.                                                                                                                                                                                                                                                                                                                                                                            |
| `getRootRef`            | `Ref<HTMLDivElement>`                                              | `-`                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `onClose`               | `((reason: AlertCloseReason) => void)`                             | `-`                                                         | Обработчик закрытия модального окна.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `**onClosed** \*`       | `VoidFunction`                                                     | `-`                                                         | Обработчик закрытия модального окна, срабатывающий после окончания анимации.                                                                                                                                                                                                                                                                                                                                                                      |
| `ref`                   | `Ref<HTMLDivElement>`                                              | `-`                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `renderAction`          | `((props: AlertActionProps) => ReactNode)`                         | `-`                                                         | Функция для отрисовки действия.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `restoreFocus`          | `boolean \| (() => boolean \| HTMLElement)`                        | `true`                                                      | Управление поведением возврата фокуса при закрытии всплывающего окна.                                                                                                                                                                                                                                                                                                                                                                             |
| `title`                 | `ReactNode`                                                        | `-`                                                         | Заголовок модального окна.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `titleTestId`           | `string`                                                           | `-`                                                         | Передает атрибут `data-testid` для заголовка.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `usePortal`             | `boolean \| HTMLElement \| RefObject<HTMLElement \| null> \| null` | `true (использует `document.body` как портал по умолчанию)` | Настройка портала для рендеринга компонента.  `true` - использует `portalRoot` из контекста `AppRoot` (если доступен) или `document.body`; `false` - отключает использование портала; `HTMLElement` - указывает конкретный DOM-элемент для использования в качестве портала; `React.RefObject<HTMLElement \| null>` - ссылка на DOM-элемент для использования в качестве портала; `null` - эквивалентно `false`, отключает использование портала. |
