Типы событий

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

События тура (Tour Events)

Тур (Shepherd.Tour) генерирует события, которые сигнализируют о его жизненном цикле и взаимодействиях с пользователем. Основные события тура:

  • start – срабатывает при запуске тура методом tour.start(). Позволяет инициализировать необходимые элементы интерфейса перед появлением первого шага.

  • complete – происходит, когда тур успешно завершен (обычно после последнего шага). Часто используется для аналитики или автоматической активации дополнительных функций.

  • cancel – вызывается при отмене тура пользователем через кнопку закрытия или программно через tour.cancel(). Полезно для сохранения состояния или сброса интерфейса.

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

  • hide – вызывается при скрытии шага, включая переход на следующий шаг, закрытие или отмену. Позволяет выполнять очистку или отключение временных эффектов.

  • active – срабатывает при активации конкретного шага. Отличается от show, так как учитывает логику активного шага без визуальных эффектов, например, при программной навигации.

События шагов (Step Events)

Каждый шаг (Shepherd.Step) является самостоятельным объектом с собственными событиями:

  • before-show – вызывается перед отображением шага. Можно использовать для проверки условий, установки динамического контента или блокировки шага.

  • show – срабатывает в момент отображения шага на странице. Позволяет запускать анимации или дополнительные скрипты, синхронизированные с появлением подсказки.

  • before-hide – срабатывает перед скрытием шага. Часто используется для валидации данных, сохранения состояния или предотвращения скрытия при определённых условиях.

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

  • complete – срабатывает при успешном завершении шага. Отличается от событий туров тем, что фиксирует прогресс на уровне конкретного шага.

  • cancel – аналогично событию тура, но привязано к отдельному шагу. Позволяет реагировать на отмену конкретной подсказки.

Пользовательские события

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

tour.on('my-custom-event', () => {
  console.log('Пользовательское событие произошло');
});

tour.steps[0].on('step-custom', () => {
  console.log('Кастомное событие конкретного шага');
});

Пользовательские события позволяют:

  • синхронизировать тур с внешними действиями (например, изменение состояния приложения),
  • запускать анимации или эффекты, которые не завязаны напрямую на жизненный цикл шага,
  • создавать условные ветвления туров, реагируя на действия пользователя или состояние страницы.

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

  • Приоритет событий: события шага исполняются независимо от событий тура, однако события тура могут перехватывать действия шагов, если настроить глобальные слушатели.
  • Передача данных: все события могут передавать объект с информацией о текущем шаге, состоянии тура или произвольные данные.
  • Удаление слушателей: методы off(event, handler) позволяют отключать обработчики, предотвращая утечки памяти при динамическом создании туров.
  • Асинхронные операции: поддержка промисов позволяет задерживать переход к следующему шагу до завершения асинхронных задач.

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

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

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в тур!',
  attachTo: { element: '.header', on: 'bottom' },
});

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

tour.start();

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

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

Оглавление