useModalManager

Хук для управления модальными окнами (ModalPage, ModalCard) в приложении. Позволяет открывать, обновлять и закрывать модальные окна программно из любого места в коде.

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

Быстрый старт

Хук возвращает два значения: API для управления модалками и компонент, который нужно добавить в разметку.

const [api, contextHolder] = useModalManager();
 
// Открыть модальное окно
api.openModalCard({
  title: "Привет, мир!",
  children: "Содержимое модалки",
});
 
// Не забудьте добавить holder в JSX
return (
  <>
    {/* Ваш контент */}
    {contextHolder}
  </>
);

Параметры

Все параметры опциональны. Хук можно вызвать без аргументов: useModalManager().

Параметр	Тип	Описание
`saveHistory`	`boolean`	Сохранять ли историю открытия модальных окон. При `true` (по умолчанию) можно вернуться к предыдущей модалке через кнопку “Назад”. При `false` предыдущая модалка закрывается при открытии новой.
`modalOverlayTestId`	`string`	`data-testid` для маски модального окна.
`noFocusToDialog`	`boolean`	Отключает фокус на контейнер диалогового окна при открытии.
`disableModalOverlay`	`boolean`	Отключает отображение и взаимодействие с фоном модалки.
`disableOpenAnimation`	`boolean`	Отключает анимацию появления.
`disableCloseAnimation`	`boolean`	Отключает анимацию закрытия.
`usePortal`	`boolean`	Использовать ли портал для рендеринга.
`onOpen`	`(id: string) => void`	Колбэк, вызываемый при начале открытия модалки.
`onOpened`	`(id: string) => void`	Колбэк, вызываемый при окончательном открытии модалки.
`onClose`	`(id: string) => void`	Колбэк, вызываемый при начале закрытия модалки.
`onClosed`	`(id: string) => void`	Колбэк, вызываемый при окончательном закрытии модалки.

Возвращаемое значение

Хук возвращает массив из двух элементов:

api — объект с методами для управления модальными окнами
contextHolder — React-элемент, который нужно добавить в JSX вашего компонента

API методы

`openModalCard(props)` — открыть ModalCard

Показывает модальную карточку. Принимает те же свойства, что и компонент ModalCard (кроме open и keepMounted).

Возвращает: объект с методами для управления этой модалкой (см. OpenModalReturn).

const result = api.openModalCard({
  title: "Заголовок",
  children: "Содержимое",
  actions: <Button onClick={() => result.close()}>Закрыть</Button>,
});

`openModalPage(props)` — открыть ModalPage

Показывает модальную страницу. Принимает те же свойства, что и компонент ModalPage (кроме open и keepMounted).

Возвращает: объект с методами для управления этой модалкой (см. OpenModalReturn).

const result = api.openModalPage({
  header: <ModalPageHeader>Заголовок</ModalPageHeader>,
  children: <Group>Содержимое</Group>,
});

`openCustomModalCard(payload)` и `openCustomModalPage(payload)` — открыть кастомную модалку

Позволяют создать модальное окно с собственной разметкой. Подробнее в разделе Пользовательские модальные окна.

`close(id)` — закрыть модалку

Закрывает модальное окно по его идентификатору.

const result = api.openModalCard({ title: "Модалка" });
api.close(result.id);

`closeAll()` — закрыть все модалки

Закрывает все открытые модальные окна одновременно.

api.closeAll();

`update(id, type, props)` — обновить свойства модалки

Изменяет свойства уже открытой модалки. Можно изменить любое свойство, кроме id.

const result = api.openModalCard({ title: "Старый заголовок" });
 
// Позже обновляем
api.update(result.id, "card", {
  title: "Новый заголовок",
});

`setSaveHistory(value)` — изменить сохранение истории

Меняет поведение сохранения истории модалок.

api.setSaveHistory(false); // Предыдущие модалки будут закрываться

Объект, который возвращают методы openModalCard, openModalPage, openCustomModalCard и openCustomModalPage. Содержит методы для управления конкретной модалкой.

Свойство	Тип	Описание
`id`	`string`	Уникальный идентификатор модалки. Генерируется автоматически, если не указан при открытии.
`close()`	`() => void`	Закрывает эту модалку.
`update(props)`	`(props) => void`	Обновляет свойства модалки. Тип `props` зависит от типа модалки (`ModalCard` или `ModalPage`).
`onClose(resolve?)`	`(resolve?) => Promise`	Возвращает Promise, который выполнится, когда модалка закроется.

Пример использования onClose:

const result = api.openModalCard({ title: "Модалка" });
 
// Выполнить действие после закрытия
result.onClose().then(() => {
  console.log("Модалка закрыта!");
});

Примеры использования

Базовый пример

Загружается...

История открытия модальных окон

По умолчанию история открытых модальных окон сохраняется. Это означает, что при открытии новой модалки предыдущая остаётся в истории, и можно вернуться к ней через кнопку “Назад”.

Чтобы отключить это поведение, передайте saveHistory: false в хук или используйте метод setSaveHistory(false). При отключённой истории предыдущая модалка будет закрываться при открытии новой.

Загружается...

Пользовательские модальные окна

Методы openCustomModalCard и openCustomModalPage позволяют создать модальное окно с собственной разметкой и логикой. Это полезно, когда нужно:

Передать дополнительные данные в модалку
Использовать сложную разметку, которую нельзя описать через openModalCard/openModalPage
Разделить логику вызова модалки и её отображения

Как это работает

Вместо простого объекта конфигурации вы передаёте React-компонент, который будет рендерить содержимое модалки. В этот компонент автоматически передаются:

modalProps — все свойства для компонента ModalCard или ModalPage
id — идентификатор модалки
close() — функция для закрытия модалки
update(props) — функция для обновления свойств модалки
ваши дополнительные свойства (если указаны)

Два способа использования

Способ 1: Передать объект с настройками (когда нужны дополнительные свойства)

api.openCustomModalCard({
  component: MyModalComponent,
  additionalProps: {
    userName: "Иван",
  },
  baseProps: {
    // Свойства для ModalCard
    title: "Заголовок",
  },
});

Способ 2: Передать компонент напрямую (когда дополнительные свойства не нужны)

api.openCustomModalCard(MyModalComponent);

Типы

CustomModalPayload<BaseProps, AdditionalProps> — объект с настройками:

component — React-компонент для рендеринга
additionalProps? — дополнительные свойства для компонента
baseProps? — базовые свойства для ModalCard или ModalPage
id? — идентификатор (генерируется автоматически, если не указан)

CustomModalProps<BaseProps, AdditionalProps> — свойства, которые получает ваш компонент:

Все ваши AdditionalProps
modalProps — свойства для ModalCard или ModalPage
id — идентификатор модалки
close() — закрыть модалку
update(props) — обновить свойства

Пример с дополнительными свойствами

Когда нужно передать данные в модалку (например, функцию для открытия следующей модалки):

Загружается...

Пример без дополнительных свойств

Если дополнительные свойства не нужны, можно передать компонент напрямую:

Загружается...

useScrollLock

useTodayDate