Распространенные ошибки

Одной из самых частых ошибок является некорректная инициализация экземпляра Shepherd.Tour. Для корректной работы необходимо:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});
  • Пропущенный объект defaultStepOptions приводит к неожиданному поведению шагов: шаги могут не отображать стрелки или игнорировать прокрутку.
  • Передача некорректных параметров (например, строк вместо объекта) вызывает ошибки во время выполнения и полностью блокирует тур.

Ошибки при добавлении шагов

Добавление шагов через tour.addStep() часто вызывает трудности:

tour.addStep({
  id: 'example-step',
  text: 'Пример текста',
  attachTo: {
    element: '.selector',
    on: 'bottom'
  }
});

Ключевые моменты:

  • Неверный селектор элемента (element: '.nonexistent') делает шаг невидимым и не вызывает ошибок, что приводит к путанице.
  • Некорректное значение on (например, 'top-left' вместо 'top') ломает позиционирование тултипа.
  • Отсутствие id может усложнить управление туром и динамическое переключение между шагами.

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

Shepherd.js часто используется в динамических интерфейсах. Основная ошибка — вызов tour.start() до того, как DOM полностью готов:

document.addEventListener('DOMContentLoaded', () => {
  tour.start();
});
  • Если элементы появляются позже (например, через AJAX), шаги не будут прикреплены к элементам.
  • Решение: использовать MutationObserver или события загрузки контента, чтобы запускать тур только после появления всех целевых элементов.

Ошибки в управлении навигацией

Неправильное использование методов навигации next(), back(), cancel() и complete() приводит к сбоям:

  • Вызов tour.next() на последнем шаге не приводит к завершению тура, если не предусмотрен обработчик onComplete.
  • Отмена тура с помощью tour.cancel() без сохранения состояния может вызвать потерю данных, если шаги изменяют интерфейс пользователя.
  • Совместное использование нескольких туров без очистки предыдущих экземпляров может вызвать конфликты и визуальные накладки.

Проблемы с кастомизацией шагов

Shepherd.js поддерживает обширную кастомизацию, однако ошибки возникают при:

  • Использовании нестандартных классов CSS, которые не поддерживают стандартные свойства анимации и позиционирования.
  • Применении событий show, hide, before-show и т. п. без проверки существования шага, что вызывает ошибки типа Cannot read property '... of undefined'.
  • Неправильной передаче HTML-контента в text вместо строки: text: document.createElement('div') не будет корректно обработан.

Конфликты с другими библиотеками

Shepherd.js использует Popper.js для позиционирования, и ошибки часто возникают при:

  • Одновременном использовании сторонних тултип-библиотек, которые изменяют размеры или позицию элементов.
  • Динамическом изменении DOM, не оповещая Shepherd.js, что вызывает смещение шагов.
  • Несовместимости версий Popper.js: использование версии 2.x при ожидании 1.x ломает позиционирование.

Отслеживание состояния тура

Неправильное хранение состояния шага или завершения тура вызывает логические ошибки:

  • Отсутствие проверки tour.isActive() перед вызовом навигационных методов приводит к вызовам по несуществующему туру.
  • Попытка перезапустить уже завершенный тур без очистки старого экземпляра (tour.complete() не сбрасывает шаги) приводит к отсутствию шагов при повторном запуске.

Примеры распространённых ошибок

// Ошибка: неверный селектор
tour.addStep({
  id: 'wrong-step',
  text: 'Неправильный элемент',
  attachTo: { element: '#missing', on: 'top' }
});

// Ошибка: запуск до загрузки динамического контента
tour.start();

// Ошибка: нестандартная кастомизация без проверки
tour.addStep({
  id: 'custom-step',
  text: '<div>HTML контент</div>',
  buttons: [
    {
      text: 'Далее',
      action: () => tour.next()
    }
  ]
});

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

Оглавление