Утилитарные функции

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

getBoundingClientRect(element)

Функция возвращает объект с координатами и размерами элемента относительно видимой области окна (viewport). Возвращаемый объект содержит свойства: top, left, bottom, right, width, height.

Применение:

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

const element = document.querySelector('#tooltip');
const rect = getBoundingClientRect(element);
console.log(rect.top, rect.left, rect.width, rect.height);

Особенность: учитывает трансформации CSS, такие как scale и rotate, что делает её точнее стандартного element.getBoundingClientRect() в ряде случаев.

getLayoutRect(element)

Возвращает физические размеры элемента без учета трансформаций CSS и прокрутки. Содержит свойства x, y, width, height.

Применение:

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

const rect = getLayoutRect(element);
console.log(rect.width, rect.height);

Полезна при вычислении размеров, когда требуется чистая геометрия элемента.

orderModifiers(modifiers)

Сортирует массив модификаторов в правильном порядке выполнения, учитывая их зависимости друг от друга.

Применение:

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

const modifiers = [
  { name: 'flip', phase: 'main', requires: ['preventOverflow'] },
  { name: 'preventOverflow', phase: 'main' }
];

const ordered = orderModifiers(modifiers);
console.log(ordered.map(mod => mod.name)); // ["preventOverflow", "flip"]

Используется при создании кастомных Popper-инстансов с модификаторами в специфическом порядке.

debounce(fn)

Создает функцию с отложенным выполнением, предотвращая слишком частые вызовы, например, при изменении размера окна или скролле.

Применение:

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

const updatePopper = () => console.log('Обновление позиции');
const debouncedUpdate = debounce(updatePopper, 100);

window.addEventListener('resize', debouncedUpdate);

Позволяет оптимизировать производительность при частых событиях.

getVariation(placement)

Возвращает вариацию позиции, если она указана. Например, для placement: 'top-start' вернет 'start'.

Применение:

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

const variation = getVariation('bottom-end');
console.log(variation); // "end"

Используется в модификаторах, когда необходимо обрабатывать вариации отдельно от основной позиции.

getOppositePlacement(placement)

Возвращает противоположное положение относительно исходного.

Применение:

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

console.log(getOppositePlacement('top')); // "bottom"
console.log(getOppositePlacement('left-start')); // "right-start"

Ключевой инструмент для реализации логики flip в кастомных модификаторах.

within(min, value, max)

Функция ограничивает значение value в диапазоне [min, max].

Применение:

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

console.log(within(0, 150, 100)); // 100
console.log(within(0, -50, 100)); // 0
console.log(within(0, 50, 100));  // 50

Часто используется для предотвращения выхода всплывающих элементов за пределы контейнера.

mergeByName(modifiers)

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

Применение:

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

const modifiers = [
  { name: 'offset', options: { offset: [0, 8] } },
  { name: 'offset', options: { offset: [0, 16] } }
];

const merged = mergeByName(modifiers);
console.log(merged); // [{ name: 'offset', options: { offset: [0, 16] } }]

Обеспечивает корректную работу пользовательских конфигураций с повторяющимися модификаторами.

detectOverflow(state, options)

Вычисляет, насколько элемент выходит за пределы указанных границ (boundary). Возвращает объект с величинами top, bottom, left, right.

Применение:

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

const overflow = detectOverflow({
  state: popperState,
  options: { boundary: document.body }
});

console.log(overflow.top, overflow.bottom);

Используется в модификаторах preventOverflow и flip, а также при создании собственных ограничений позиции.

computeOffsets({ reference, element, placement })

Вычисляет смещение элемента относительно опорного (reference) для конкретного placement.

Применение:

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

const offsets = computeOffsets({
  reference: referenceRect,
  element: elementRect,
  placement: 'top'
});

console.log(offsets.x, offsets.y);

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

Итоговый набор утилитарных функций

  • Работа с размерами и координатами: getBoundingClientRect, getLayoutRect, computeOffsets
  • Управление модификаторами: orderModifiers, mergeByName, getVariation, getOppositePlacement
  • Оптимизация и ограничение значений: debounce, within
  • Проверка границ и переполнений: detectOverflow

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

Оглавление