Debug режим

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

Для активации debug режима используется параметр debug при создании позиции:

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

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

computePosition(reference, floating, {
  placement: 'top',
  middleware: [offset(10), flip(), shift()],
  debug: true
});

При включении debug: true библиотека добавляет вспомогательные визуальные элементы, которые показывают:

  • границы reference и floating элементов,
  • линии направления, указывающие на точку привязки,
  • зону смещения, добавленного через middleware.

Интерактивное отслеживание через Floating UI DevTools

Floating UI совместим с отдельным инструментом Floating UI DevTools, который позволяет детально просматривать вычисленные позиции элементов в реальном времени. DevTools отображает:

  • координаты x и y для floating элемента,
  • активные middleware и их влияние на позицию,
  • порядок применения middleware, включая flip, shift, offset, arrow.

Подключение DevTools выглядит следующим образом:

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

enableDevTools({
  reference,
  floating
});

После вызова на странице появится оверлей с визуальными индикаторами, который автоматически обновляется при изменении позиции или размера элементов.

Детальный разбор отладки middleware

Debug режим позволяет увидеть поэтапное влияние каждого middleware:

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

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

Настройка кастомного визуального представления

По умолчанию Floating UI добавляет базовые цветные рамки и линии. Для более тонкой настройки можно использовать CSS-селекторы, привязанные к классам .floating-ui-debug:

.floating-ui-debug-reference {
  border: 2px dashed blue;
}

.floating-ui-debug-floating {
  border: 2px dashed red;
}

.floating-ui-debug-arrow {
  background-color: yellow;
  width: 4px;
  height: 4px;
}

Эта кастомизация позволяет создавать визуально понятные схемы для сложных UI-компонентов.

Логирование координат и событий

Помимо визуализации, debug режим позволяет логировать координаты и состояние элементов:

computePosition(reference, floating, {
  placement: 'bottom',
  middleware: [offset(10), flip()],
  debug: {
    log: true
  }
}).then(({ x, y }) => {
  console.log('Floating coordinates:', x, y);
});

Параметр log: true выводит детализированные сообщения для каждого middleware, что упрощает поиск ошибок и проверку корректности смещений.

Интеграция с динамическими интерфейсами

Debug режим особенно полезен в динамических интерфейсах, где размеры и позиции элементов меняются при взаимодействии с пользователем:

  • изменение текста или контента в floating,
  • анимации появления/исчезновения,
  • реакция на прокрутку или изменение размеров окна.

Использование debug режима совместно с DevTools позволяет в реальном времени отслеживать все изменения, предотвращая баги с наложением и обрезанием элементов.

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

  • Включать debug режим только на этапе разработки; на продакшене его лучше отключать.
  • Для элементов с position: fixed важно учитывать, что визуальные индикаторы могут не совпадать с реальными координатами при масштабировании страницы.
  • Совмещать debug режим с strategy: 'fixed' или strategy: 'absolute' для проверки корректного поведения в разных сценариях.

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

Оглавление