Интерактивные туториалы

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

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

Создание тура начинается с нового экземпляра:

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

Добавление шагов

Каждый шаг создаётся методом addStep и настраивается объектом с ключевыми свойствами:

tour.addStep({
  id: 'example-step',
  text: 'Это пример подсказки для кнопки',
  attachTo: {
    element: '#myButton',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    },
    {
      text: 'Закрыть',
      action: tour.cancel
    }
  ]
});
  • id — уникальный идентификатор шага.
  • text — текст подсказки.
  • attachTo — объект, определяющий элемент и позицию подсказки относительно него (top, bottom, left, right).
  • buttons — массив объектов кнопок с действиями (tour.next, tour.back, tour.cancel).

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

Shepherd.js поддерживает полный контроль над последовательностью шагов:

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

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

Библиотека предоставляет несколько способов кастомизации:

  • Темы: shepherd-theme-arrows, shepherd-theme-default, shepherd-theme-dark.
  • Кастомные классы: через classes можно добавить свои CSS-стили.
  • Ширина и позиция: width, padding, arrow позволяют настроить размеры и направление стрелки подсказки.
tour.addStep({
  id: 'custom-style',
  text: 'Шаг с кастомными стилями',
  classes: 'custom-step',
  attachTo: { element: '#element', on: 'top' },
  width: 300
});

События и обработчики

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

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

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

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

tour.addStep({
  id: 'step-with-event',
  text: 'Шаг с событием',
  buttons: [
    { text: 'Далее', action: tour.next }
  ],
  when: {
    show: () => console.log('Показан этот шаг')
  }
});

Динамические шаги и условия

Шаги могут создаваться динамически в зависимости от состояния страницы. Например, можно показывать шаг только если определённый элемент существует:

if (document.querySelector('#optionalFeature')) {
  tour.addStep({
    id: 'conditional-step',
    text: 'Эта подсказка появляется только при наличии элемента',
    attachTo: { element: '#optionalFeature', on: 'right' }
  });
}

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

Интеграция с формами и модальными окнами

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

tour.addStep({
  id: 'modal-step',
  text: 'Подсказка в модальном окне',
  attachTo: { element: '.modal-input', on: 'bottom' },
  beforeShowPromise: () => {
    return new Promise(resolve => {
      document.querySelector('.modal').style.display = 'block';
      resolve();
    });
  }
});
  • beforeShowPromise гарантирует, что шаг не будет показан, пока элемент не станет видимым.

Локализация и мультиязычность

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

const i18n = {
  ru: {
    step1: 'Нажмите на кнопку',
    step2: 'Введите данные'
  },
  en: {
    step1: 'Click the button',
    step2: 'Enter your data'
  }
};

tour.addStep({
  id: 'localized-step',
  text: i18n.ru.step1,
  attachTo: { element: '#btn', on: 'top' }
});

Анимации и плавность переходов

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

Оптимизация производительности

Для больших интерфейсов с множеством шагов рекомендуется:

  • Использовать ленивую инициализацию шагов.
  • Привязывать шаги только к элементам, которые реально существуют.
  • Минимизировать сложные колбэки внутри beforeShowPromise и when.show.

Взаимодействие с другими библиотеками

Shepherd.js легко интегрируется с фреймворками типа React, Vue или Angular через привязку к DOM-элементам. В React часто используют хуки для контроля старта и завершения тура, а в Vue — v-if для динамической генерации элементов, к которым привязываются шаги.

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

Оглавление