Типы Modifiers

В Popper.js модификаторы (modifiers) — это объекты, которые изменяют поведение поппера на этапе его вычисления позиции. Они применяются последовательно и могут как корректировать расположение поппера, так и изменять его стили, поведение при столкновениях или добавлять кастомные эффекты. Каждый модификатор содержит обязательное свойство name и функцию fn, выполняющую основную логику модификатора. Кроме того, модификаторы могут иметь флаги enabled и phase, задающие активацию и фазу применения.

Фазы исполнения модификаторов:

  • read — получение данных о DOM, размеры и положение элементов.
  • main — основной этап изменения позиции и стилей.
  • write — запись вычисленных стилей в DOM.
  • afterWrite — дополнительные действия после применения стилей.

Понимание фаз важно для правильного использования и создания кастомных модификаторов.

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

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

offset

Модификатор смещения изменяет позицию поппера относительно целевого элемента.

Ключевые свойства:

{
  name: 'offset',
  options: {
    offset: [0, 8] // смещение по оси X и Y
  }
}

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

  • Первый элемент массива отвечает за горизонтальное смещение, второй — за вертикальное.
  • Может применяться как для сдвига поппера, так и для создания отступов между поппером и reference-элементом.

preventOverflow

Модификатор предотвращает выход поппера за пределы видимой области.

Опции:

{
  name: 'preventOverflow',
  options: {
    boundary: 'viewport', // или 'clippingParents'
    padding: 8
  }
}

Характеристики:

  • boundary задает границы, внутри которых поппер должен оставаться.
  • padding добавляет отступ от границ, предотвращая прилипающий эффект к краям.
  • Работает совместно с flip для динамического изменения позиции.

flip

Позволяет попперу автоматически менять положение при ограниченном пространстве.

Пример конфигурации:

{
  name: 'flip',
  options: {
    fallbackPlacements: ['top', 'right', 'left'],
    padding: 5
  }
}

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

  • fallbackPlacements — массив альтернативных позиций, которые Popper.js будет проверять.
  • Интегрируется с preventOverflow для корректного поведения при ограниченной видимости.

arrow

Используется для создания указателя (стрелки) на поппере.

Пример:

{
  name: 'arrow',
  options: {
    element: '.arrow',
    padding: 5
  }
}

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

  • element — DOM-узел стрелки.
  • padding защищает стрелку от соприкосновения с границами popper или reference.
  • Работает только в связке с позиционированием поппера, корректируя смещение стрелки.

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

Создание собственного модификатора возможно через объект с обязательными полями:

{
  name: 'customModifier',
  enabled: true,
  phase: 'main',
  fn({ state, options, name }) {
    // логика модификатора
  }
}

Параметры функции fn:

  • state — объект состояния поппера: позиции, размеры элементов, активные модификаторы.
  • options — настройки модификатора, переданные пользователем.
  • name — имя модификатора для удобства логирования и отладки.

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

  • Можно изменять state.styles, state.attributes и state.modifiersData.
  • Можно добавлять новые вычисления для сложных интерфейсных эффектов.
  • Поддерживают все фазы (read, main, write, afterWrite), что позволяет гибко управлять порядком исполнения.

Последовательность и приоритет модификаторов

Popper.js выполняет модификаторы в порядке их объявления. При этом важно учитывать:

  • enabled: false отключает модификатор полностью.
  • Модификаторы, влияющие на позицию (offset, flip, preventOverflow), должны идти раньше визуальных модификаторов (arrow, applyStyles).
  • С помощью поля requires можно указать зависимость модификатора от других, гарантируя корректный порядок вычислений.

Пример:

{
  name: 'arrow',
  enabled: true,
  phase: 'main',
  requires: ['popperOffsets']
}

arrow будет выполняться только после того, как Popper.js вычислит смещение поппера (popperOffsets).

Ключевые рекомендации по работе с модификаторами

  • Использовать встроенные модификаторы для стандартного поведения.
  • Кастомные модификаторы применять только при необходимости специфических эффектов.
  • Указывать фазы правильно, чтобы избежать конфликтов и лишних пересчетов стилей.
  • Контролировать последовательность и зависимости модификаторов через requires.
  • При использовании нескольких модификаторов, влияющих на позицию, проверять совместимость опций (offset, padding, fallbackPlacements).

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

Оглавление