Параметры и возвращаемые значения

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

Обязательные параметры

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

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

computePosition(reference, floating);
  • reference – элемент, относительно которого позиционируется всплывающий элемент.
  • floating – сам всплывающий элемент, который нужно разместить на странице.

Опциональные параметры

Объект options передается вторым аргументом функции computePosition. Основные из них:

  1. placement – задаёт предпочтительное размещение элемента. Возможные значения: 'top', 'bottom', 'left', 'right', а также вариации с -start и -end ('top-start', 'bottom-end').

  2. strategy – определяет метод позиционирования:

    • 'absolute' – стандартное абсолютное позиционирование относительно ближайшего позиционированного предка.
    • 'fixed' – позиционирование относительно окна браузера, игнорирует прокрутку.

  3. middleware – массив функций для модификации расчета позиции. Часто используемые middleware:

    • offset – задаёт смещение от reference элемента.
    • flip – автоматически меняет сторону при недостатке места.
    • shift – корректирует положение для предотвращения выхода за границы viewport.
    • arrow – позиционирует стрелку относительно reference элемента.

Пример с использованием middleware:

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

computePosition(reference, floating, {
  placement: 'top',
  strategy: 'absolute',
  middleware: [offset(10), flip(), shift({ padding: 5 })]
});

Параметры middleware

Каждое middleware имеет свои параметры:

  • offset(value: number | { mainAxis?: number, crossAxis?: number }) – задаёт расстояние между reference и floating по основной и поперечной оси.
  • flip({ fallbackPlacements?, padding? }) – массив альтернативных позиций для автоматического переворота.
  • shift({ padding? }) – предотвращает обрезание элемента за пределами viewport. padding добавляет отступ от границ.
  • arrow({ element, padding }) – задаёт DOM-элемент стрелки и минимальный отступ от границ floating.

Возвращаемые значения computePosition

Функция возвращает Promise, который разрешается объектом с ключевыми координатами и информацией о позиции:

computePosition(reference, floating, options).then(({ x, y, placement, strategy, middlewareData }) => {
  Object.assign(floating.style, {
    left: `${x}px`,
    top: `${y}px`,
    position: strategy
  });
});

  • x, y – абсолютные координаты floating элемента относительно документа или окна.

  • placement – финальная выбранная позиция, может отличаться от запрошенной при использовании flip.

  • strategy – стратегия позиционирования (absolute или fixed).

  • middlewareData – объект с результатами middleware, например:

    {
  arrow: { x: 10, y: 5 },
  shift: { x: 0, y: 3 }
}

Примеры работы с возвращаемыми данными

Позиционирование стрелки

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

const arrowElement = document.querySelector('.tooltip-arrow');

computePosition(reference, floating, {
  middleware: [arrow({ element: arrowElement })]
}).then(({ x, y, middlewareData }) => {
  Object.assign(arrowElement.style, {
    left: `${middlewareData.arrow.x}px`,
    top: `${middlewareData.arrow.y}px`
  });
});

Сдвиг при ограничениях viewport

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

computePosition(reference, floating, {
  middleware: [shift({ padding: 10 })]
}).then(({ x, y, middlewareData }) => {
  console.log('Смещение для видимости:', middlewareData.shift);
});

Комбинирование middleware

Floating UI позволяет комбинировать несколько middleware для тонкой настройки позиции:

computePosition(reference, floating, {
  placement: 'right-start',
  middleware: [
    offset(8),
    flip({ fallbackPlacements: ['left-start', 'bottom-start'] }),
    shift({ padding: 5 }),
    arrow({ element: arrowElement, padding: 5 })
  ]
});

Такой подход гарантирует, что floating элемент не только находится в правильной позиции, но и автоматически подстраивается под пространство вокруг reference, корректно отображает стрелку и не выходит за границы viewport.

Итоговая структура возвращаемых данных

{
  x: number,             // координата X
  y: number,             // координата Y
  placement: string,     // финальная позиция
  strategy: 'absolute' | 'fixed', // стратегия позиционирования
  middlewareData: {      // данные middleware
    [middlewareName: string]: any
  }
}

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

Оглавление