Модификаторы Popper.js

Shepherd.js использует Popper.js для управления позиционированием тултипов и шагов интерактивных туров. Popper.js предоставляет мощный механизм, позволяющий контролировать поведение всплывающих элементов относительно целевых узлов DOM. Ключевым инструментом в этом является система модификаторов, которая расширяет стандартное поведение позиционирования и позволяет гибко настраивать внешний вид и расположение шагов.

Основные принципы работы модификаторов

Модификаторы — это объекты с набором свойств, которые описывают, как Popper.js должен корректировать положение поппера:

  • name — уникальное имя модификатора, например offset, preventOverflow, flip.
  • enabled — логическое значение, активен ли модификатор.
  • options — объект с настройками модификатора.
  • phase — этап работы поппера, на котором применяется модификатор (beforeRead, read, afterRead, beforeMain, main, afterMain, beforeWrite, write, afterWrite).
  • fn — функция, выполняющая логику модификатора (редко используется напрямую, чаще применяются встроенные модификаторы).

Shepherd.js передаёт эти модификаторы в Popper.js через конфигурацию popperOptions каждого шага:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      modifiers: [
        { name: 'offset', options: { offset: [0, 10] } },
        { name: 'flip', options: { fallbackPlacements: ['top', 'bottom'] } }
      ]
    }
  }
});

Важнейшие модификаторы Popper.js

1. offset

Позволяет смещать поппер относительно целевого элемента.

  • Синтаксис: offset: [skidding, distance]

    • skidding — смещение по оси X (горизонтально).
    • distance — смещение по оси Y (вертикально).

  • Часто используется для того, чтобы шаг тура не перекрывал элементы интерфейса.

Пример с использованием Shepherd.js:

tour.addStep({
  text: 'Пример смещения',
  attachTo: { element: '.button', on: 'bottom' },
  popperOptions: {
    modifiers: [
      { name: 'offset', options: { offset: [0, 20] } }
    ]
  }
});

2. preventOverflow

Гарантирует, что поппер не выйдет за пределы видимой области окна или заданного контейнера.

  • Параметры options:

    • boundary — DOM-элемент, относительно которого проверяется переполнение (viewport по умолчанию).
    • padding — минимальное расстояние от границ контейнера.

Пример:

modifiers: [
  { name: 'preventOverflow', options: { boundary: 'viewport', padding: 8 } }
]

3. flip

Позволяет автоматически менять позицию шага, если основная сторона не помещается на экране.

  • Параметры options:

    • fallbackPlacements — массив альтернативных позиций.
    • padding — минимальное расстояние до границ экрана.

  • Работает в связке с preventOverflow.

Пример:

modifiers: [
  { name: 'flip', options: { fallbackPlacements: ['top', 'left', 'right'], padding: 10 } }
]

4. arrow

Используется для корректного позиционирования стрелки поппера.

  • Параметры options:

    • element — CSS-селектор или DOM-элемент стрелки.

  • Shepherd.js автоматически добавляет стрелку к шагам с arrow: true, но при кастомных стилях можно задавать элемент вручную.

Пример:

modifiers: [
  { name: 'arrow', options: { element: '.shepherd-arrow' } }
]

5. computeStyles

Контролирует, как Popper.js вычисляет CSS-свойства transform и top/left для позиционирования.

  • Параметры options:

    • gpuAcceleration — включение ускорения через GPU.
    • adaptive — адаптивное позиционирование при изменении размеров окна.

Пример:

modifiers: [
  { name: 'computeStyles', options: { gpuAcceleration: true, adaptive: false } }
]

Настройка модификаторов в Shepherd.js

Каждый шаг тура может иметь собственные модификаторы Popper.js. Настройка производится через popperOptions:

tour.addStep({
  title: 'Пример шага с модификаторами',
  text: 'Шаг с кастомными модификаторами Popper.js',
  attachTo: { element: '.menu', on: 'right' },
  popperOptions: {
    modifiers: [
      { name: 'offset', options: { offset: [0, 15] } },
      { name: 'preventOverflow', options: { boundary: '.container', padding: 5 } },
      { name: 'flip', options: { fallbackPlacements: ['left', 'top'] } }
    ]
  }
});
  • popperOptions можно задавать глобально через defaultStepOptions для всего тура, либо индивидуально для каждого шага.
  • Порядок модификаторов важен: сначала offset, затем preventOverflow, затем flip, чтобы смещения учитывались перед проверкой границ и переворотом.

Расширенные возможности

  • Кастомные модификаторы: можно создать собственную логику изменения позиции, добавив объект с name, enabled, phase и fn.
  • Комбинирование модификаторов: например, offset + flip + arrow позволяют точно настроить шаги даже в сложных макетах.
  • Адаптивность: модификаторы preventOverflow и flip делают шаги автоматически подстраиваемыми под размеры экрана и динамически изменяющиеся элементы интерфейса.

Модификаторы Popper.js в Shepherd.js дают полный контроль над поведением шагов тура: смещение, предотвращение выхода за границы, динамическое изменение позиции и точное позиционирование стрелок. Грамотная настройка этих инструментов позволяет создавать максимально удобные и визуально аккуратные интерактивные гиды.

Оглавление