Структура документации

Shepherd.js можно подключить двумя способами: через пакетный менеджер или напрямую через CDN. Для npm/ yarn:

npm install shepherd.js
# или
yarn add shepherd.js

Для подключения через CDN необходимо добавить в HTML:

<link rel="stylesheet" href="https://unpkg.com/shepherd.js/dist/css/shepherd.css">
<script src="https://unpkg.com/shepherd.js/dist/js/shepherd.min.js"></script>

Важно подключать CSS перед JS, чтобы стили шагов корректно применялись.

Инициализация тура

Основным объектом является Shepherd.Tour, который управляет последовательностью шагов. Тур создается с опциями, влияющими на поведение всех шагов:

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

Ключевые моменты при инициализации:

  • scrollTo — автоматически прокручивает страницу к целевому элементу.
  • cancelIcon — добавляет крестик для закрытия шага.
  • classes — позволяет задавать тему и стили шагов.
  • useModalOverlay — делает фон затемненным, ограничивая внимание пользователя на шаге.

Создание шагов

Шаги добавляются через метод addStep, где задаются заголовок, текст и целевой элемент:

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

Опции шагов:

  • id — уникальный идентификатор шага, необходим для ссылок и управления.
  • text — основной текст шага; может быть HTML.
  • attachTo — объект с элементом и положением (on) шага относительно элемента.
  • buttons — массив кнопок с действиями: tour.next, tour.back, tour.complete, кастомные функции.

Дополнительно можно использовать:

  • classes — отдельные стили конкретного шага.
  • scrollTo — переопределяет глобальный параметр для отдельного шага.
  • when — объект событий, позволяющий выполнять функции при show, hide и других действиях.

Навигация и управление туром

Shepherd.js предоставляет методы для управления туром:

  • tour.start() — запуск тура.
  • tour.next() — переход к следующему шагу.
  • tour.back() — возврат к предыдущему шагу.
  • tour.cancel() — отмена и закрытие тура.
  • tour.complete() — завершение тура с вызовом обработчиков complete.

События тура:

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

Каждое событие можно использовать для выполнения дополнительных действий, например, записи состояния пользователя.

Настройка кнопок и действий

Кнопки в шагах могут выполнять разные действия. Помимо стандартных:

  • tour.next — перейти к следующему шагу.
  • tour.back — вернуться к предыдущему.
  • tour.cancel — закрыть тур.
  • tour.complete — завершить тур.

Можно задавать кастомные функции:

buttons: [
  {
    text: 'Скрыть',
    action: () => {
      console.log('Шаг скрыт');
      tour.hide();
    }
  }
]

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

attachTo поддерживает привязку к DOM-элементам. Параметры:

  • element — селектор или DOM-узел.
  • on — позиция: 'top', 'bottom', 'left', 'right', 'auto'.
  • offset — смещение шага от элемента.

Пример:

attachTo: {
  element: '#menu',
  on: 'right'
}

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

Темизация и кастомизация стилей

Shepherd.js позволяет задавать глобальные и локальные классы для шагов:

classes: 'shepherd-theme-dark custom-step-class'

CSS для .custom-step-class можно определить отдельно, что позволяет полностью контролировать внешний вид:

.custom-step-class {
  background-color: #2a2a2a;
  color: #ffffff;
}

Использование модальных оверлеев

Опция useModalOverlay затемняет фон и фокусирует внимание на текущем шаге. Дополнительно можно управлять оверлеем:

tour.options.useModalOverlay = true;

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

Асинхронные действия и промисы

Shepherd.js поддерживает асинхронные действия в шагах, например, загрузку данных перед показом:

tour.addStep({
  id: 'load-step',
  text: 'Загружаем данные...',
  when: {
    show: async () => {
      await fetchData();
    }
  }
});

Метод when.show может возвращать промис, что позволяет интегрировать тур с динамическим контентом.

Состояние и локальное хранение

Для запоминания, прошел ли пользователь тур, можно использовать localStorage:

if (!localStorage.getItem('tourCompleted')) {
  tour.start();
  tour.on('complete', () => localStorage.setItem('tourCompleted', 'true'));
}

Это предотвращает повторное отображение уже пройденного обучения.

Дополнительные возможности

  • Step Lifecycle: события before-show, after-show, before-hide, after-hide.
  • Многоязычность: текст шагов может динамически менять язык.
  • Интеграция с фреймворками: React, Vue, Angular — через прямую манипуляцию DOM или обертки компонентов.

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

Оглавление