popperOptions

Shepherd.js использует библиотеку Popper.js для управления позиционированием тултипов и подсказок на странице. popperOptions — это ключевой параметр, позволяющий детально контролировать поведение подсказки относительно целевого элемента, границ видимости и смещений. Он передается при создании шага и представляет собой объект конфигурации Popper.js.

Основная структура popperOptions

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      modifiers: [
        {
          name: 'offset',
          options: {
            offset: [0, 10]
          }
        },
        {
          name: 'preventOverflow',
          options: {
            padding: 8
          }
        }
      ],
      strategy: 'absolute'
    }
  }
});
  • modifiers — массив модификаторов, определяющих поведение поппера.
  • strategy — стратегия позиционирования: 'absolute' или 'fixed'.
  • placement — можно дополнительно указать позицию подсказки относительно элемента: 'top', 'bottom', 'left', 'right'.

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

offset

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

modifiers: [
  {
    name: 'offset',
    options: {
      offset: [0, 15] // [по горизонтали, по вертикали]
    }
  }
]
  • Первый параметр смещает по оси X, второй — по оси Y.
  • Полезно для создания отступа между подсказкой и элементом.

preventOverflow

Предотвращает выход подсказки за пределы видимой области.

modifiers: [
  {
    name: 'preventOverflow',
    options: {
      padding: 10 // расстояние от края окна
    }
  }
]
  • padding задает минимальный отступ от границ окна.
  • Позволяет автоматически изменять позицию, если стандартное размещение приводит к обрезанию подсказки.

flip

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

modifiers: [
  {
    name: 'flip',
    options: {
      fallbackPlacements: ['top', 'bottom', 'left', 'right']
    }
  }
]
  • fallbackPlacements — массив альтернативных позиций для popper.
  • Используется совместно с preventOverflow для адаптивного поведения подсказки.

arrow

Добавляет стрелку к подсказке и позиционирует её по направлению к элементу.

modifiers: [
  {
    name: 'arrow',
    options: {
      element: '.shepherd-arrow'
    }
  }
]
  • element — селектор или DOM-элемент стрелки.
  • Подсказка автоматически корректирует положение стрелки при изменении позиции.

Пример комплексного шага с popperOptions

tour.addStep({
  id: 'step-1',
  text: 'Пример шага с расширенными настройками Popper.js',
  attachTo: {
    element: '#button',
    on: 'bottom'
  },
  popperOptions: {
    strategy: 'fixed',
    modifiers: [
      {
        name: 'offset',
        options: { offset: [0, 20] }
      },
      {
        name: 'flip',
        options: { fallbackPlacements: ['top', 'right', 'left'] }
      },
      {
        name: 'preventOverflow',
        options: { padding: 12 }
      },
      {
        name: 'arrow',
        options: { element: '.shepherd-arrow' }
      }
    ]
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});
  • Стратегия fixed закрепляет подсказку относительно окна, а не документа.
  • Смещение offset создаёт визуальный зазор между элементом и подсказкой.
  • flip и preventOverflow обеспечивают корректное позиционирование на любых размерах экрана.
  • arrow указывает на целевой элемент, создавая визуальную привязку.

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

  1. Всегда использовать preventOverflow при работе с динамическим контентом.

  2. Комбинировать offset и arrow, чтобы подсказка выглядела аккуратно и не перекрывала элемент.

  3. Использовать flip на маленьких экранах или при изменяемых позициях элементов.

  4. Выбирать стратегию позиционирования исходя из типа интерфейса:

    • absolute — для статичных контейнеров;
    • fixed — для модальных окон и фиксированных элементов.

  5. Проверять видимость подсказки при изменении размеров окна, особенно при сложных макетах.

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

Оглавление