Система событий Shepherd.js

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

Каждый шаг (Step) и тур (Tour) являются объектами с поддержкой событий, которые можно слушать через метод .on(event, handler) или через конфигурацию при создании шага.

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

tour.on('start', () => console.log('Тур начался'));
tour.on('complete', () => console.log('Тур завершён'));

В этом примере события start и complete привязаны к туре. В обработчиках можно выполнять любые действия: запуск анимаций, изменение DOM или логирование действий пользователя.

Основные события тура

Shepherd.js поддерживает ряд событий на уровне тура:

  • start – вызывается при запуске тура методом .start().
  • complete – срабатывает после успешного прохождения всех шагов.
  • cancel – срабатывает, если пользователь прервал тур.
  • show – срабатывает при отображении любого шага.
  • active – срабатывает при активации текущего шага (когда шаг становится видимым и интерактивным).
  • hide – срабатывает при скрытии шага.

Пример использования нескольких событий:

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

tour.on('show', (event) => {
  console.log(`Отображается шаг: ${event.step.id}`);
});

Аргумент event в обработчиках шагов содержит объект Step, что позволяет получить доступ к его свойствам, например, event.step.id или event.step.options.

События конкретного шага

Каждый шаг может иметь собственные события, независимые от тура. Основные события шага:

  • show – шаг отображён пользователю.
  • hide – шаг скрыт.
  • complete – шаг завершён (например, нажата кнопка завершения).
  • cancel – шаг отменён пользователем.
  • before-show – вызывается перед отображением шага, полезно для динамического изменения содержимого.
  • before-hide – вызывается перед скрытием шага.

Пример:

const step = tour.addStep({
  id: 'example-step',
  text: 'Это пример шага',
  attachTo: { element: '.example', on: 'bottom' }
});

step.on('show', () => console.log('Шаг отображён'));
step.on('before-show', () => console.log('Шаг собирается отображаться'));

Использование событий на уровне шагов позволяет управлять поведением интерфейса точечно, не затрагивая другие шаги.

Динамическая реакция на действия пользователя

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

const step = tour.addStep({
  id: 'action-step',
  text: 'Нажмите кнопку, чтобы продолжить',
  attachTo: { element: '.button', on: 'top' },
  buttons: []
});

step.on('show', () => {
  const button = document.querySelector('.button');
  button.addEventListener('click', () => {
    step.complete();
  });
});

Здесь шаг не содержит стандартных кнопок навигации, а завершение шага происходит через событие click.

Передача данных через события

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

tour.on('show', (event) => {
  const currentStepId = event.step.id;
  const extraData = event.step.options.extraData;
  console.log(`Шаг: ${currentStepId}, данные: ${extraData}`);
});

Добавление extraData к шагу:

tour.addStep({
  id: 'data-step',
  text: 'Шаг с дополнительными данными',
  extraData: { completedTasks: 3 }
});

Управление событиями: .once() и .off()

Shepherd.js позволяет подписываться на событие один раз с помощью .once():

tour.once('start', () => console.log('Тур стартовал только один раз'));

Удаление обработчика событий происходит через .off():

function handler() {
  console.log('Это событие больше не будет срабатывать');
}

tour.on('cancel', handler);
tour.off('cancel', handler);

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

Рекомендации по организации событий

  1. Группировка по уровню: разделять обработчики на шаги и туры, чтобы избежать конфликтов.
  2. Использование before-show для динамического контента: позволяет менять текст, кнопки или элементы DOM перед отображением шага.
  3. Очистка обработчиков: с помощью .off() предотвращается накопление ненужных слушателей при повторных турах.
  4. Логирование событий: полезно при отладке последовательностей шагов и сложных интерактивных туров.
  5. Передача контекста через event.step.options: позволяет хранить и передавать любые данные между шагами.

Пример комплексного тура с событиями

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

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в тур',
  buttons: [
    { text: 'Далее', action: tour.next }
  ]
});

tour.addStep({
  id: 'interactive',
  text: 'Нажмите кнопку для продолжения',
  attachTo: { element: '.btn-action', on: 'top' },
  buttons: []
});

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур пройден'));
tour.on('show', (e) => console.log(`Показывается шаг: ${e.step.id}`));

tour.steps.find(s => s.id === 'interactive').on('show', () => {
  document.querySelector('.btn-action').addEventListener('click', () => {
    tour.steps.find(s => s.id === 'interactive').complete();
  });
});

tour.start();

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

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

Оглавление