Хуки для управления туром

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

beforeShow и beforeShowPromise

  • beforeShow — синхронная функция, вызываемая перед отображением шага. Используется для подготовки DOM, скрытия элементов, вычисления динамических координат.
  • beforeShowPromise — асинхронный вариант, возвращающий промис. Тур не будет показан, пока промис не разрешится. Полезно для загрузки данных с сервера или выполнения анимаций перед показом шага.

Пример использования:

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

tour.addStep({
  id: 'example-step',
  text: 'Подготовка данных...',
  attachTo: { element: '#target', on: 'bottom' },
  beforeShow: () => {
    console.log('Шаг готовится к отображению');
  },
  beforeShowPromise: () => {
    return new Promise(resolve => {
      setTimeout(() => {
        console.log('Данные загружены');
        resolve();
      }, 1000);
    });
  }
});

show и hide

  • show вызывается сразу после того, как шаг отображается на экране. Это место для активации анимаций, подсветки элементов или записи статистики о просмотре шага.
  • hide вызывается перед скрытием шага, например, для сохранения состояния, отключения обработчиков событий или выполнения анимаций закрытия.

Пример:

tour.addStep({
  id: 'highlight-step',
  text: 'Элемент подсвечен',
  attachTo: { element: '#highlight', on: 'right' },
  show: () => {
    document.querySelector('#highlight').classList.add('active');
  },
  hide: () => {
    document.querySelector('#highlight').classList.remove('active');
  }
});

cancel и complete

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

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

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

active

  • Хук active позволяет реагировать на изменение активности шага в реальном времени.
  • Он срабатывает каждый раз, когда шаг становится активным, что полезно для динамического изменения содержимого шага или проверки условий отображения.
tour.on('active', step => {
  console.log(`Активный шаг: ${step.id}`);
});

Использование хуков для асинхронного взаимодействия

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

tour.addStep({
  id: 'api-step',
  text: 'Загрузка информации с сервера...',
  beforeShowPromise: () => fetch('/api/data')
    .then(response => response.json())
    .then(data => {
      console.log('Данные API:', data);
    })
});

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

Совмещение хуков с событиями тура

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

Пример: показывать шаг только если пользователь ранее не посетил страницу:

tour.on('show', step => {
  if (step.id === 'conditional-step' && localStorage.getItem('visited')) {
    step.hide();
  }
});

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

  1. Минимизировать блокирующий код в beforeShow — использовать синхронные операции только для быстрых подготовительных действий.
  2. Асинхронные операции через beforeShowPromise обеспечивают плавный UX без зависаний.
  3. Синхронизация с внешними библиотеками (например, анимациями или загрузкой данных) выполняется через хуки beforeShowPromise, show и hide.
  4. Логирование и аналитика удобно интегрируется через глобальные события active, cancel и complete.

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

Оглавление