Deprecated функциональность

Floating UI — это библиотека для построения плавающих интерфейсов, таких как тултипы, поповеры, дропдауны и меню. Со временем API библиотеки развивается, и некоторые функции становятся устаревшими (deprecated). Понимание того, какие методы и опции больше не поддерживаются, критично для поддержки кода и предотвращения ошибок при обновлении версии библиотеки.

Устаревшие функции позиционирования

Ранние версии Floating UI предоставляли методы позиционирования через computePosition с устаревшими опциями, которые сейчас заменены более гибкими middleware.

Примеры deprecated опций:

  • flip: { fallbackPlacements: [...] } — ранее использовалась для автоматического изменения позиции, если основной placement не помещался. Сейчас предпочтительно использовать middleware flip() с отдельной конфигурацией.
  • offset: number — прямое указание отступа между reference и floating элементом больше не рекомендуется; вместо этого применяется middleware offset() с явным указанием сдвига по оси X/Y.

Рекомендуемая замена:

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

computePosition(reference, floating, {
  middleware: [
    offset(8), // отступ 8px
    flip({ fallbackPlacements: ['top', 'right'] }),
  ],
});

Устаревшие API для работы с событиями

В предыдущих версиях библиотека предоставляла методы вроде autoUpdate() и autoPlacement, которые имели ограниченную конфигурацию:

  • autoUpdate(reference, floating, callback) — автоматически следил за изменениями размеров и скролла. Deprecated: теперь рекомендуется использовать autoUpdate из @floating-ui/dom с явным управлением подписками и отменой наблюдателей.

Современный пример:

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

const cleanup = autoUpdate(reference, floating, () => {
  computePosition(reference, floating, {
    middleware: [offset(10), flip()],
  }).then(({ x, y }) => {
    Object.assign(floating.style, {
      left: `${x}px`,
      top: `${y}px`,
    });
  });
});

// Для отмены наблюдения
cleanup();

Устаревшие middleware

Некоторые middleware полностью устарели и заменены более универсальными решениями:

  • shift (старый синтаксис) → теперь используется shift() с объектной конфигурацией { limiter: ... }.
  • arrow с устаревшей логикой смещения → заменён middleware arrow() с поддержкой современных API для позиции стрелки.

Пример обновлённого middleware для стрелки:

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

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

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

Deprecated конфигурации для React и других фреймворков

Для React раньше существовали хелперы вроде useFloating с устаревшими опциями placementStrategy и middlewareData напрямую в стейте.

Теперь рекомендуется использовать новый API:

  • strategy — заменяет устаревшие placementStrategy.
  • middleware передаются как массив через middleware без прямой модификации middlewareData.
  • Для управления обновлениями позиции используется whileElementsMounted вместо прямого autoUpdate в хук-рендере.

Пример React-хука:

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

const { x, y, reference, floating, strategy, middlewareData } = useFloating({
  placement: 'bottom',
  middleware: [
    offset(10),
    flip(),
    arrow({ element: arrowRef }),
  ],
});

Логика устаревания и обратная совместимость

Floating UI придерживается строгой политики: устаревшие методы помечаются как deprecated, но не удаляются сразу. Это позволяет:

  • Постепенно мигрировать существующий код без поломки приложений.
  • Использовать новые middleware и API для более точного управления позиционированием и производительностью.
  • Отказаться от методов, не поддерживающих современные сценарии, например динамическое изменение размеров контейнеров и сложные nested popover’ы.

При обновлении версии библиотеки следует проверять:

  1. Список deprecated функций в документации.
  2. Замены через новые middleware и API.
  3. Возможность безопасного удаления устаревших вызовов.

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

  • Любые прямые вызовы flip, offset, shift через устаревшие синтаксисы нужно переписать через новые middleware.
  • Отказаться от старых хуков и опций React в пользу useFloating с middleware и whileElementsMounted.
  • Для стрелок использовать современный arrow({ element }) вместо ручного расчёта.
  • Проверять консоль браузера на предупреждения о deprecated функциях — библиотека выводит детальные подсказки.

Устранение deprecated кода повышает стабильность, совместимость и производительность приложений, использующих Floating UI.

Оглавление