Метод createPopper

Метод createPopper является центральной функцией библиотеки Popper.js. Он отвечает за создание поппера — плавающего элемента, позиционируемого относительно другого элемента (так называемого reference element). Метод обеспечивает динамическое вычисление положения и позволяет корректно управлять позиционированием с учетом размеров окна, скролла и границ видимой области.

Синтаксис метода выглядит следующим образом:

const popperInstance = createPopper(reference, popper, options);
  • reference — DOM-элемент, относительно которого позиционируется поппер.
  • popper — сам плавающий элемент (DOM-элемент), который будет отображаться.
  • options — объект с настройками, управляющий поведением и стратегией позиционирования.

Настройка опций createPopper

Опции делятся на несколько ключевых категорий:

1. Позиция и стратегия (placement, strategy)

  • placement — определяет основное положение поппера относительно reference. Возможные значения:
top, bottom, left, right
top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end

Например, bottom-start размещает поппер под элементом, с выравниванием по левому краю.

  • strategy — способ позиционирования, принимает значения:
absolute | fixed

absolute учитывает ближайший позиционированный предок, fixed фиксирует элемент относительно окна просмотра.

const popperInstance = createPopper(button, tooltip, {
  placement: 'top',
  strategy: 'absolute'
});

2. Модификаторы (modifiers)

Модификаторы — это объекты, которые позволяют расширять функциональность Popper.js, изменяя или настраивая поведение поппера. Каждый модификатор имеет структуру:

{
  name: 'название',
  enabled: true, // включение/отключение модификатора
  options: { /* параметры */ },
  phase: 'phase' // optional, на какой фазе выполнять
}

Наиболее часто используемые модификаторы:

  • offset — смещение поппера относительно reference:
modifiers: [{
  name: 'offset',
  options: {
    offset: [0, 10] // [сколько по горизонтали, сколько по вертикали]
  }
}]
  • flip — автоматический перенос поппера на противоположную сторону при недостатке места:
modifiers: [{
  name: 'flip',
  options: {
    fallbackPlacements: ['top', 'right', 'bottom', 'left']
  }
}]
  • preventOverflow — предотвращает выход поппера за пределы видимой области:
modifiers: [{
  name: 'preventOverflow',
  options: {
    boundary: 'viewport', // ограничения по окну
    padding: 8 // минимальное расстояние до границ
  }
}]
  • arrow — управляет позиционированием стрелки поппера, если она есть:
modifiers: [{
  name: 'arrow',
  options: {
    element: arrowElement, // DOM-элемент стрелки
    padding: 5
  }
}]

Методы управления экземпляром Popper

После создания экземпляра через createPopper доступны следующие методы:

  • update() — пересчитывает положение поппера и применяет изменения. Возвращает промис.
  • destroy() — полностью удаляет popperInstance, отключает все слушатели.
  • setOptions(options) — позволяет изменить параметры и модификаторы динамически.
  • forceUpdate() — синхронное обновление позиции без промиса.

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

// динамическое изменение позиции
popperInstance.setOptions({
  placement: 'bottom-end'
});

// пересчет позиции после изменения DOM
popperInstance.update();

// удаление поппера
popperInstance.destroy();

Фазы модификаторов

Каждый модификатор может быть выполнен на определенной фазе жизненного цикла Popper.js:

  1. beforeRead — до чтения размеров и положения.
  2. read — получение размеров элементов.
  3. afterRead — после чтения размеров.
  4. beforeMain — перед основной обработкой.
  5. main — основная логика модификатора.
  6. afterMain — после основной обработки.
  7. beforeWrite — перед записью изменений в DOM.
  8. write — непосредственное изменение DOM.
  9. afterWrite — финальная фаза.

Фазы позволяют управлять последовательностью выполнения модификаторов и гарантировать корректное позиционирование.

Примеры комплексной конфигурации

const popperInstance = createPopper(referenceElement, tooltipElement, {
  placement: 'bottom',
  strategy: 'fixed',
  modifiers: [
    { name: 'offset', options: { offset: [0, 12] } },
    { name: 'flip', options: { fallbackPlacements: ['top', 'right'] } },
    { name: 'preventOverflow', options: { padding: 5, boundary: 'viewport' } },
    { name: 'arrow', options: { element: arrowElement, padding: 5 } }
  ]
});

В этом примере поппер будет:

  • Находиться под элементом (bottom) с отступом 12px.
  • Переноситься вверх или вправо, если нет места.
  • Не выходить за границы видимой области.
  • Стрелка будет позиционироваться с учетом 5px от краев.

Особенности работы createPopper

  • Popper.js автоматически поддерживает реактивное позиционирование при скролле или изменении размеров окна.
  • Можно использовать динамические reference и динамический контент popper без пересоздания экземпляра, достаточно вызвать update().
  • Модификаторы можно подключать или отключать на лету, что позволяет гибко настраивать поведение всплывающих элементов.
  • Стрелка поппера (arrow) позиционируется автоматически, если правильно указан модификатор arrow, и учитывает любые смещения или ограничения.

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

Оглавление