﻿---
description: Базовый компонент для создания модальных карточек с гибким содержимым.
---

# ModalCardBase \[tag:component]

Базовый компонент для создания модальных карточек с гибким содержимым.
Используется как основа для `ModalCard`.

Связанные компоненты:

* [`ModalCard`](/components/modal-card)

```jsx
<ModalCardBase
  icon={<Icon56MoneyTransferOutline />}
  title="Подтверждение перевода"
  description="Сумма: 5 000 ₽ · Получатель: Иван Петров"
  actions={
    <ButtonGroup mode="horizontal" gap="s" stretched>
      <Button size="l" mode="primary" stretched>
        Подтвердить
      </Button>
      <Button size="l" mode="secondary" stretched>
        Отмена
      </Button>
    </ButtonGroup>
  }
  dismissLabel="Закрыть"
/>
```

## Ключевые элементы

## Визуальные компоненты

### Иконка

Задаётся свойством `icon`. Рекомендуется использовать:

* контурные иконки размером `56px` (`<Icon56...Outline />`);
* аватары размером `72px`(`<Avatar size={72} src={...} />`).

### Текстовые блоки

* Свойство `title` отвечает за основной заголовок.
* Свойство `description` отвечает за поясняющий текст.

## Интерактивные элементы

* Свойство `actions` используется для задания группы кнопок (`Button`).
* Свойство `outsideButtons` используется для дополнительных элементов управления (*только для десктопа*).
  Рекомендуется использовать компонент [`ModalOutsideButton`](/components/modal-outside-button)

## Блокировка закрытия

Свойство `preventClose` отключает закрытие по нажатию, свайпу или клавише `ESC`.

## Размеры и адаптивность

Компонент автоматически адаптируется под все устройства, но с помощью свойство `size` можно определить
максимальную ширину для десктопа (по умолчанию `450px`).

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

Через свойство `dismissButtonMode=inside|outside|none` можно задать вид кнопки закрытия.
Согласно нашим дизайн-гайдам, `dismissButtonMode=outside` отображается только для `compact`-режима (десктопная и планшетные версии).
Для iOS всегда будет применяться `dismissButtonMode=inside` в `regular`-режиме (мобильная версия).

> Свойство `dismissButtonMode=none` (скрывает крестик) или `preventClose` (отключает стандартные способы закрытия) негативно влияют на пользовательский опыт. Используйте их, только если точно знаете, что делаете.

## Отступы между контентом и кнопками действий (`actions`)

По умолчанию верхний отступ от кнопок действий `actions` равняется `16px`. Согласно дизайн-системе отступ может быть
больше в зависимости от того какие данные отображаются внутри `ModalCardBase`.
Если необходимо увеличить отступ, то передавайте в `actions` компонент [Spacing](/components/spacing).

```jsx
<ModalCardBase
  dismissButtonMode="inside"
  dismissLabel="Закрыть"
  title="Десктопная и планшетная версии с крестиком внутри"
  description="Сверху будет безопасный отступ до иконки"
  actions={
    <React.Fragment>
      <Spacing size={16} />
      <Button size="l" mode="primary" stretched>
        Некая кнопка
      </Button>
    </React.Fragment>
  }
/>
```

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

Если `ModalCardBase` является модальным окном, то ему, или его родителю,
надо добавить аттрибуты `role="dialog"` и `aria-modal="true"`, чтобы пользователи клавиатуры или скринридера
не могли выйти за пределы модального окна пока оно не закрылось.

Также у `ModalCardBase` обязательно должно быть имя — краткое название. Благодаря этому пользователи вспомогательных
технологий знают, что это за элемент и какое у него содержимое.

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

* используя свойство `title`. Тогда следует также передать `aria-labelledby` и `titleId` так,
  чтобы они имели одинаковые значения, чтобы можно было связать `title` и модальное окно.
  Мы не делаем этого автоматически потому что не можем быть уверены на каком уровне будут заданы `role` и `aria-modal`;
