Критические изменения

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

Версия и совместимость

Начиная с версии 8.x, Shepherd.js полностью отказался от внутренней зависимости на Tether.js, заменив её собственной реализацией позиционирования подсказок через Popper.js. Это изменение критически важно, так как предыдущие проекты, использующие Tether, требуют переписывания конфигураций шагов, связанных с позиционированием.

Ключевой момент: при обновлении до новой версии необходимо проверить все шаги с настройками attachTo и position. В новой версии синтаксис стал более строгим:

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

Ранее допускались строки вида 'button bottom', теперь обязательна структура объекта.

Изменение API шагов

В новых версиях изменилась структура шагов и параметры их кастомизации:

  • text → title и description Ранее шаги содержали только свойство text, которое отображалось в тултипе. Сейчас рекомендуется использовать разделение на title и description, что улучшает доступность и семантику:
steps: [
  {
    id: 'intro',
    title: 'Добро пожаловать',
    description: 'Это первый шаг вашего интерактивного тура.',
    attachTo: { element: '#start', on: 'top' }
  }
]
  • buttons Кнопки теперь принимают action вместо classes для управления навигацией и кастомным поведением:
buttons: [
  {
    text: 'Далее',
    action: tour.next
  },
  {
    text: 'Закрыть',
    action: tour.cancel
  }
]
  • modal и фоновые оверлеи Поддержка модальных подсказок реализована через modal: true и глобальные опции тура. Это изменение критично для проектов, где используется затемнение всего экрана.

Новая система событий

Shepherd.js теперь поддерживает более точное управление событиями шагов и тура:

  • События тура: start, complete, cancel, active, inactive
  • События шагов: show, hide, before-show, before-hide

Пример:

tour.on('start', () => console.log('Тур начат'));
tour.steps[0].on('show', () => console.log('Показан первый шаг'));

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

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

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

tour.addStep({
  id: 'dynamic-step',
  title: 'Новый шаг',
  description: 'Добавлен во время работы тура',
  attachTo: { element: '#dynamic', on: 'right' },
  buttons: [{ text: 'Далее', action: tour.next }]
});

Это критически важно для SPA-приложений, где элементы DOM создаются динамически после загрузки страницы.

Настройки позиции и адаптивность

Shepherd.js теперь учитывает размеры окна и перекрытие элементов при позиционировании подсказок. Параметры:

  • scrollTo — автоматически прокручивает страницу к элементу.
  • canClickTarget — разрешает клики по элементу во время показа шага.
  • popperOptions — позволяет настраивать поведение Popper.js для точного позиционирования.

Пример адаптивного шага:

attachTo: {
  element: '#menu',
  on: 'auto',
  scrollTo: true
}

on: 'auto' позволяет библиотеке автоматически выбрать сторону, где подсказка помещается корректнее всего.

Поддержка кастомного оформления

Стилизация шагов теперь централизована через темы и CSS-классы, что упрощает поддержку крупных проектов. Классы можно задавать глобально через defaultStepOptions.classes:

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

Это изменение критично для унификации внешнего вида всех подсказок на сайте.

Важные моменты миграции

  1. Проверить все шаги с attachTo и обновить синтаксис объекта.
  2. Переписать все кнопки с использованием action вместо classes.
  3. Обновить события для шагов и тура.
  4. Проверить динамическое добавление шагов в SPA.
  5. Настроить popperOptions для корректного позиционирования на всех экранах.
  6. Перенести кастомные стили в классы темы, чтобы избежать конфликтов с новой версией.

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

Оглавление