Координатная система

Floating UI — это библиотека для точного позиционирования всплывающих элементов (popovers, tooltips, dropdowns) относительно целевых элементов на странице. Основой работы библиотеки является координатная система, позволяющая управлять положением и ориентацией элементов с учётом ограничений viewport и других факторов.

Система координат и контекст

Floating UI оперирует двумя основными системами координат:

  1. Координаты относительно окна (viewport) Используются для расчёта позиции относительно видимой области страницы. В этой системе верхний левый угол окна считается точкой (0, 0), а значения x и y увеличиваются вправо и вниз соответственно.

  2. Координаты относительно родителя (offset parent) Применяются, когда элемент находится внутри контейнера с CSS-свойством position: relative или position: absolute. В этом случае точка (0, 0) соответствует верхнему левому углу родителя, а не всего окна. Floating UI автоматически учитывает родительские смещения при вычислении позиции.

Основные параметры позиции

Floating UI возвращает объект с координатами:

{
  x: number, // смещение по горизонтали
  y: number, // смещение по вертикали
  placement: string // позиция относительно reference элемента
}
  • x и y — абсолютные значения смещения с учётом выбранной системы координат.
  • placement — текстовое обозначение позиции: top, bottom, left, right и их комбинации с -start и -end, например, top-start.

Относительное позиционирование и контекстные ограничения

Floating UI позволяет учитывать ограничения контейнера с помощью модификатора flip или shift. Эти модификаторы изменяют координаты, если элемент не помещается в текущей позиции:

  • flip — автоматически меняет позицию на противоположную при переполнении viewport. Например, top → bottom.
  • shift — корректирует координаты так, чтобы элемент оставался видимым, подталкивая его внутри контейнера или окна.
import { computePosition, flip, shift } from '@floating-ui/dom';

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

computePosition(reference, floating, {
  middleware: [flip(), shift({ padding: 8 })],
}).then(({ x, y }) => {
  Object.assign(floating.style, {
    left: `${x}px`,
    top: `${y}px`
  });
});

Здесь padding: 8 гарантирует, что всплывающий элемент не будет прижат к краям окна.

Точки привязки и origin

Floating UI оперирует двумя ключевыми точками:

  1. Reference point — точка на элементе, относительно которой рассчитывается позиция. Обычно это центр или край элемента.
  2. Floating point — точка на всплывающем элементе, которая будет совмещена с reference point.

Сочетание этих точек определяет точное смещение:

  • top-start — верхняя точка всплывающего элемента совмещается с верхним левым краем reference.
  • bottom-end — нижняя точка всплывающего элемента совмещается с нижним правым краем reference.

Floating UI поддерживает кастомные смещения через параметр offset, позволяя задавать любое смещение по x и y:

import { offset } from '@floating-ui/dom';

computePosition(reference, floating, {
  middleware: [offset({ mainAxis: 10, crossAxis: 5 })],
});
  • mainAxis — смещение вдоль основной оси (например, вверх/вниз для top/bottom).
  • crossAxis — смещение по перпендикулярной оси (влево/вправо).

Учет масштабирования и трансформаций

Floating UI корректно обрабатывает CSS-трансформации, такие как scale, translate или transform-origin. Библиотека использует метод getBoundingClientRect(), чтобы определить фактические координаты элементов после всех преобразований.

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

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

После расчёта координат Floating UI возвращает координаты, которые можно напрямую использовать для установки стилей top и left. При этом библиотека гарантирует:

  • Совмещение floating point с reference point.
  • Учет ограничений viewport и контейнера.
  • Возможность динамического изменения позиции при изменении размеров или прокрутке.
  • Поддержку offset, flip и shift для максимальной точности.

Заключение по координатной системе

Координатная система Floating UI строится на взаимодействии reference point, floating point, системы координат родителя или viewport, а также middleware для корректировки позиции. Понимание этих принципов позволяет точно управлять положением всплывающих элементов даже в сложных интерфейсах с динамическими размерами, трансформациями и ограничениями по экрану.

Оглавление