Базовое смещение элемента

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

Опция offset

Смещение задается через модификатор offset. Оно определяет расстояние в пикселях (или процентах) между поппером и референсом. В Popper.js версии 2 синтаксис выглядит следующим образом:

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

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

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10], // [skid, distance]
      },
    },
  ],
});
  • skid — смещение по оси, перпендикулярной основной оси поппера. Для top и bottom это горизонтальное смещение, для left и right — вертикальное.
  • distance — расстояние между поппером и референсом по основной оси.

Например, [0, 10] означает, что поппер будет находиться на 10 пикселей ниже элемента при положении top или выше при положении bottom.

Динамическое смещение через функцию

Модификатор offset может принимать функцию, что позволяет динамически изменять смещение в зависимости от размеров элементов или других условий:

offset: ({ popper, reference, placement }) => {
  if (placement.startsWith('top')) {
    return [0, reference.offsetHeight + 5];
  } else {
    return [0, 10];
  }
}

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

  • popper — DOM-элемент поппера.
  • reference — DOM-элемент, к которому привязан поппер.
  • placement — текущая позиция поппера (top, bottom, left, right).

Функция должна возвращать массив [skid, distance], аналогичный статической конфигурации.

Влияние смещения на адаптивность

Смещение играет важную роль при использовании авто-позиционирования (flip). Если смещение слишком большое, Popper может не помещаться в видимой области, и срабатывание модификатора flip может привести к неожиданному поведению. Рекомендуется:

  • Проверять значения смещения для всех позиций (top, bottom, left, right).
  • Использовать функцию для вычисления смещения в зависимости от реальных размеров поппера и референса.
  • При необходимости ограничивать максимальное смещение через модификатор preventOverflow.

Комбинация с другими модификаторами

Смещение тесно взаимодействует с модификаторами:

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

Пример комбинирования:

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'offset',
      options: { offset: [0, 12] },
    },
    { name: 'flip', options: { fallbackPlacements: ['top', 'bottom'] } },
    { name: 'preventOverflow', options: { padding: 8 } },
    { name: 'arrow', options: { element: '.arrow' } },
  ],
});

Практические рекомендации по смещению

  • Минимальное смещение: для большинства тултипов достаточно 6–10 пикселей, чтобы визуально отделять поппер от референса.
  • Увеличенное смещение: полезно для дропдаунов или больших панелей, чтобы они не перекрывали целевой элемент.
  • Динамическое смещение: предпочтительно для адаптивного дизайна, когда размеры поппера могут меняться.
  • Использование отрицательного смещения: позволяет частично накладывать поппер на референс, если это требуется по дизайну.

Тонкости поведения при разных позициях

  • Top / Bottom: distance управляет вертикальным отступом, skid — горизонтальным.
  • Left / Right: distance управляет горизонтальным отступом, skid — вертикальным.
  • Комбинированное смещение: [skid, distance] можно использовать для точного позиционирования по обеим осям.

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

Оглавление