complete

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

  • Tour — объект, который управляет всей последовательностью шагов.
  • Step — отдельный шаг в туре, связанный с конкретным элементом DOM.
  • Options — набор параметров, определяющих поведение тура и каждого шага.
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: {
      enabled: true
    }
  }
});

Здесь defaultStepOptions задаёт параметры по умолчанию для всех шагов: автоматическая прокрутка к элементу и наличие кнопки закрытия.

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

Каждый шаг создаётся с помощью метода addStep. Основные параметры:

  • id — уникальный идентификатор шага.
  • text — текст, который отображается пользователю.
  • attachTo — объект, указывающий на элемент DOM и позицию подсказки относительно него.
  • buttons — массив объектов, описывающих кнопки управления шагом.
tour.addStep({
  id: 'step1',
  text: 'Это основной элемент меню.',
  attachTo: {
    element: '#main-menu',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

attachTo поддерживает позиции: top, bottom, left, right, а также комбинации, например, top-start.

Управление туром

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

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

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

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

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

Кастомизация шагов

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

  • Кнопки: можно задать text, action, classes, secondary.
  • Тема: через classes можно подключить кастомные CSS-классы.
  • Подсказки: с помощью popperOptions можно управлять позиционированием.
tour.addStep({
  id: 'custom-step',
  text: 'Шаг с индивидуальными стилями',
  attachTo: { element: '#custom', on: 'right' },
  classes: 'shepherd-theme-arrows custom-step-style',
  buttons: [
    {
      text: 'Назад',
      action: tour.back,
      classes: 'btn-back'
    },
    {
      text: 'Вперёд',
      action: tour.next,
      classes: 'btn-next'
    }
  ]
});

Интеграция с динамическим контентом

Если элементы создаются динамически, важно инициализировать шаг только после появления элемента. Для этого можно использовать коллбэки или MutationObserver.

const observer = new MutationObserver(() => {
  if (document.querySelector('#dynamic-element')) {
    tour.addStep({
      id: 'dynamic-step',
      text: 'Динамический элемент готов',
      attachTo: { element: '#dynamic-element', on: 'top' },
      buttons: [{ text: 'Далее', action: tour.next }]
    });
    observer.disconnect();
  }
});

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

Управление последовательностью и условиями

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

tour.addStep({
  id: 'conditional-step',
  text: 'Этот шаг показывается только если выполнено условие',
  attachTo: { element: '#conditional', on: 'left' },
  when: {
    show: () => {
      return document.querySelectorAll('.active').length > 0;
    }
  },
  buttons: [{ text: 'Далее', action: tour.next }]
});

Работа с локализацией и многоязычностью

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

const translations = {
  en: { next: 'Next', prev: 'Back', finish: 'Finish' },
  ru: { next: 'Далее', prev: 'Назад', finish: 'Завершить' }
};

const lang = 'ru';

tour.addStep({
  id: 'step-lang',
  text: 'Многоязычный шаг',
  buttons: [
    { text: translations[lang].prev, action: tour.back },
    { text: translations[lang].next, action: tour.next }
  ]
});

Поддержка кастомных событий

Shepherd.js генерирует события для каждого шага:

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

Привязка событий через on:

tour.on('show', (event) => {
  console.log(`Шаг ${event.step.id} показан`);
});
tour.on('cancel', () => console.log('Тур отменён пользователем'));

Анимации и визуальные эффекты

С помощью CSS и кастомных классов можно добавлять анимации появления подсказок:

.shepherd-theme-arrows.custom-step-style {
  transition: opacity 0.3s ease, transform 0.3s ease;
}

Использование beforeShowPromise позволяет выполнять анимации или подготовку данных перед отображением шага:

tour.addStep({
  id: 'animated-step',
  text: 'Анимация перед показом',
  attachTo: { element: '#animate', on: 'bottom' },
  beforeShowPromise: () => new Promise(resolve => setTimeout(resolve, 500))
});

Расширение функциональности

Shepherd.js допускает расширение:

  • Подключение кастомных кнопок и тултипов.
  • Использование сторонних библиотек для позиционирования через popperOptions.
  • Создание сложных туров с ветвлением шагов и асинхронной логикой.

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

Оглавление