Диагностика проблем

Shepherd.js — это библиотека для создания интерактивных руководств (tours) в веб-приложениях. Основная концепция строится на последовательности шагов (steps), каждый из которых может содержать заголовок, описание и управляющие элементы (кнопки). Каждый шаг привязывается к конкретному элементу DOM через селектор attachTo. Понимание структуры шагов и их жизненного цикла критично для диагностики проблем.

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shepherd-theme-arrows',
    scrollTo: { beh * avior: 'smooth', block: 'center' }
  }
});

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в приложение!',
  attachTo: { element: '#start-btn', on: 'bottom' },
  buttons: [
    { text: 'Далее', action: tour.next }
  ]
});

tour.start();

Проблемы с привязкой шагов к элементам DOM

Наиболее частая причина сбоев Shepherd.js — это отсутствие элемента на странице в момент создания шага. Если элемент не существует, шаг не отобразится, а иногда вызывает ошибку.

Диагностика:

Проверить правильность селектора attachTo.element.
Убедиться, что элемент доступен в DOM до запуска tour.start().
Для динамически загружаемых элементов использовать события загрузки или задержки (setTimeout или MutationObserver).

const observer = new MutationObserver(() => {
  if (document.querySelector('#start-btn')) {
    tour.start();
    observer.disconnect();
  }
});

observer.observe(document.body, { childList: true, subtree: true });

Конфликты с CSS и стилями

Shepherd.js использует CSS-классы для позиционирования и анимации подсказок. Неправильные или конфликтующие стили могут привести к тому, что подсказка будет скрыта или позиционироваться неверно.

Методы диагностики:

Проверка видимости через getBoundingClientRect().
Временное отключение кастомных стилей для элементов .shepherd-step и .shepherd-tooltip.
Использование встроенных тем Shepherd.js (shepherd-theme-arrows, shepherd-theme-default) для выявления конфликтов.

const stepElement = document.querySelector('.shepherd-step');
console.log(stepElement?.getBoundingClientRect());

Ошибки жизненного цикла шагов

Shepherd.js предоставляет события жизненного цикла: show, hide, cancel, complete. Иногда шаги не отображаются из-за неправильного управления событиями.

Проверка:

Подписка на события шага и тура для логирования.
Убедиться, что методы next() и back() вызываются корректно.

tour.on('start', () => console.log('Тур начался'));
tour.on('complete', () => console.log('Тур завершён'));

tour.addStep({
  id: 'step1',
  text: 'Первый шаг',
  buttons: [
    {
      text: 'Следующий',
      action: function() {
        console.log('Нажата кнопка Далее');
        tour.next();
      }
    }
  ]
});

Проблемы с асинхронными действиями

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

Стратегии диагностики:

Использование async/await перед добавлением шага.
Отложенный запуск tour.start() до завершения загрузки данных.
Проверка наличия элементов и данных через консоль.

async function initTour() {
  await fetchData(); // Асинхронная загрузка данных
  tour.addStep({ id: 'data-step', text: 'Данные загружены', attachTo: { element: '#data', on: 'top' } });
  tour.start();
}

Логирование и отладка

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

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

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