Метод on для подписки

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

Синтаксис метода on

tour.on(event, callback)
step.on(event, callback)

Параметры:

  • event — строка, определяющая событие, на которое производится подписка. Shepherd поддерживает множество событий, разделённых на два уровня:

    • Тур: start, complete, cancel, show, hide
    • Шаг: show, hide, complete, cancel, active, inactive, destroy

  • callback — функция, которая будет вызвана при наступлении события. Может принимать аргументы, в зависимости от события (например, текущий шаг или объект тура).

Метод возвращает объект Shepherd, что позволяет использовать цепочку вызовов (chaining).

Примеры использования на уровне тура

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

// Подписка на событие начала тура
tour.on('start', () => {
  console.log('Тур начат');
});

// Подписка на завершение тура
tour.on('complete', () => {
  console.log('Тур завершён');
});

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

tour.start();

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

Примеры использования на уровне шага

Каждый шаг Shepherd.js также поддерживает собственные события. Метод on здесь особенно полезен для кастомизации поведения отдельных элементов интерфейса.

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

// Подписка на показ шага
step.on('show', () => {
  console.log('Шаг показан');
});

// Подписка на скрытие шага
step.on('hide', () => {
  console.log('Шаг скрыт');
});

// Подписка на завершение шага
step.on('complete', () => {
  console.log('Шаг выполнен');
});

tour.start();

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

Доступные события Shepherd.js

События тура:

Событие Описание
start Тур начинается
cancel Тур отменён пользователем
complete Тур успешно завершён
show Любой шаг тура показан
hide Любой шаг тура скрыт

События шага:

Событие Описание
show Шаг показан
hide Шаг скрыт
complete Шаг выполнен
cancel Шаг отменён
active Шаг активен (фокус пользователя на шаге)
inactive Шаг неактивен
destroy Шаг удалён

Эти события можно комбинировать для построения сложных сценариев взаимодействия.

Использование аргументов callback

Некоторые события передают параметры в callback. Например:

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

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

Цепочка вызовов с on

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

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

Это позволяет структурировать код более читаемо и избежать повторного обращения к объекту тура.

Практические рекомендации

  1. Использовать on для логирования действий пользователя. Это удобно при аналитике и тестировании интерактивных туров.
  2. Использовать события шага для динамических изменений DOM. Например, подсветка элементов только при активном шаге.
  3. Удалять подписки при необходимости. Shepherd.js предоставляет метод off(event, callback) для удаления слушателей, предотвращая утечки памяти при больших турах.
  4. Комбинировать события. Например, запуск анимации при show и её остановка при hide.

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

Оглавление