* используя свойство `aria-label`;
* используя свойство `aria-labelledby`. Если не использовать свойство `title`, то можно передать `id` любого контейнера
  с текстом;

Чтобы кнопка для закрытия была доступной для ассистивных технологий, мы передаем в нее скрытый визуально текст,
который сможет прочитать скринридер. Для изменения текста, передайте его в `dismissLabel`.

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

| Свойство                   | Тип                                         | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------- | ------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions`                  | `ReactNode`                                 | `-`          | Кнопки-действия. Принимает [`Button`](https://vkui.io/components/button) с параметрами:  - `size="l" mode="primary" stretched` - `size="l" mode="secondary" stretched`.  Для набора кнопок используйте [`ButtonGroup`](https://vkui.io/components/button-group) с параметрами:  - `gap="s" mode="horizontal" stretched` - `gap="m" mode="vertical" stretched`. |
| `description`              | `ReactNode`                                 | `-`          | Описание.                                                                                                                                                                                                                                                                                                                                                      |
| `descriptionComponent`     | `ElementType<any, keyof IntrinsicElements>` | `span`       | Позволяет поменять тег используемый для описания.                                                                                                                                                                                                                                                                                                              |
| `dismissButtonMode`        | `"none" \| "inside" \| "outside"`           | `outside`    | Расположение кнопки закрытия (внутри и вне `popout'a`).  Доступно только в `compact`-режиме.  На `iOS` в `regular`-режиме всегда включен `inside`.  ⚠️ ВНИМАНИЕ: использование `none` скрывает крестик, это негативно сказывается на пользовательском опыте.                                                                                                   |
| `dismissLabel`             | `string`                                    | `Закрыть`    | Текст кнопки закрытия. Делает ее доступной для ассистивных технологий.                                                                                                                                                                                                                                                                                         |
| `getRootRef`               | `Ref<HTMLDivElement>`                       | `-`          |                                                                                                                                                                                                                                                                                                                                                                |
| `icon`                     | `ReactNode`                                 | `-`          | Иконка.  Может быть компонентом иконки, например, `<Icon56MoneyTransferOutline />`, или `<Avatar size={72} src="" />`.                                                                                                                                                                                                                                         |
| `modalDismissButtonTestId` | `string`                                    | `-`          | Передает атрибут `data-testid` для кнопки закрытия.                                                                                                                                                                                                                                                                                                            |
| `onClose`                  | `VoidFunction`                              | `-`          | Обработчик закрытия модального окна.                                                                                                                                                                                                                                                                                                                           |
| `outsideButtons`           | `ReactNode`                                 | `-`          | Управляющие элементы под кнопкой закрытия.  Доступно только в `compact`-режиме. Рекомендуется размещать иконки размера 20, обернутые в ModalOutsideButton.                                                                                                                                                                                                     |
| `preventClose`             | `boolean`                                   | `-`          | Позволяет отключить возможность закрытия модальной страницы (смахивание, клавиша `ESC`, нажатие на подложку).  ⚠️ ВНИМАНИЕ: использование этой опции негативно сказывается на пользовательском опыте.                                                                                                                                                          |
| `ref`                      | `Ref<HTMLDivElement>`                       | `-`          |                                                                                                                                                                                                                                                                                                                                                                |
| `size`                     | `number`                                    | `-`          | Задаёт контенту максимальную ширину для десктопной версии.                                                                                                                                                                                                                                                                                                     |
| `title`                    | `ReactNode`                                 | `-`          | Заголовок карточки.                                                                                                                                                                                                                                                                                                                                            |
| `titleComponent`           | `ElementType<any, keyof IntrinsicElements>` | `span`       | Позволяет поменять тег используемый для заголовка.                                                                                                                                                                                                                                                                                                             |
| `titleId`                  | `string`                                    | `-`          | Позволяет задать id для заголовка. Используется, чтобы связать модальное окно и title через aria-labelledby, тем самым задав модальному окну имя через title.                                                                                                                                                                                                  |
