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

В Shepherd.js позиционирование является ключевым аспектом управления пользовательскими турами. Каждый шаг (step) может быть привязан к определённому элементу страницы с помощью свойства attachTo. Этот объект задаёт целевой элемент и позицию относительно него:

attachTo: {
  element: '#my-button',
  on: 'bottom'
}

Здесь element указывает CSS-селектор или DOM-элемент, к которому привязывается подсказка, а on задаёт направление появления подсказки относительно элемента. Допустимые значения on:

top — над элементом
bottom — под элементом
left — слева от элемента
right — справа от элемента
top-start, top-end, bottom-start, bottom-end — выравнивание с учетом углов
left-start, left-end, right-start, right-end — аналогично для боковых сторон

Использование смещений (offset)

Для более точного позиционирования Shepherd.js поддерживает свойства offsetX и offsetY. Они позволяют сдвигать подсказку относительно выбранной позиции:

attachTo: {
  element: '#my-button',
  on: 'bottom',
  offset: { x: 10, y: 5 }
}

Здесь подсказка сдвигается на 10 пикселей вправо и на 5 пикселей вниз от стандартной позиции bottom. Это особенно полезно, когда нужно избежать перекрытия элементов интерфейса.

Автоматическое управление видимостью

Shepherd.js использует Popper.js под капотом для динамического позиционирования, что обеспечивает автоматический выбор оптимальной позиции в зависимости от доступного пространства. Свойство smartPositioning по умолчанию включено и позволяет:

перемещать подсказку, если исходная позиция выходит за границы окна;
адаптироваться к изменению размеров окна и прокрутке страницы.

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    popperOptions: {
      modifiers: [{ name: 'offset', options: { offset: [0, 8] } }]
    }
  }
});

Полное управление Popper.js через Shepherd.js

Shepherd.js позволяет напрямую передавать объект popperOptions, что открывает доступ к расширенным возможностям Popper.js:

flip — переключение позиции при недостатке места
preventOverflow — предотвращение выхода подсказки за границы контейнера
arrow — настройка стрелки подсказки

Пример расширенной конфигурации:

attachTo: {
  element: '#menu',
  on: 'right',
  popperOptions: {
    modifiers: [
      { name: 'flip', options: { fallbackPlacements: ['left', 'top'] } },
      { name: 'preventOverflow', options: { padding: 10 } }
    ]
  }
}

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

Позиционирование без привязки к элементу

Shepherd.js также поддерживает центральное позиционирование на экране, когда подсказка не привязана к конкретному элементу. Для этого можно не указывать attachTo и использовать свойство useModalOverlay для затемнения фона:

tour.addStep({
  title: 'Приветствие',
  text: 'Это центральная подсказка.',
  useModalOverlay: true
});

Позиция определяется автоматически, и подсказка центрируется по экрану. Это удобно для приветственных экранов и уведомлений.

Динамическое изменение позиции шагов

В процессе работы тура можно динамически менять позицию шагов, используя методы updateStepOptions или перезаписывая attachTo:

step.updateStepOptions({
  attachTo: { element: '#new-button', on: 'top' }
});

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

Особенности адаптивного позиционирования

Responsive design: Shepherd.js корректно работает на мобильных устройствах, автоматически смещая подсказку для видимости.
Scroll management: свойство scrollTo обеспечивает автоматическую прокрутку к целевому элементу.
Collision detection: Popper.js предотвращает наложение подсказок на границы окна или другие элементы.