Управление z-index

В библиотеке Ant Design (AntD) управление z-index играет ключевую роль в организации слоёв компонентов и модальных элементов. Z-index определяет порядок наложения элементов на странице, что особенно важно при работе с модальными окнами, всплывающими подсказками, дропдаунами и тасками типа уведомлений (notification, message, tooltip).

В Ant Design структура слоёв реализована через централизованную систему zIndex в Design Tokens, что позволяет управлять наложением компонентов последовательно и предсказуемо.

Основные принципы

  1. Контекст наложения Z-index работает в контексте CSS stacking context. Если родительский элемент имеет позиционирование (position: relative/absolute/fixed) и z-index, все дочерние элементы ограничены этим контекстом. В AntD многие компоненты создают собственные контексты:

    • Modal создаёт отдельный слой через rc-dialog.
    • Dropdown использует портал (rc-trigger), чтобы избежать проблем с вложенными контекстами.

  2. Z-index в Design Tokens Ant Design использует переменные токенов для всех стандартных слоёв:

    const zIndexToken = {
  modal: 1000,
  dropdown: 1050,
  tooltip: 1060,
  notification: 1100,
  message: 1200
};

    Эти значения гарантируют, что сообщения будут поверх модальных окон, а тултипы поверх дропдаунов.

Управление z-index в компонентах

Компонент Modal автоматически использует высокий z-index для поверхностного отображения:

import { Modal, Button } from 'antd';
import { useState } from 'react';

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onCl ick={() => setOpen(true)}>Открыть модал</Button>
      <Modal
        title="Пример модала"
        open={open}
        onCan cel={() => setOpen(false)}
        zIndex={1500}  // Перезапись стандартного z-index
      >
        Содержимое модала
      </Modal>
    </>
  );
}

Особенности:

  • zIndex можно задавать напрямую через проп zIndex.
  • Если несколько модалей открываются одновременно, их порядок зависит от значения zIndex.

Dropdown и другие всплывающие элементы используют getPopupContainer для контроля контекста:

import { Dropdown, Menu, Button } from 'antd';

const menu = (
  <Menu>
    <Menu.Item>Пункт 1</Menu.Item>
    <Menu.Item>Пункт 2</Menu.Item>
  </Menu>
);

<Dropdown overlay={menu} getPopupContainer={trigger => trigger.parentNode}>
  <Button>Меню</Button>
</Dropdown>

Важное:

  • Если родитель имеет z-index, Dropdown может оказаться под другими элементами. Использование портала (getPopupContainer) позволяет избежать этого.

Tooltip

Компонент Tooltip всегда рендерится через портал, что обеспечивает корректное наложение над другими элементами. Можно настроить zIndex через ConfigProvider или локально:

<Tooltip title="Подсказка" overlayStyle={{ zIndex: 2000 }}>
  <Button>Наведи на меня</Button>
</Tooltip>

Глобальное управление через ConfigProvider

Ant Design предоставляет возможность глобально задавать z-index для всех компонентов:

import { ConfigProvider } from 'antd';

<ConfigProvider
  theme={{
    token: {
      zIndexPopup: 1050,
      zIndexModal: 1000,
    },
  }}
>
  <App />
</ConfigProvider>
  • zIndexPopup — для Dropdown, Tooltip, Popover.
  • zIndexModal — для Modal.
  • Можно также управлять zIndexMessage, zIndexNotification через кастомные токены.

Взаимодействие нескольких слоёв

При работе с несколькими наложенными компонентами важно учитывать логическую иерархию:

  1. Modal > Drawer > Dropdown > Tooltip > Notification/Message
  2. Если необходимо изменить стандартный порядок, используйте zIndex индивидуально для компонента.
  3. Избегать изменения родительского контекста без явной необходимости — это может привести к неожиданным эффектам наложения.

Практические рекомендации

  • Всегда проверять контекст родителя при работе с компонентами, создающими порталы.
  • Использовать ConfigProvider для глобальных настроек z-index, чтобы обеспечить единый стандарт для всего приложения.
  • При наложении нескольких модальных окон задавать z-index явно, чтобы избежать скрытия элементов.
  • Tooltip, Popover и Dropdown чаще всего безопасно использовать с getPopupContainer, чтобы исключить конфликт z-index с другими блоками.
  • Для динамически создаваемых уведомлений (notification, message) использовать стандартные токены AntD и при необходимости увеличивать zIndex.

Заключение по особенностям Ant Design z-index

  • z-index в Ant Design строго регулируется токенами, что упрощает управление слоями.
  • Modal, Drawer, Dropdown, Tooltip, Notification, Message имеют заранее определённые уровни, которые можно кастомизировать через props или глобально через ConfigProvider.
  • Правильное управление z-index предотвращает визуальные конфликты и обеспечивает предсказуемое наложение элементов.
  • Контроль контекста (порталы и родительские элементы) является ключевым для корректного рендеринга слоёв.

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

Оглавление