Хуки расширения

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

Типы хуков

В Shepherd.js доступны несколько категорий хуков:

  1. beforeShow / afterShow – вызываются перед отображением и после отображения шага тура. Позволяют изменять элементы DOM, проверять условия отображения, запускать анимации или логировать события.

  2. beforeHide / afterHide – срабатывают перед скрытием и после скрытия шага. Используются для очистки состояний, скрытия всплывающих элементов или остановки процессов, инициированных на шаге.

  3. beforeComplete / afterComplete – активируются перед завершением шага или всего тура и после него. Позволяют сохранять пользовательские данные, запускать переходы к следующему шагу или уведомления.

  4. beforeCancel / afterCancel – вызываются при отмене шага или тура. Обеспечивают корректное удаление временных данных и сброс состояния интерфейса.

Регистрация хуков

Хуки могут быть определены как на уровне тура, так и на уровне отдельных шагов.

На уровне тура:

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

tour.on('before-show', function(step) {
  console.log(`Сейчас будет показан шаг: ${step.id}`);
});

tour.on('after-complete', function() {
  console.log('Тур завершён');
});

На уровне шага:

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в приложение',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ],
  beforeShowPromise: function() {
    return new Promise(resolve => {
      // асинхронная логика перед отображением шага
      setTimeout(() => {
        console.log('Шаг готов к показу');
        resolve();
      }, 500);
    });
  },
  afterShow: function() {
    console.log('Шаг отображён');
  }
});

Асинхронные хуки

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

tour.addStep({
  id: 'async-step',
  text: 'Подождите немного...',
  beforeShowPromise: async function() {
    await fetchData();
    console.log('Данные загружены, шаг можно показать');
  }
});

Управление состоянием через хуки

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

  • Сохранять текущий шаг в локальном хранилище для восстановления сессии.
  • Включать или отключать кнопки в зависимости от пользовательских действий.
  • Запускать кастомные анимации для подсветки элементов интерфейса.
tour.on('before-show', function(step) {
  const isAdmin = checkUserRole();
  if (!isAdmin && step.id === 'admin-step') {
    step.hide(); // скрываем шаг, если пользователь не администратор
  }
});

Комбинирование хуков

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

tour.addStep({
  id: 'step1',
  text: 'Пример комбинации хуков',
  beforeShow: function() { console.log('Локальный beforeShow'); }
});

tour.on('before-show', function(step) { console.log('Глобальный beforeShow'); });

Результат выполнения: локальный beforeShow шага выполняется перед глобальным хуком тура, что позволяет настраивать поведение каждого шага индивидуально и при этом сохранять общий контроль над туром.

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

  • Использовать асинхронные хуки для любых операций, связанных с загрузкой данных или проверкой состояния.
  • Минимизировать сложные вычисления в хуках afterShow и afterHide, чтобы не задерживать взаимодействие пользователя с интерфейсом.
  • Четко разделять локальные и глобальные хуки, чтобы избежать конфликтов и дублирования логики.
  • Для тестирования туров использовать консольные логи в хуках, чтобы отслеживать последовательность событий.

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

Оглавление