Визуализация boundaries

В Popper.js boundaries определяют область, внутри которой всплывающий элемент (popper) может позиционироваться. Они предотвращают выход подсказок, тултипов или меню за пределы видимой области или контейнера, улучшая юзабилити и визуальную согласованность интерфейса.

Popper.js поддерживает несколько способов задания boundaries: через DOM-элемент, viewport или определённые контейнеры. Каждая из этих опций управляется опцией preventOverflow в конфигурации Popper.

import { createPopper } from '@popperjs/core';

const reference = document.querySelector('#button');
const popper = document.querySelector('#tooltip');

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        boundary: 'viewport', // 'clippingParents' | HTMLElement | 'viewport'
        padding: 8, // отступ от границ
      },
    },
  ],
});

В примере выше boundary: 'viewport' гарантирует, что popper не выйдет за пределы видимой области экрана. Параметр padding позволяет задать минимальное расстояние до границ.

Типы boundaries

  1. Viewport – ограничение видимой областью окна браузера. Используется по умолчанию, когда важно, чтобы popper всегда оставался в зоне видимости.

  2. Clipping Parents – ограничения родительскими элементами с установленным overflow (hidden, scroll или auto). Это полезно, когда popper находится внутри контейнера с прокруткой и нельзя позволить ему «вылезать» за его пределы.

  3. HTML элемент – можно передать конкретный элемент DOM для ограничения popper. Пример:

options: {
  boundary: document.querySelector('#container')
}
  1. Custom Rect – для динамических или виртуальных контейнеров можно передать объект с координатами top, bottom, left, right. Это расширенный вариант для сложных интерфейсов с нестандартной версткой.

Модификатор preventOverflow

Модификатор preventOverflow отвечает за соблюдение границ и может быть тонко настроен через опции:

  • mainAxis – контролирует предотвращение выхода по основной оси (top/bottom или left/right, в зависимости от placement).
  • altAxis – предотвращает выход по альтернативной оси.
  • tether – связывает popper с reference и не позволяет ему полностью уйти за границу, но может допускать частичное смещение.
  • tetherOffset – смещение для привязки, числовое значение или функция.

Пример:

{
  name: 'preventOverflow',
  options: {
    mainAxis: true,
    altAxis: true,
    tether: true,
    tetherOffset: 10,
    boundary: 'clippingParents'
  }
}

В этом случае popper будет максимально оставаться внутри родительских элементов с overflow, учитывая отступ 10px и возможность частично отходить к границе.

Взаимодействие с flip

Модификатор flip автоматически меняет направление popper, если он не помещается внутри boundaries. При корректной настройке preventOverflow и flip popper никогда не пересечёт заданные границы, а при нехватке места — изменит placement.

modifiers: [
  {
    name: 'flip',
    options: {
      fallbackPlacements: ['top', 'right', 'bottom', 'left']
    }
  },
  {
    name: 'preventOverflow',
    options: {
      boundary: 'viewport',
      padding: 5
    }
  }
]

Советы по использованию boundaries

  • Для всплывающих подсказок лучше использовать viewport или clippingParents, чтобы гарантировать видимость на всех разрешениях.
  • Для сложных контейнеров с прокруткой часто комбинируют preventOverflow с flip, чтобы popper адаптивно менял позицию.
  • Не рекомендуется задавать слишком маленький padding, иначе popper может «прилипать» к краям и визуально ломать дизайн.
  • В случае кастомных контейнеров можно вычислять границы через getBoundingClientRect() и передавать объект вручную, что позволяет контролировать нестандартные сценарии.

Отслеживание динамических изменений

Если размеры boundaries изменяются во время работы интерфейса (например, изменение размеров контейнера или окна), Popper.js обеспечивает автоматическое пересчитывание позиции popper через update():

popper.update();

Для динамических интерфейсов рекомендуется вызывать update() после любых изменений DOM, которые могут повлиять на boundaries, чтобы popper оставался корректно позиционированным.

Резюме по визуализации boundaries

  • Boundaries ограничивают область, в которой popper может отображаться.
  • Используются опции preventOverflow и boundary, а также параметры padding, mainAxis, altAxis, tether.
  • Комбинируется с flip для автоматической смены позиции при нехватке места.
  • Поддерживает стандартные контейнеры, viewport, кастомные элементы и прямоугольники.
  • Для динамических интерфейсов необходимо использовать update() после изменения размеров или положения boundaries.

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

Оглавление