Адаптация позиционирования

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

Основы позиционирования

Каждый шаг в Shepherd определяется объектом с настройками, включая свойство attachTo, которое указывает элемент DOM и предпочтительное направление подсказки:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Пример подсказки',
  attachTo: { element: '.my-element', on: 'bottom' }
});

Здесь ключевой параметр on определяет позицию тултипа относительно целевого элемента: 'top', 'bottom', 'left', 'right', а также их вариации ('top-start', 'top-end' и т.д.). Однако простое указание позиции не гарантирует, что подсказка не выйдет за пределы видимой области.

Автоматическое смещение (fallbacks)

Shepherd.js поддерживает автоматический выбор альтернативных позиций через свойство attachTo с опцией on в виде массива. Это особенно важно для адаптивного позиционирования при изменении размеров окна или при прокрутке страницы:

tour.addStep({
  id: 'adaptive-step',
  text: 'Подсказка с адаптацией',
  attachTo: {
    element: '.my-element',
    on: ['bottom', 'top', 'right', 'left']  // fallback позиции
  }
});

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

Использование tetherOptions для тонкой настройки

Shepherd.js строится поверх библиотеки Tether.js, что позволяет глубоко контролировать позиционирование. Свойство tetherOptions в шаге открывает возможности для детальной настройки:

  • offset – смещение подсказки относительно целевого элемента.
  • constraints – набор правил для ограничений, предотвращающих выход за пределы видимой области.
  • attachment и targetAttachment – определяют точку привязки тултипа и элемента.

Пример с кастомными ограничениями:

tour.addStep({
  id: 'custom-step',
  text: 'Шаг с кастомными ограничениями',
  attachTo: { element: '.my-element', on: 'bottom' },
  tetherOptions: {
    offset: '0 10px',
    constraints: [
      {
        to: 'window',
        attachment: 'together',
        pin: true
      }
    ]
  }
});

В этом примере подсказка будет смещена на 10 пикселей вниз и закреплена так, чтобы не выйти за пределы окна браузера.

Адаптация при изменении размера окна

Чтобы подсказки корректно реагировали на динамические изменения размеров и положения элементов, необходимо учитывать:

  • Событие resize окна – Shepherd автоматически обновляет позиции, если используется свойство scrollTo: true.
  • Пересчёт положения – метод step.position() позволяет вручную пересчитать координаты при изменении DOM или скрытии/появлении элементов.
window.addEventListener('resize', () => {
  tour.steps.forEach(step => step.position());
});

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

Динамическая смена позиции

Иногда требуется изменить позицию подсказки во время выполнения шага, например, при адаптации к узким экранам:

const step = tour.addStep({
  id: 'dynamic-step',
  text: 'Динамическая позиция',
  attachTo: { element: '.my-element', on: 'bottom' }
});

if (window.innerWidth < 600) {
  step.updateStepOptions({
    attachTo: { element: '.my-element', on: 'top' }
  });
  step.position();
}

Метод updateStepOptions позволяет менять позицию и текст на лету, а position() гарантирует правильное пересчитывание координат.

Логика при конфликтующих ограничениях

Shepherd.js использует Tether.js для вычисления оптимальной позиции, основываясь на доступном пространстве и заданных constraints. Важно:

  • Правильно задавать массив fallback-позиций.
  • Использовать ограничения через tetherOptions.constraints.
  • Применять смещения (offset) для предотвращения перекрытия целевого элемента.

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

Итоговые рекомендации

  • Всегда указывать массив fallback-позиций для надежности.
  • Использовать tetherOptions для точной настройки смещений и ограничений.
  • Пересчитывать позиции при изменении размеров окна или динамических изменений DOM.
  • Использовать updateStepOptions для адаптации позиции на лету в зависимости от условий.

Эти механизмы делают Shepherd.js гибким инструментом для интерактивных пошаговых руководств с адаптивным позиционированием, гарантируя корректное отображение подсказок на всех устройствах и экранах.

Оглавление