Типы данных

Библиотека Floating UI для JavaScript ориентирована на управление позиционированием всплывающих элементов, таких как тултипы, поповеры и контекстные меню. Для работы с этой библиотекой важно понимать, какие типы данных она использует, какие объекты создаются и передаются в функции, а также как они взаимодействуют между собой.

Element и VirtualElement

Element — это стандартный DOM-элемент (HTMLElement), который используется в качестве якоря (reference) или всплывающего элемента (floating). Большинство функций Floating UI ожидают именно реальный элемент из DOM.

VirtualElement — объект, имитирующий DOM-элемент, который предоставляет методы:

  • getBoundingClientRect() — возвращает объект с размерами и координатами виртуального элемента.
  • contextElement (необязательный) — указывает на реальный DOM-контекст, необходимый для вычислений.

Пример использования виртуального элемента:

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

Координаты и размеры: ClientRect и Rect

Floating UI активно использует объекты типа ClientRect и Rect для позиционирования. Эти объекты содержат поля:

  • x, y — координаты верхнего левого угла.
  • width, height — размеры элемента.
  • top, right, bottom, left — дополнительные границы.

Важно понимать, что методы библиотеки возвращают координаты в вьюпорте, а не в документе. Для учета прокрутки можно использовать свойства window.scrollX и window.scrollY.

Middleware и их опции

Middleware — это массив функций, которые изменяют позицию всплывающего элемента. Каждая функция middleware получает объект с типами данных:

  • x: number — текущее горизонтальное смещение.
  • y: number — текущее вертикальное смещение.
  • placement: Placement — строка с позицией (top, bottom, left, right, включая варианты с -start и -end).
  • strategy: Strategy — absolute или fixed.

Middleware возвращает объект с полями:

  • x, y — новые координаты.
  • data (необязательный) — дополнительные вычисленные значения, передаваемые следующему middleware.

Пример middleware:

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

offset({ mainAxis: 10, crossAxis: 5 });

Здесь mainAxis и crossAxis — числовые значения, определяющие смещение.

Placement и Strategy

Placement — это строковый тип данных, описывающий расположение всплывающего элемента относительно референса. Возможные значения:

  • top, bottom, left, right
  • top-start, top-end, bottom-start, bottom-end
  • left-start, left-end, right-start, right-end

Strategy — строковый тип, принимающий только два значения:

  • absolute — позиция относительно ближайшего родителя с position: relative.
  • fixed — фиксированная позиция относительно окна.

Эти типы передаются в функции computePosition и используются для корректного расчета координат.

FloatingContext и ReferenceContext

Некоторые функции, особенно при работе с React-обертками Floating UI, используют объекты контекста. Основные поля:

  • x, y — текущие координаты.
  • placement — текущее размещение.
  • strategy — стратегия позиционирования.
  • middlewareData — объект с результатами middleware.
  • refs — ссылки на DOM-элементы reference и floating.

Эти объекты позволяют управлять состоянием позиции и интегрироваться с компонентами UI, сохраняя типовую безопасность и удобство работы с данными.

Типы для событий: PointerCoords и MouseEvent

Для интерактивных всплывающих элементов Floating UI иногда использует координаты указателя. Основные поля:

  • clientX, clientY — координаты курсора относительно окна.
  • pageX, pageY — координаты относительно документа.

Эти типы данных позволяют реализовать middleware, основанные на позиции курсора, например followCursor.

Итоговая структура данных

Floating UI опирается на строгие типы данных, каждый из которых отвечает за свою область:

  • DOM-элементы (Element / VirtualElement) — источник координат.
  • Объекты размеров и координат (Rect, ClientRect) — внутренние вычисления.
  • Middleware и их возвращаемые объекты — трансформация позиции.
  • Стратегии и размещения (Strategy, Placement) — логика расположения.
  • Контексты (FloatingContext, ReferenceContext) — управление состоянием.
  • События и координаты курсора (PointerCoords) — интерактивное управление.

Понимание этих типов данных является ключевым для эффективного использования Floating UI и построения стабильных, гибких интерфейсов, которые правильно реагируют на изменения DOM, размеры элементов и действия пользователя.

Оглавление