Visual regression тесты

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

Установка и подключение

Для работы с Floating UI достаточно установить пакет через npm:

npm install @floating-ui/dom

После установки можно подключать его в проекте:

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

Базовое позиционирование

Для отображения всплывающего блока рядом с целевым элементом используется функция computePosition:

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

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

Ключевые моменты:

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

Работа с коллизиями

В Floating UI встроенные стратегии предотвращения выхода всплывающих элементов за пределы окна или контейнера:

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

Пример с autoPlacement:

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

computePosition(reference, floating, {
  middleware: [autoPlacement({ alignment: 'start', padding: 10 })],
}).then(({ x, y }) => {
  Object.assign(floating.style, {
    left: `${x}px`,
    top: `${y}px`,
  });
});

Динамическое обновление позиции

Floating UI позволяет отслеживать изменения размера окна или положения цели с помощью функции autoUpdate:

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

autoUpdate(reference, floating, () => {
  computePosition(reference, floating, {
    placement: 'top',
    middleware: [offset(10), flip(), shift({ padding: 5 })],
  }).then(({ x, y }) => {
    Object.assign(floating.style, {
      left: `${x}px`,
      top: `${y}px`,
    });
  });
});
  • autoUpdate автоматически пересчитывает координаты при изменении размеров окна, прокрутке или изменении позиции цели.
  • Можно остановить обновление, вызвав возвращённую функцию очистки.

Интеграция с фреймворками

React

В React можно использовать Floating UI с хуками:

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

function Tooltip({ children }) {
  const { x, y, reference, floating } = useFloating({
    placement: 'bottom',
    middleware: [offset(8), flip(), shift({ padding: 5 })],
  });

  return (
    <>
      
      

        {children}
      

    
  );
}
  • Хук useFloating возвращает координаты и ссылки на элементы.
  • Мидлвары работают аналогично чистому DOM API.

Vue

В Vue 3 интеграция реализуется через реактивные свойства:

import { ref, onMounted } from 'vue';
import { computePosition, offset, flip, shift, autoUpdate } from '@floating-ui/dom';

export default {
  setup() {
    const reference = ref(null);
    const floating = ref(null);

    onMounted(() => {
      autoUpdate(reference.value, floating.value, () => {
        computePosition(reference.value, floating.value, {
          placement: 'right',
          middleware: [offset(10), flip(), shift({ padding: 5 })],
        }).then(({ x, y }) => {
          Object.assign(floating.value.style, { left: `${x}px`, top: `${y}px` });
        });
      });
    });

    return { reference, floating };
  },
};

Дополнительные возможности

  • Arrow — встроенная поддержка стрелок у всплывающих элементов, с автоматическим смещением.
  • Hide — модификатор для скрытия элемента, если он полностью выходит за пределы видимой области.
  • Strategy — выбор между absolute и fixed позиционированием для разных сценариев.

Практические советы

  • Всегда комбинировать flip и shift для предотвращения обрезки элементов.
  • Использовать autoUpdate для интерактивных компонентов, особенно при динамическом контенте.
  • Минимизировать использование сложных вложенных мидлваров без необходимости — это повышает производительность.
  • Для адаптивных интерфейсов применять autoPlacement с alignment и padding для лучшей подстройки под разные размеры экрана.
Оглавление