Интерфейс getBoundingClientRect

getBoundingClientRect — это встроенный метод DOM-элемента, который возвращает объект DOMRect с размерами и положением элемента относительно окна браузера. В контексте Popper.js этот метод играет ключевую роль при расчёте позиции всплывающих элементов (попперов), таких как тултипы, dropdown-меню и модальные окна.

Структура возвращаемого объекта

Метод element.getBoundingClientRect() возвращает объект с следующими свойствами:

  • x и y — координаты верхнего левого угла элемента относительно viewport по осям X и Y.
  • width и height — ширина и высота элемента.
  • top, right, bottom, left — координаты соответствующих сторон элемента относительно viewport.

Пример:

const rect = referenceElement.getBoundingClientRect();

console.log(rect.top);    // расстояние от верхнего края viewport до верхнего края элемента
console.log(rect.right);  // расстояние от левого края viewport до правого края элемента
console.log(rect.width);  // ширина элемента

Значение для Popper.js

Popper.js использует getBoundingClientRect для определения anchor элемента (reference element) и расчёта позиции popper. Метод обеспечивает точное измерение даже при прокрутке страницы или трансформациях CSS.

Основные применения:

  1. Расчёт координат поппера Popper получает размеры и положение reference-элемента через getBoundingClientRect, затем вычисляет координаты для позиционирования всплывающего элемента.

  2. Поддержка трансформаций и прокрутки В отличие от свойств типа offsetTop или offsetLeft, getBoundingClientRect учитывает текущий скролл, CSS-трансформации и масштабирование, что делает позиционирование корректным в любых условиях.

  3. Динамическое обновление позиции При изменении размера окна или содержимого страницы Popper вызывает getBoundingClientRect повторно для пересчёта позиции. Это позволяет реализовать адаптивные тултипы и меню.

Пример интеграции в Popper.js

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

const referenceElement = document.querySelector('#button');
const popperElement = document.querySelector('#tooltip');

const popperInstance = createPopper(referenceElement, popperElement, {
  placement: 'top', 
  modifiers: [
    {
      name: 'computeStyles',
      options: {
        adaptive: true,
      },
    },
  ],
});

console.log(referenceElement.getBoundingClientRect());
// => DOMRect { x: 100, y: 50, width: 80, height: 30, ... }

Здесь Popper использует объект DOMRect, возвращаемый getBoundingClientRect, чтобы определить точку привязки поппера и применить нужные смещения для точного позиционирования.

Важные нюансы

  • Относительно viewport: координаты getBoundingClientRect всегда возвращаются относительно видимой области окна браузера, а не документа.
  • Поддержка трансформаций: метод корректно учитывает CSS transform: scale, translate, что позволяет точно позиционировать попперы даже при изменениях визуального масштаба элемента.
  • Поддержка Subpixel-значений: возвращаемые координаты могут быть дробными числами, что повышает точность при позиционировании мелких элементов.
  • Не учитывает margin: метод возвращает размеры без внешних отступов, поэтому если нужно учитывать margin, необходимо делать дополнительные вычисления.

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

  • Для вычисления позиции поппера всегда использовать getBoundingClientRect, а не offsetTop/offsetLeft, чтобы учесть прокрутку и трансформации.
  • При работе с анимациями или динамически изменяющимися элементами стоит обновлять Popper через update() после изменения размеров или позиции reference-элемента.
  • Если элемент скрыт (display: none), метод вернёт 0 для всех координат и размеров. Для корректной работы поппера нужно убедиться, что reference-элемент видим.

getBoundingClientRect — фундаментальный инструмент для точного позиционирования в Popper.js, обеспечивающий согласованность координат и размеров вне зависимости от скролла, трансформаций и динамически изменяемого контента.

Оглавление