Настройка через popperOptions

Shepherd.js использует библиотеку Popper.js для управления позиционированием подсказок. Каждый шаг тура (Shepherd.Step) позволяет настраивать своё расположение, смещение и поведение через объект popperOptions. Этот объект предоставляет полный контроль над тем, как подсказка появляется относительно целевого элемента и как реагирует на изменения в DOM.

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

popperOptions является объектом, который передаётся в каждый шаг тура и соответствует API Popper.js:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      modifiers: [],
      strategy: 'absolute',
    }
  }
});

Ключевые поля:

  • modifiers — массив модификаторов Popper.js, определяющих смещение, адаптацию к экрану, поведение при столкновениях и т.д.
  • strategy — стратегия позиционирования: 'absolute' или 'fixed'.
  • placement — позиция подсказки относительно цели: 'top', 'bottom', 'left', 'right', 'auto' и их вариации ('-start', '-end').

Модификаторы (modifiers)

Модификаторы управляют конкретными аспектами позиционирования и поведения подсказки:

  1. offset — задаёт смещение подсказки относительно цели:
popperOptions: {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10] // [по горизонтали, по вертикали]
      }
    }
  ]
}
  • Первый параметр — горизонтальное смещение, второй — вертикальное.
  • Позволяет создавать пространство между подсказкой и целевым элементом.
  1. preventOverflow — предотвращает выход подсказки за пределы видимой области окна:
popperOptions: {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        padding: 8 // отступ от границ окна
      }
    }
  ]
}
  • Полезно для адаптивных интерфейсов, когда цель находится у края экрана.
  • padding задаёт минимальное расстояние от границ.
  1. flip — позволяет автоматически менять позицию подсказки при нехватке места:
popperOptions: {
  modifiers: [
    {
      name: 'flip',
      options: {
        fallbackPlacements: ['top', 'bottom', 'right'] // последовательность альтернативных позиций
      }
    }
  ]
}
  • Подсказка попытается разместиться на первой доступной позиции из массива fallbackPlacements.
  • Если не указано, используется стандартная логика Popper.js.
  1. arrow — добавляет стрелку к подсказке и управляет её позиционированием:
popperOptions: {
  modifiers: [
    {
      name: 'arrow',
      options: {
        element: '.shepherd-arrow', // селектор стрелки
        padding: 5 // расстояние от края подсказки
      }
    }
  ]
}
  • В Shepherd.js стрелка автоматически создаётся при использовании темы с .shepherd-arrow.
  • Позволяет корректно выравнивать стрелку на любой позиции подсказки.

Стратегии позиционирования

  • absolute — позиция подсказки рассчитывается относительно ближайшего предка с position: relative.
  • fixed — позиция фиксирована относительно окна, игнорируя прокрутку. Используется для подсказок, которые должны оставаться на экране при скролле.
popperOptions: {
  strategy: 'fixed'
}

Пример комплексной настройки шага тура

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      placement: 'bottom-start',
      strategy: 'fixed',
      modifiers: [
        {
          name: 'offset',
          options: { offset: [0, 15] }
        },
        {
          name: 'flip',
          options: { fallbackPlacements: ['top', 'right', 'left'] }
        },
        {
          name: 'preventOverflow',
          options: { padding: 10 }
        },
        {
          name: 'arrow',
          options: { element: '.shepherd-arrow', padding: 5 }
        }
      ]
    }
  }
});

tour.addStep({
  title: 'Пример шага',
  text: 'Подсказка с кастомным позиционированием и стрелкой',
  attachTo: { element: '#target', on: 'bottom' }
});

tour.start();
  • placement задаёт первоначальное расположение.
  • Модификаторы контролируют смещение, адаптацию к экрану и отображение стрелки.
  • strategy: 'fixed' позволяет подсказке оставаться на месте при прокрутке страницы.

Динамическая настройка popperOptions

popperOptions может быть настроен отдельно для каждого шага:

tour.addStep({
  title: 'Другой шаг',
  text: 'С другой позицией и смещением',
  attachTo: { element: '#another-target', on: 'right' },
  popperOptions: {
    modifiers: [
      { name: 'offset', options: { offset: [10, 20] } },
      { name: 'flip', options: { fallbackPlacements: ['left', 'top'] } }
    ]
  }
});
  • Позволяет создавать уникальные поведения для подсказок в зависимости от контекста интерфейса.
  • Можно комбинировать с различными стратегиями и модификаторами.

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

  • Всегда использовать offset для создания визуального расстояния между подсказкой и целью.
  • Для адаптивных интерфейсов включать preventOverflow и flip, чтобы подсказки не выходили за границы окна.
  • Для подсказок, фиксированных на экране при скролле, задавать strategy: 'fixed'.
  • Использовать arrow с правильным селектором, чтобы стрелка корректно выравнивалась.

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

Оглавление