Встроенные модификаторы

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

Основные встроенные модификаторы

offset

Модификатор offset управляет смещением popper относительно reference. Его можно задавать в виде массива [skidding, distance]:

const popperInstance = Popper.createPopper(referenceElement, popperElement, {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10] // смещение по горизонтали и вертикали
      },
    },
  ],
});
  • skidding — горизонтальное смещение относительно позиции popper.
  • distance — вертикальное смещение относительно позиции reference.

Используется для создания отступов, корректировки позиции tooltip или dropdown.

preventOverflow

Модификатор предотвращает выход popper за границы окна или указанного контейнера:

{
  name: 'preventOverflow',
  options: {
    boundary: 'viewport', // 'clippingParents' или конкретный элемент
    padding: 8,           // отступ от границ
  },
}

Ключевые параметры:

  • boundary — определяет, по каким границам проверять overflow.
  • padding — внутренний отступ, чтобы popper не прилипал к краям.

Этот модификатор особенно важен для адаптивного дизайна, когда popper должен оставаться видимым на всех разрешениях экрана.

flip

Модификатор flip автоматически меняет положение popper, если основная позиция не помещается на экране:

{
  name: 'flip',
  options: {
    fallbackPlacements: ['top', 'right', 'left'], 
    boundary: document.body,
  },
}
  • fallbackPlacements — массив альтернативных позиций, которые будут проверяться.
  • boundary — контейнер, относительно которого проверяется возможность флипа.

Используется, чтобы tooltip или dropdown не скрывался за границами окна.

arrow

Модификатор arrow позволяет автоматически позиционировать стрелку popper к reference:

{
  name: 'arrow',
  options: {
    element: arrowElement, // DOM-элемент стрелки
    padding: 5,            // отступ от краёв popper
  },
}
  • element — элемент стрелки, который будет позиционироваться.
  • padding — минимальное расстояние стрелки от краёв popper.

Модификатор работает только в сочетании с другими, влияющими на позицию, такими как offset или preventOverflow.

computeStyles

Модификатор отвечает за вычисление CSS-свойств top, left, transform для popper:

{
  name: 'computeStyles',
  options: {
    adaptive: true, // включает динамическое изменение transform при скролле
    gpuAcceleration: true, // использует transform для ускорения рендеринга
  },
}
  • adaptive — оптимизирует позиционирование при изменении размеров окна.
  • gpuAcceleration — повышает производительность, используя CSS-трансформации вместо прямого изменения top/left.

applyStyles

Модификатор, который применяет рассчитанные стили к DOM-элементу:

{
  name: 'applyStyles',
  options: {
    // дополнительные опции отсутствуют, модификатор работает автоматически
  },
}

Он получает результаты computeStyles и обновляет inline-стили popper и стрелки. Без него popper будет позиционироваться только в памяти, но визуально не изменит положение.

eventListeners

Модификатор управляет подпиской на события scroll и resize:

{
  name: 'eventListeners',
  enabled: true,
}
  • enabled — включение или отключение событий.
  • Обеспечивает автоматическое обновление позиции popper при скролле и изменении размера окна.
  • Может быть отключен для статичных элементов, чтобы уменьшить нагрузку на рендер.

Взаимодействие модификаторов

  1. Порядок выполнения Модификаторы выполняются в порядке массива modifiers. Это критично: например, computeStyles должен идти после offset и flip, а applyStyles всегда последний.

  2. Опция phase Каждый модификатор имеет фазу выполнения:

    • read — чтение размеров и позиции элементов.
    • main — вычисления позиционирования.
    • write — применение изменений к DOM.

  3. Опция requires Позволяет указать зависимость модификатора от другого:

    {
  name: 'arrow',
  options: { element: arrowElement },
  requires: ['popperOffsets'],
}

  4. Совместимость Некоторые модификаторы, такие как flip и preventOverflow, лучше использовать вместе, чтобы popper корректно реагировал на изменение границ видимости.

Настройка поведения встроенных модификаторов

  • Отключение модификатора:

    { name: 'flip', enabled: false }

  • Переопределение опций:

    {
  name: 'offset',
  options: { offset: [10, 20] }
}

  • Добавление пользовательских модификаторов Встроенные модификаторы могут быть дополнены кастомными функциями, но их порядок и фаза выполнения должны быть согласованы с phase и requires.

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

Оглавление