Shepherd.js в ванильном JavaScript

Shepherd.js — это библиотека для создания интерактивных пошаговых руководств на веб-страницах. Для работы с ней необходимо подключить как CSS, так и JS-файлы. В ванильном JavaScript это можно сделать несколькими способами:

Через CDN:

После подключения Shepherd.js становится доступен глобальный объект Shepherd.

Через npm и сборщик модулей:

npm install shepherd.js
import Shepherd from 'shepherd.js';
import 'shepherd.js/dist/css/shepherd.css';

После этого можно использовать классы и методы библиотеки напрямую в коде.

Создание тура и шагов

Основной объект Shepherd — это Shepherd.Tour. Он управляет всей логикой показа шагов, их навигацией и опциями.

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

Пояснение ключевых опций:

  • cancelIcon.enabled — отображает крестик для закрытия шага.
  • classes — CSS-класс для кастомизации темы.
  • scrollTo — параметры прокрутки страницы при показе шага.

Добавление шагов осуществляется через метод addStep:

tour.addStep({
  id: 'welcome',
  text: 'Добро пожаловать! Это первый шаг нашего тура.',
  attachTo: {
    element: '.header',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Разбор ключевых параметров шага:

  • id — уникальный идентификатор шага.
  • text — текстовое содержание шага.
  • attachTo — указывает элемент на странице, к которому привязан шаг, и сторону появления (top, bottom, left, right).
  • buttons — массив кнопок с текстом и действием.

Управление навигацией

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

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

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

tour.addStep({
  id: 'step2',
  text: 'Теперь мы покажем вторую секцию.',
  attachTo: { element: '#section2', on: 'top' },
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next },
    { text: 'Закрыть', action: tour.cancel }
  ]
});

Настройка внешнего вида и тем

Shepherd.js поддерживает кастомные темы через CSS. По умолчанию доступны:

  • shepherd-theme-arrows — стрелки у подсказок.
  • shepherd-theme-default — стандартный вид.

Для глубокой кастомизации можно использовать собственные классы:

tour.addStep({
  id: 'custom',
  text: 'Шаг с пользовательским стилем',
  classes: 'my-custom-step',
  attachTo: { element: '#custom-element', on: 'right' }
});

В CSS:

.my-custom-step {
  background-color: #f0f0f0;
  color: #333;
  border-radius: 10px;
  padding: 15px;
}
.my-custom-step .shepherd-arrow {
  border-color: #f0f0f0;
}

События и колбэки

Shepherd.js предоставляет множество событий для отслеживания действий пользователя:

  • show — шаг отображается.
  • hide — шаг скрывается.
  • complete — завершение тура.
  • cancel — отмена тура пользователем.

Пример использования событий:

tour.on('show', () => {
  console.log('Показывается шаг:', tour.currentStep.id);
});

tour.on('complete', () => {
  console.log('Тур завершён успешно');
});

Эти события позволяют интегрировать тур с аналитикой или динамическим изменением интерфейса.

Привязка шагов к элементам, которых может не быть

Shepherd.js поддерживает асинхронное ожидание появления элементов. Например, если элемент появляется после AJAX-запроса:

tour.addStep({
  id: 'async-step',
  text: 'Элемент загружен динамически',
  attachTo: { element: '#dynamic-element', on: 'bottom' },
  when: {
    show: () => {
      if (!document.querySelector('#dynamic-element')) {
        setTimeout(() => tour.show('async-step'), 500);
      }
    }
  }
});

Это предотвращает ошибки при отсутствии элемента в момент инициализации тура.

Программное управление шагами

Каждый шаг — объект Shepherd.Step, который можно изменять динамически:

const step = new Shepherd.Step(tour, {
  id: 'dynamic-step',
  text: 'Это динамический шаг',
  attachTo: { element: '#dynamic', on: 'left' }
});

step.updateStepOptions({
  text: 'Текст обновлён программно',
  buttons: [{ text: 'Далее', action: tour.next }]
});

tour.addStep(step);

Метод updateStepOptions позволяет менять содержимое, кнопки и позицию шага во время работы тура.

Интеграция с формами и сложными интерфейсами

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

tour.addStep({
  id: 'form-step',
  text: 'Введите ваше имя здесь',
  attachTo: { element: '#name-input', on: 'right' },
  buttons: [
    {
      text: 'Далее',
      action: () => {
        const value = document.querySelector('#name-input').value;
        if (value) tour.next();
        else alert('Поле не должно быть пустым');
      }
    }
  ]
});

Это позволяет реализовать интерактивные проверки и направлять пользователя по интерфейсу.

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

Shepherd.js поддерживает работу с промисами в колбэках кнопок:

tour.addStep({
  id: 'async-button-step',
  text: 'Нажмите для загрузки данных',
  attachTo: { element: '#load-btn', on: 'bottom' },
  buttons: [
    {
      text: 'Загрузить',
      action: () => fetch('/data.json')
        .then(res => res.json())
        .then(data => {
          console.log('Данные загружены:', data);
          tour.next();
        })
    }
  ]
});

Это удобно для интеграции с серверной логикой без прерывания тура.

Поддержка мультиязычности

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

const translations = {
  en: { welcome: 'Welcome to the tour!' },
  ru: { welcome: 'Добро пожаловать!' }
};

const lang = 'ru';

tour.addStep({
  id: 'i18n-step',
  text: translations[lang].welcome,
  buttons: [{ text: 'Далее', action: tour.next }]
});

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

Работа с несколькими турами на одной странице

Можно создать несколько экземпляров Shepherd.Tour для разных разделов:

const tour1 = new Shepherd.Tour({ defaultStepOptions: { scrollTo: true } });
const tour2 = new Shepherd.Tour({ defaultStepOptions: { scrollTo: true } });

tour1.addStep({ id: 't1-step1', text: 'Первый тур, шаг 1', buttons: [{ text: 'Далее', action: tour1.next }] });
tour2.addStep({ id: 't2-step1', text: 'Второй тур, шаг 1', buttons: [{ text: 'Далее', action: tour2.next }] });

tour1.start(); // запуск первого тура

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

Оглавление