Миграция с версии 2.x на 10.x

Shepherd.js с версии 2.x до 10.x претерпела значительные изменения в архитектуре. Основное отличие заключается в переходе от глобального объекта Shepherd.Tour и устаревших методов к модульной структуре с использованием ES6 классов. Теперь каждая экземплярная переменная тура создается через new Shepherd.Tour({...}), а шаги добавляются методом tour.addStep({...}). Это позволяет создавать несколько независимых туров на одной странице без конфликтов.

Ключевые изменения в конфигурации тура:

  • Объект defaults теперь задается при создании тура и влияет на все шаги по умолчанию.
  • Поддержка плагинов и расширений через отдельные модули, например Shepherd.Step, Shepherd.Tether, что обеспечивает большую гибкость кастомизации.
  • События тура (например, show, complete, cancel) теперь подписываются через метод tour.on(event, callback) вместо старого способа с глобальными слушателями.

Изменения в синтаксисе шагов

В версии 10.x шаги имеют унифицированный формат, отличающийся от версии 2.x:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shadow-md bg-purple-dark',
    scrollTo: true
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Это новый шаг в версии 10.x',
  attachTo: {
    element: '.my-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Вперед',
      action: tour.next
    }
  ]
});

Изменения по сравнению с версией 2.x:

  • attachTo теперь всегда объект с element и on. Ранее использовалась строка вида ".my-element bottom".
  • Кнопки теперь имеют объектный формат с text и action. Методы tour.next() и tour.back() заменили устаревшие nextStep() и backStep().
  • Стили и классы указываются через classes вместо className.

Работа с событиями

В новой версии события обрабатываются через метод on на экземпляре тура или шага:

tour.on('start', () => {
  console.log('Тур запущен');
});

tour.on('complete', () => {
  console.log('Тур завершен');
});

tour.addStep({
  id: 'step1',
  text: 'Шаг с событием',
  buttons: [{ text: 'Далее', action: tour.next }],
}).on('show', () => {
  console.log('Шаг отображен');
});

Старый способ через глобальные функции, такие как Shepherd.on(...), больше не поддерживается.

Миграция кнопок и действий

В версии 2.x кнопки шагов использовали упрощенный массив строк или объекты с устаревшими методами. В 10.x каждая кнопка — это объект с обязательными свойствами text и action:

  • action — функция, которая принимает контекст шага и вызывает методы тура (next, back, complete).
  • Поддержка кастомных функций действий, например закрытие шага с дополнительной логикой:
{
  text: 'Закрыть',
  action: () => {
    tour.cancel();
    console.log('Тур отменен');
  }
}

Изменения в позиционировании и attachTo

Ранее использовался устаревший Tether, теперь Shepherd.js полностью интегрирован с Popper.js для позиционирования.

  • attachTo всегда объект с element и on.
  • Опционально можно указывать offset через { offset: '0, 10' }.
  • Автоматическое смещение шага при выходе за пределы экрана теперь встроено, что повышает стабильность отображения.
attachTo: {
  element: '#btn',
  on: 'top',
  offset: '0,5'
}

Работа с модальными окнами и динамическим контентом

Версия 10.x поддерживает шаги, прикрепленные к элементам, которые появляются динамически после загрузки страницы:

  • tour.start() теперь корректно ожидает рендер элемента при использовании scrollTo: true.
  • Для динамических элементов можно использовать проверку через beforeShowPromise:
tour.addStep({
  id: 'dynamic-step',
  text: 'Элемент появится через 1 секунду',
  attachTo: { element: '#dynamic', on: 'bottom' },
  beforeShowPromise: () => new Promise(resolve => setTimeout(resolve, 1000))
});

Обновленный API для кастомизации

  • Тематические классы (classes) заменяют устаревший className.
  • Попапы теперь настраиваются через объект popover внутри шага:
tour.addStep({
  id: 'popover-step',
  text: 'Содержимое попапа',
  popover: {
    title: 'Заголовок',
    description: 'Дополнительный текст',
  },
  buttons: [{ text: 'OK', action: tour.next }]
});
  • Глобальные опции через defaultStepOptions задаются на уровне тура.

Советы по миграции с 2.x на 10.x

  1. Замена устаревших методов: nextStep() → next, backStep() → back, cancelTour() → cancel.
  2. Конвертация attachTo в объект с element и on.
  3. Переписывание кнопок в формат объектов с text и action.
  4. Подключение стилей: классы шагов теперь через classes, без использования встроенных тем.
  5. Использование beforeShowPromise для динамических элементов вместо сложных таймеров.
  6. События подписываются через tour.on() и step.on(), удаляется глобальная регистрация.

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

Оглавление