createPopper

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

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

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

const popperInstance = createPopper(reference, popper, {
  placement: 'top',
});

Параметры createPopper:

  1. reference — DOM-элемент или виртуальный объект, относительно которого будет позиционироваться поппер.
  2. popper — DOM-элемент, который будет отображаться как поппер.
  3. options — объект с настройками, включая placement, modifiers и strategy.

Параметр placement

placement определяет позицию поппера относительно reference. Возможные значения:

  • Основные: 'top', 'bottom', 'left', 'right'
  • С уточнением направления: 'top-start', 'top-end', 'bottom-start', 'bottom-end'

Пример:

createPopper(reference, popper, {
  placement: 'bottom-end',
});

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

  • Если выбранное место не помещается на экране, Popper автоматически подбирает альтернативное место.
  • placement может быть динамическим, управляемым через модификатор flip.

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

Модификаторы позволяют управлять поведением поппера: смещением, адаптацией под viewport, добавлением стрелок и т.д.

Структура модификатора:

{
  name: 'offset',
  options: {
    offset: [0, 8], // горизонтальное и вертикальное смещение
  },
}

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

  1. offset — задаёт смещение поппера относительно reference.
  2. flip — автоматически изменяет позицию, если поппер выходит за границы окна.
  3. preventOverflow — предотвращает выход поппера за пределы контейнера или viewport.
  4. arrow — добавляет стрелку, указывающую на reference; требует указания элемента стрелки.
  5. computeStyles — управляет стратегией позиционирования (absolute или fixed) и стилями transform.

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

createPopper(reference, popper, {
  placement: 'top',
  modifiers: [
    {
      name: 'offset',
      options: { offset: [0, 10] },
    },
    {
      name: 'flip',
      options: { fallbackPlacements: ['bottom', 'right'] },
    },
    {
      name: 'arrow',
      options: { element: document.querySelector('#arrow') },
    },
  ],
});

Стратегии позиционирования

Popper.js поддерживает две стратегии позиционирования:

  1. absolute — поппер позиционируется относительно ближайшего родителя с position: relative/absolute.
  2. fixed — поппер фиксируется относительно окна (viewport), игнорируя скролл родительских элементов.
createPopper(reference, popper, {
  strategy: 'fixed',
});

Методы объекта popperInstance

createPopper возвращает объект с API для управления поппером:

  • update() — пересчитывает и обновляет позицию.
  • forceUpdate() — немедленно пересчитывает позицию без задержки.
  • destroy() — удаляет поппер и отключает все слушатели событий.

Пример динамического обновления:

popperInstance.update();

Виртуальные элементы

Popper.js позволяет использовать объекты вместо реальных DOM-элементов. Такой объект должен иметь свойства getBoundingClientRect() и contextElement. Это полезно, когда нужно позиционировать поппер относительно координат курсора или canvas-элемента.

const virtualReference = {
  getBoundingClientRect: () => ({
    width: 0,
    height: 0,
    top: 100,
    bottom: 100,
    left: 200,
    right: 200,
  }),
  contextElement: document.body,
};

createPopper(virtualReference, popper);

Динамическое управление

Поппер можно динамически менять:

  • Изменять placement через setOptions:
popperInstance.setOptions({
  placement: 'right-start',
});
  • Добавлять или удалять модификаторы на лету.
popperInstance.setOptions({
  modifiers: [{ name: 'offset', options: { offset: [0, 20] } }],
});
  • Удалять поппер полностью:
popperInstance.destroy();

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

  • Использовать modifiers: [{ name: 'eventListeners', enabled: false }] для временного отключения слежения за scroll/resize.
  • Применять strategy: 'fixed' для элементов в модальных окнах и фиксированных контейнерах.
  • Минимизировать количество сложных модификаторов при массовом рендере попперов.

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

Оглавление