Включение debug режима

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

import { createPopper } from '@popperjs/core';

// Пример базовой инициализации
const button = document.querySelector('#button');
const tooltip = document.querySelector('#tooltip');

const popperInstance = createPopper(button, tooltip, {
  modifiers: [
    {
      name: 'debug',
      enabled: true,
    },
  ],
});

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

  • modifiers — массив модификаторов, который управляет поведением поппера.
  • debug — встроенный модификатор, предназначенный исключительно для диагностики.
  • enabled: true активирует визуальное отображение границ элементов.

Визуальная отладка через debug модификатор

При включенном debug режиме Popper.js добавляет на страницу контурные рамки для следующих элементов:

  • reference — якорный элемент, относительно которого позиционируется поппер.
  • popper — сам всплывающий элемент.
  • arrow — стрелка, если используется модификатор arrow.

Рамки автоматически подсвечиваются различными цветами, что позволяет быстро определить ошибки позиционирования или неправильные смещения.

/* Для кастомизации визуализации debug */
.popper-debug {
  border: 2px dashed red;
  background-color: rgba(255, 0, 0, 0.1);
}
.reference-debug {
  border: 2px dashed blue;
}
.arrow-debug {
  border: 2px dashed green;
}

Интеграция с модификаторами и отладка сложных сценариев

Debug режим особенно полезен при работе с дополнительными модификаторами:

  • flip — позволяет менять позицию поппера, если пространство ограничено.
  • offset — смещает поппер относительно якоря.
  • preventOverflow — предотвращает выход поппера за границы окна.
const popperInstance = createPopper(button, tooltip, {
  placement: 'bottom',
  modifiers: [
    { name: 'offset', options: { offset: [0, 10] } },
    { name: 'flip', options: { fallbackPlacements: ['top', 'right', 'left'] } },
    { name: 'preventOverflow', options: { padding: 8 } },
    { name: 'debug', enabled: true },
  ],
});

Включение debug режима позволяет наблюдать, как каждый модификатор влияет на позиционирование поппера в реальном времени. Контуры помогают визуально оценить:

  • смещение от якоря;
  • корректность применения flip;
  • наличие перекрытий и выходов за пределы контейнера.

Логирование внутреннего состояния Popper.js

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

const logModifier = {
  name: 'log',
  enabled: true,
  phase: 'afterWrite',
  fn({ state }) {
    console.log('Popper state:', state);
  },
};

const popperInstance = createPopper(button, tooltip, {
  modifiers: [
    { name: 'debug', enabled: true },
    logModifier,
  ],
});

Особенности:

  • phase: 'afterWrite' гарантирует, что логирование происходит после применения всех изменений DOM.
  • state содержит информацию о положении popper, размерах, смещениях и активных модификаторах.
  • Совместное использование debug и логирования даёт полное представление о работе Popper.js в сложных интерфейсах.

Практические рекомендации при использовании debug режима

  1. Временное включение: debug режим не предназначен для продакшн-кода. Его следует использовать только на этапе разработки.
  2. Сочетание с кастомными стилями: задавая CSS для .popper-debug, можно сделать контуры более заметными.
  3. Отслеживание всех элементов: для сложных попперов с несколькими якорями или вложенными попперами, debug режим позволяет выявить все проблемы позиционирования.
  4. Взаимодействие с другими библиотеками: если Popper.js используется внутри React, Vue или Angular, debug режим помогает визуально сверить реальные координаты элементов с ожиданиями компонента.

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

Оглавление