События уровня шага

Shepherd.js предоставляет гибкую систему событий на уровне шага, позволяя контролировать поведение тура и взаимодействие с пользователем. Каждый шаг (Step) в Shepherd имеет набор встроенных событий, которые могут быть использованы для выполнения кастомной логики до, во время и после отображения шага.

События жизненного цикла шага

Каждый шаг поддерживает несколько ключевых событий жизненного цикла:

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

    const step = tour.addStep({
  text: 'Это первый шаг',
  attachTo: { element: '.btn-start', on: 'bottom' }
});

step.on('show', () => {
  console.log('Шаг отображен');
});

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

    step.on('hide', () => {
  console.log('Шаг скрыт');
});

  • complete — вызывается после того, как пользователь завершил шаг через кнопку действия (например, “Next” или “Done”). Отлично подходит для записи аналитики или перехода к бизнес-логике.

    step.on('complete', () => {
  console.log('Шаг завершен пользователем');
});

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

    step.on('cancel', () => {
  console.log('Шаг отменен');
});

  • active — срабатывает при активации шага, даже если он был показан повторно после скрытия. Позволяет повторно инициировать действия, не создавая дубликатов обработчиков.

    step.on('active', () => {
  console.log('Шаг активирован');
});

Работа с пользовательскими событиями

Shepherd.js позволяет добавлять собственные события через API Step#on и Step#off. Это даёт возможность расширять поведение шага по мере необходимости.

step.on('customEvent', () => {
  console.log('Пользовательское событие выполнено');
});

// Вызов пользовательского события вручную
step.trigger('customEvent');

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

Управление событиями кнопок шага

Каждый шаг может содержать кнопки, каждая из которых поддерживает обработку событий через свойство action. Важные моменты:

  • next — автоматически переходит к следующему шагу.
  • back — возвращает на предыдущий шаг.
  • cancel — завершает весь тур.
  • custom — позволяет выполнить любую функцию перед переходом.

Пример кнопки с кастомным действием:

step.addButton({
  text: 'Подтвердить',
  action() {
    console.log('Пользователь нажал Подтвердить');
    step.complete();
  }
});

Асинхронные события и тайминги

Шаги могут управлять асинхронными процессами через события:

  • Запуск сетевого запроса при show.
  • Ожидание загрузки контента перед активацией шага.
  • Использование Promise внутри действия кнопки для блокировки перехода до завершения процесса.

Пример асинхронного действия:

step.addButton({
  text: 'Загрузить данные',
  action() {
    fetch('/api/data')
      .then(response => response.json())
      .then(data => {
        console.log('Данные получены:', data);
        step.complete();
      });
  }
});

Подключение событий к туру

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

  • Каждый шаг может иметь уникальные события.
  • События можно добавлять и удалять динамически с помощью on и off.
  • Комбинация событий шагов и событий тура позволяет создавать комплексные интерактивные сценарии.

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

  • Использовать show для инициализации визуальных и интерактивных элементов.
  • Использовать hide и cancel для очистки временных данных и отмены таймеров.
  • Для аналитики и записи действий пользователей лучше всего использовать complete.
  • Пользовательские события помогают отделять логику UI от бизнес-логики, обеспечивая модульность кода.

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

Оглавление