Параметры обработчиков событий

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

Регистрация обработчиков событий

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

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

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

// Добавление обработчика на шаг
tour.getById('intro').on('show', () => {
  console.log('Шаг показан');
});

// Добавление обработчика на тур
tour.on('complete', () => {
  console.log('Тур завершён');
});

Основные события шага:

  • show – шаг становится видимым;
  • hide – шаг скрыт;
  • destroy – шаг удалён из DOM;
  • complete – шаг завершён (при использовании навигации);
  • cancel – шаг отменён пользователем.

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

  • start – запуск тура;
  • complete – успешное завершение тура;
  • cancel – отмена тура;
  • inactive – тур не активен;
  • active – тур активен.

Использование нескольких обработчиков

Shepherd.js позволяет навешивать несколько обработчиков на одно событие:

const step = tour.getById('intro');

step.on('show', () => console.log('Первый обработчик'));
step.on('show', () => console.log('Второй обработчик'));

Обработчики вызываются в том порядке, в котором они были добавлены.

Удаление обработчиков

Для удаления обработчиков используется метод off. Он принимает имя события и функцию-обработчик:

function onShowStep() {
  console.log('Показываем шаг');
}

step.on('show', onShowStep);

// позже можно удалить
step.off('show', onShowStep);

Если не передавать функцию, будут удалены все обработчики данного события:

step.off('show');

Передача контекста и аргументов

Обработчики получают в контексте объект шага (this), что позволяет управлять состоянием шага и туром внутри функции:

step.on('show', function() {
  console.log(`Текущий шаг: ${this.id}`);
  this.updateStepOptions({ cancelIcon: { enabled: false } });
});

Обработка событий навигации

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

  • before-show – вызывается перед показом шага, можно изменить текст, позицию или другие опции;
  • before-hide – срабатывает перед скрытием шага, полезно для анимаций и сохранения данных;
  • active – шаг становится активным (только после рендеринга);
  • inactive – шаг теряет активность.

Пример динамического изменения текста шага перед показом:

step.on('before-show', function() {
  this.updateStepOptions({
    text: `Сегодня: ${new Date().toLocaleDateString()}`
  });
});

Обработка глобальных событий документа

Shepherd.js интегрируется с DOM через attachTo. Иногда необходимо реагировать на события вне шага, например, клики на определённые элементы. Для этого можно использовать глобальные обработчики и синхронизировать их с состоянием тура:

document.querySelector('.next-btn').addEventListener('click', () => {
  tour.next();
});

tour.on('cancel', () => {
  document.querySelector('.next-btn').disabled = false;
});

Обработка ошибок и пользовательских условий

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

step.on('before-hide', function() {
  if (!document.querySelector('#agree').checked) {
    alert('Необходимо согласиться с условиями!');
    return false; // блокируем скрытие шага
  }
});

Это работает совместно с методами show и hide, контролируя поток тура.

Комбинирование событий и кастомных действий

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

step.on('show', () => {
  gsap.from('.highlight', { opacity: 0, duration: 1 });
});

tour.on('complete', () => {
  fetch('/log-tour-completion', { method: 'POST' });
});

Советы по структуре обработчиков

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

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

Оглавление