Основные направления размещения

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

Принцип работы основных направлений

В Popper.js используется понятие placement, которое задаёт базовое направление размещения popper относительно reference. Каждое направление может быть основным или иметь вариацию по оси. Базовые направления включают:

  • top — popper располагается над reference, по вертикальной оси;
  • bottom — popper располагается под reference;
  • left — popper располагается слева от reference, по горизонтальной оси;
  • right — popper располагается справа от reference.

Каждое из этих направлений может быть уточнено с помощью вариантов по оси, чтобы точно контролировать выравнивание:

  • start — выравнивание по началу оси reference;
  • end — выравнивание по концу оси reference.

Пример синтаксиса:

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

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

createPopper(reference, popper, {
  placement: 'top-start', // popper над кнопкой, выравнивание по левому краю
});

Полные комбинации placement

Основные направления с вариациями дают следующие комбинации:

Направление Вариант start Вариант end
top top-start top-end
bottom bottom-start bottom-end
left left-start left-end
right right-start right-end

Без варианта (top, bottom, left, right) popper будет центрирован по соответствующей оси reference.

Автоматическое смещение и flip

Popper.js предоставляет модификатор flip, который позволяет автоматически менять направление popper, если выбранное placement выходит за границы видимой области:

createPopper(reference, popper, {
  placement: 'top',
  modifiers: [
    {
      name: 'flip',
      options: {
        fallbackPlacements: ['bottom', 'right', 'left'], // альтернативные направления
      },
    },
  ],
});
  • fallbackPlacements задаёт порядок, в котором библиотека будет пробовать альтернативные позиции.
  • Если основной popper не помещается в viewport, он автоматически выбирает первое доступное направление из списка.

Настройка смещения относительно reference

Для точной позиции поппера используется модификатор offset, который задаёт сдвиг по основной и перекрёстной оси:

createPopper(reference, popper, {
  placement: 'bottom-end',
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10], // 0 по перекрестной оси, 10px по основной
      },
    },
  ],
});
  • Первый параметр массива [skid, distance] отвечает за смещение по перекрёстной оси (skid), второй — за смещение по основной оси (distance).
  • Для bottom-end это означает 10px вниз от края reference, без смещения влево/вправо.

Сложные сценарии позиционирования

Popper.js поддерживает комбинацию направлений и вариаций с динамическим переключением:

  1. Автоопределение направления: использование placement: 'auto' позволяет библиотеке выбирать оптимальное направление на основе доступного пространства.
  2. Комбинирование с flip и preventOverflow: позволяет popper оставаться видимым и корректно позиционироваться при изменении размеров окна или содержимого.
createPopper(reference, popper, {
  placement: 'auto',
  modifiers: [
    { name: 'flip', options: { fallbackPlacements: ['top', 'right', 'left', 'bottom'] } },
    { name: 'preventOverflow', options: { padding: 8 } },
  ],
});
  • preventOverflow гарантирует, что popper не выйдет за границы viewport, добавляя защиту от выхода за пределы экрана.

Важные особенности работы направлений

  • Направления учитывают размеры reference и popper. Popper.js рассчитывает позицию с точностью до пикселя.
  • Вариации start/end адаптируются под направление письма (LTR/RTL). В RTL-режиме start выравнивается по правому краю reference, end — по левому.
  • Изменение направления при анимациях плавно корректирует позицию popper без дергания.

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

  • Для информационных тултипов чаще всего используют top или bottom.
  • Для контекстных меню оптимально bottom-start или bottom-end, чтобы элементы не перекрывали reference.
  • Для динамических модальных элементов следует комбинировать auto с flip и preventOverflow, чтобы popper адаптировался под размеры окна.

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

Оглавление