Устаревшие API

Shepherd.js активно развивается, и с каждой версией некоторые API устаревают и заменяются более современными и безопасными методами. Работа с устаревшими API может привести к непредсказуемому поведению, проблемам совместимости и трудностям при обновлении проекта. Понимание устаревших методов важно для поддержания существующих приложений и грамотного перехода на актуальные практики.

Shepherd.Tour

Ранее для создания тура использовался глобальный объект Shepherd.Tour, например:

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

Сейчас рекомендуется использовать Shepherd.Tour через импорт ES6-модуля:

import Shepherd from 'shepherd.js';

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

Ключевое отличие:

  • Устаревший объект напрямую добавлял шаги через tour.addStep(), но новые версии требуют использования defaultStepOptions вместо defaults.
  • Объект defaults больше не поддерживается в современных версиях.

addStep() с объектом вместо Step

Раньше можно было передавать объект напрямую в addStep:

tour.addStep({
  title: 'Шаг 1',
  text: 'Описание шага',
  attachTo: '.element bottom'
});

В актуальной версии рекомендуется использовать конструктор Shepherd.Step:

import Shepherd from 'shepherd.js';

const step = new Shepherd.Step(tour, {
  title: 'Шаг 1',
  text: 'Описание шага',
  attachTo: { element: '.element', on: 'bottom' }
});

tour.addStep(step);

Причины устаревания:

  • Прямое добавление объектов снижало типизацию и усложняло расширение функционала шагов.
  • Конструктор Step позволяет наследовать и добавлять кастомные методы к шагам.

attachTo с устаревшей строковой формой

Ранее для привязки шага к элементу использовалась строка:

attachTo: '.selector bottom'

Сейчас синтаксис изменён на объект:

attachTo: {
  element: '.selector',
  on: 'bottom'
}

Проблемы устаревшей формы:

  • Непредсказуемое поведение при сложных селекторах.
  • Ограничение по анимации и позиционированию.
  • Новая форма обеспечивает большую гибкость и совместимость с кастомными попапами.

events и callbacks

Ранее для обработки событий использовались устаревшие методы вроде:

tour.onShow(function() {
  console.log('Тур показан');
});

Теперь используется современный синтаксис с добавлением слушателей через объект events:

const tour = new Shepherd.Tour({
  defaultStepOptions: { scrollTo: true },
  useModalOverlay: true
});

tour.on('show', () => {
  console.log('Тур показан');
});

Основные изменения:

  • Методы типа onShow, onComplete, onCancel больше не поддерживаются.
  • События объединены через единый метод on(eventName, callback).

Структура опций и кастомизация

Ранее параметры кастомизации шагов включали устаревшие поля:

classes: 'shepherd-theme-arrows',
scrollTo: true,
buttons: [
  { text: 'Далее', action: tour.next }
]

В актуальной версии синтаксис изменён:

defaultStepOptions: {
  classes: 'shepherd-theme-arrows',
  scrollTo: { beh * avior: 'smooth', block: 'center' },
  buttons: [
    {
      text: 'Далее',
      action() { return this.next(); }
    }
  ]
}

Важные моменты:

  • scrollTo теперь объект с возможностью настройки поведения прокрутки.
  • action кнопки должно быть функцией, чтобы корректно вызывалось внутри контекста шага.
  • Использование устаревшей формы может приводить к потере контекста this и неправильной навигации.

useModalOverlay и backdrop

В ранних версиях модальное затемнение устанавливали через modal: true или backdrop: true.

В современных версиях используется отдельный флаг useModalOverlay:

const tour = new Shepherd.Tour({
  useModalOverlay: true
});

Причины изменения:

  • Устаревшие флаги конфликтовали с кастомными стилями шагов.
  • Новый флаг обеспечивает совместимость с кастомными DOM-элементами и контролирует поведение оверлея отдельно от шагов.

Резюме по устаревшим API

Устаревший метод / опция Новая альтернатива
Shepherd.Tour({ defaults }) Shepherd.Tour({ defaultStepOptions })
tour.addStep({ ... }) tour.addStep(new Shepherd.Step(tour, { ... }))
attachTo: '.selector position' attachTo: { element: '.selector', on: 'position' }
tour.onShow(callback) tour.on('show', callback)
scrollTo: true/false scrollTo: { behavior, block }
modal: true / backdrop: true useModalOverlay: true

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

Оглавление