Жизненный цикл тура

В библиотеке Shepherd.js тур начинается с создания экземпляра объекта Shepherd.Tour. Основной метод — конструктор new Shepherd.Tour(options), где options — это объект с глобальными настройками тура. Среди ключевых параметров:

  • defaultStepOptions — объект с настройками для всех шагов по умолчанию. Позволяет задать классы, позиции подсказок, поведение кнопок и другие общие параметры.
  • useModalOverlay — логическое значение, определяющее появление затемнённого фона за подсказкой.
  • tourName — уникальное имя тура, которое удобно использовать для сохранения состояния прохождения.

Пример создания тура:

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

Добавление шагов

Шаги добавляются с помощью метода addStep. Каждый шаг — это объект с обязательными и необязательными свойствами:

  • id — уникальный идентификатор шага.
  • text — содержимое подсказки.
  • attachTo — объект с селектором и позицией подсказки относительно элемента.
  • buttons — массив кнопок для навигации между шагами.
  • when — объект событий, позволяющий привязывать обработчики к жизненному циклу шага (show, hide, complete).

Пример шага с навигационными кнопками:

tour.addStep({
  id: 'welcome',
  text: 'Добро пожаловать! Это первый шаг тура.',
  attachTo: {
    element: '.header-logo',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    },
    {
      text: 'Пропустить',
      action: tour.cancel
    }
  ]
});

Управление жизненным циклом тура

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

Инициализация

Метод tour.start() запускает тур. Если указаны шаги, он автоматически покажет первый шаг и выполнит все события, привязанные к before-show и show.

Переход между шагами

  • tour.next() — переход к следующему шагу. Если шаг последний, вызовет событие complete.
  • tour.back() — возвращение к предыдущему шагу.
  • tour.show(stepId) — отображение конкретного шага по идентификатору.

Эти методы триггерят события жизненного цикла шага:

  • show — шаг становится видимым.
  • hide — шаг скрыт.
  • complete — последний шаг завершён.

Завершение и отмена

  • tour.complete() — завершает тур, вызывает все события завершения и снимает модальные оверлеи.
  • tour.cancel() — прерывает тур в любой момент, срабатывают события отмены.

Пример подписки на события:

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

tour.on('cancel', () => {
  console.log('Тур отменён');
});

tour.on('show', (step) => {
  console.log(`Показан шаг: ${step.id}`);
});

Управление состоянием тура

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

  • tour.currentStep — текущий шаг.
  • tour.steps — массив всех шагов.
  • tour.isActive() — возвращает true, если тур активен.
  • tour.cancel() и tour.complete() очищают активное состояние.

Состояние можно хранить локально, используя localStorage:

tour.on('complete', () => {
  localStorage.setItem('tourCompleted', 'true');
});

if (!localStorage.getItem('tourCompleted')) {
  tour.start();
}

Работа с динамическими шагами

Шаги могут добавляться или изменяться во время выполнения тура. Для этого используются методы:

  • addStep() — добавление нового шага.
  • removeStep(stepId) — удаление существующего шага.
  • updateStepOptions(stepId, options) — обновление параметров шага на лету.

Пример динамического добавления шага:

tour.addStep({
  id: 'dynamicStep',
  text: 'Этот шаг был добавлен во время тура.',
  attachTo: { element: '.dynamic-element', on: 'top' },
  buttons: [{ text: 'Далее', action: tour.next }]
});

Взаимодействие с DOM

Для корректного отображения туров важно, чтобы элементы, к которым привязываются подсказки, существовали в момент вызова attachTo. В противном случае шаг не отобразится. Если элементы создаются динамически, следует использовать события загрузки контента или MutationObserver для отслеживания появления элементов перед показом шага.

Использование колбэков и событий

Shepherd.js поддерживает колбэки для каждого шага и тура в целом:

  • before-show — вызывается перед отображением шага.
  • show — шаг отображается.
  • hide — шаг скрыт.
  • complete — тур завершён.
  • cancel — тур отменён пользователем.

Пример использования колбэков для изменения контента перед показом:

tour.addStep({
  id: 'stepWithCallback',
  text: 'Изначальный текст',
  attachTo: { element: '.header', on: 'bottom' },
  when: {
    show: () => {
      const step = tour.getCurrentStep();
      step.updateStepOptions({ text: 'Текст обновлён перед показом' });
    }
  }
});

Управление анимацией и прокруткой

Shepherd.js автоматически прокручивает страницу к элементу, если scrollTo: true. Для тонкой настройки можно использовать CSS-анимации, классы шагов и события show/hide для добавления кастомных анимаций.

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

Оглавление