Режим отладки

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows'
  },
  debug: true
});

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

Логирование событий тура

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

  • start — тур запущен
  • complete — тур завершён успешно
  • cancel — тур прерван
  • show — шаг отображён
  • hide — шаг скрыт
  • active — шаг активен

Пример подключения логирования для всех шагов:

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур завершён'));
tour.on('cancel', () => console.log('Тур отменён'));

tour.on('show', (event) => console.log(`Показан шаг: ${event.step.id}`));
tour.on('hide', (event) => console.log(`Скрыт шаг: ${event.step.id}`));

Такой подход позволяет отслеживать динамику работы тура и выявлять ошибки привязки к элементам DOM.

Проверка привязки к элементам

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

tour.addStep({
  id: 'step1',
  text: 'Пример шага',
  attachTo: {
    element: () => document.querySelector('#dynamic-element'),
    on: 'bottom'
  }
});

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

Инспекция состояния шагов

Методы тура предоставляют доступ к текущему состоянию:

  • tour.getCurrentStep() — возвращает объект активного шага
  • tour.steps — массив всех шагов с их состояниями
  • step.isOpen() — проверка, отображается ли шаг

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

console.log('Текущий шаг:', tour.getCurrentStep()?.id);
tour.steps.forEach(step => {
  console.log(`Шаг ${step.id} открыт: ${step.isOpen()}`);
});

Это помогает понять, какие шаги активны, какие пропущены, и корректно ли завершён тур.

Использование highlightClass и визуальной отладки

Shepherd.js поддерживает визуальное выделение целевых элементов через опцию highlightClass. При отладке это удобно для визуального контроля привязки шагов:

tour.addStep({
  id: 'highlight-step',
  text: 'Шаг с подсветкой',
  attachTo: { element: '#button', on: 'right' },
  highlightClass: 'shepherd-highlight-example'
});

В режиме отладки можно добавить CSS для shepherd-highlight-example с яркими рамками или фоном, чтобы сразу видеть, к какому элементу привязан шаг.

Временные задержки и отладка динамики

При работе с динамическими интерфейсами полезно использовать задержки перед отображением шага. В Shepherd.js это реализуется через метод beforeShowPromise:

tour.addStep({
  id: 'delayed-step',
  text: 'Шаг с задержкой',
  beforeShowPromise: () => {
    return new Promise(resolve => setTimeout(resolve, 500));
  }
});

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

Логирование пользовательских действий

Для глубокого анализа взаимодействия с туром можно подключать пользовательские обработчики к кнопкам шага:

tour.addStep({
  id: 'action-step',
  text: 'Шаг с кнопкой действия',
  buttons: [
    {
      text: 'Далее',
      action: () => {
        console.log('Кнопка "Далее" нажата на шаге action-step');
        return tour.next();
      }
    }
  ]
});

Такой подход позволяет фиксировать клики и переходы между шагами для более детальной диагностики.

Совмещение режима отладки с мобильными и адаптивными интерфейсами

В мобильной версии интерфейса важно проверять позиционирование шагов и взаимодействие с сенсорными событиями. Режим отладки помогает выявить:

  • некорректное отображение тултипов
  • перекрытие элементов
  • проблемы с прокруткой страницы

Дополнительно можно включать логирование размеров элементов и их координат перед отображением шага:

tour.on('show', (event) => {
  const rect = event.step.el.getBoundingClientRect();
  console.log(`Размеры и позиция шага ${event.step.id}:`, rect);
});

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

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

Оглавление