API для расширений

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

Расширения реализуются через объект конфигурации, передаваемый при создании тура:

const tour = new Shepherd.Tour({
  defaults: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  },
  useModalOverlay: true,
  extensions: [MyCustomExtension]
});

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

Методы расширений

1. initialize(tour) Вызывается при инициализации тура. Позволяет добавить дополнительные свойства к объекту тура или зарегистрировать глобальные обработчики событий:

const MyCustomExtension = {
  initialize(tour) {
    tour.myCustomData = {};
    tour.on('show', () => console.log('Шаг показан'));
  }
};

2. beforeStep(step) Срабатывает перед отображением шага. Здесь можно изменять содержимое шага, добавлять динамические подсказки или контролировать порядок шагов:

beforeStep(step) {
  if (step.id === 'intro') {
    step.updateStepOptions({
      title: 'Приветствие',
      text: 'Добро пожаловать в интерактивный тур!'
    });
  }
}

3. afterStep(step) Вызывается после отображения шага. Позволяет запускать анимации, трекать метрики или изменять видимость элементов:

afterStep(step) {
  console.log(`Шаг ${step.id} завершён`);
  if (step.id === 'form-step') {
    document.querySelector('#submit-button').classList.add('highlight');
  }
}

4. destroy() Метод вызывается при завершении тура или его отмене. Здесь удобно удалять обработчики событий и очищать ресурсы, связанные с расширением:

destroy() {
  document.removeEventListener('click', this.clickHandler);
}

События тура и их использование в расширениях

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

  • start – запуск тура
  • complete – завершение тура
  • cancel – отмена тура
  • show – показ текущего шага
  • hide – скрытие текущего шага
  • active – шаг становится активным

Пример добавления обработчиков событий через расширение:

const AnalyticsExtension = {
  initialize(tour) {
    tour.on('show', step => {
      analytics.track('tourStepShown', { stepId: step.id });
    });
    tour.on('complete', () => analytics.track('tourCompleted'));
  }
};

Динамическое изменение шагов

Расширения позволяют динамически модифицировать шаги на основе состояния приложения или действий пользователя. Методы updateStepOptions и setContent дают возможность подменять текст, кнопки или классы:

const DynamicContentExtension = {
  beforeStep(step) {
    if (step.id === 'feature-step') {
      const featureEnabled = checkFeatureFlag();
      step.updateStepOptions({
        text: featureEnabled ? 'Функция доступна' : 'Функция отключена',
        buttons: featureEnabled 
          ? [{ text: 'Продолжить', action: step.next }] 
          : [{ text: 'Закрыть', action: step.cancel }]
      });
    }
  }
};

Пример комбинирования нескольких расширений

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

const tour = new Shepherd.Tour({
  defaults: { classes: 'shepherd-theme-arrows' },
  extensions: [AnalyticsExtension, DynamicContentExtension]
});

tour.addStep({
  id: 'feature-step',
  text: 'Здесь будет шаг с динамическим содержимым',
  attachTo: { element: '#feature', on: 'bottom' }
});

tour.start();

Рекомендации по разработке расширений

  • Использовать только публичный API Shepherd.js для совместимости с будущими версиями.
  • Сохранять состояние расширения в свойствах тура или шагов, чтобы избежать глобальных переменных.
  • Всегда реализовывать метод destroy, чтобы предотвратить утечки памяти.
  • Для сложных расширений стоит разделять логику на отдельные функции для каждого события (beforeStep, afterStep, initialize), чтобы повысить читаемость кода.

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

Оглавление