Архитектура библиотеки

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

Каждый шаг создается с помощью конструктора Shepherd.Tour().addStep() и может содержать следующие ключевые параметры:

  • title – заголовок шага, отображаемый в подсказке.

  • text – основной контент, описание действия или инструкции. Может быть строкой или массивом строк.

  • attachTo – объект с указанием элемента DOM и позиции подсказки относительно него:

    attachTo: { element: '.button', on: 'bottom' }

  • buttons – массив объектов кнопок, каждая с собственным текстом, стилями и обработчиками событий (action).

  • classes – CSS-классы для кастомизации внешнего вида.

  • scrollTo – логическое значение или объект, управляющее прокруткой страницы к элементу перед показом шага.

Объект шага управляется через методы show(), hide(), cancel(), complete() и события, такие как show, hide, complete, cancel.

Архитектура и жизненный цикл тура

Тур в Shepherd.js представляет собой контейнер шагов с логикой навигации и событийной системой. Внутри Shepherd.Tour реализованы следующие ключевые аспекты:

  1. Хранение шагов – шаги добавляются в массив this.steps и упорядочиваются согласно порядку добавления.
  2. Навигация – методы next(), back() и show(step) позволяют управлять последовательностью шага.
  3. События – тур использует механизм событий, основанный на EventEmitter. Поддерживаются события на уровне тура (start, complete, cancel) и шагов (show, hide).
  4. Состояние – тур хранит текущее состояние (active, completed, cancelled), что позволяет интегрировать его с внешними приложениями и проверять прогресс пользователя.

Пример инициализации и запуска тура:

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

tour.addStep({
  title: 'Пример шага',
  text: 'Описание действия',
  attachTo: { element: '.example', on: 'right' },
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ]
});

tour.start();

Взаимодействие с DOM и позиционирование

Shepherd.js использует библиотеку Popper.js для управления позиционированием подсказок относительно элементов страницы. Это обеспечивает:

  • Динамическое смещение подсказок при изменении размеров окна или позиции элемента.
  • Автоматический выбор оптимального направления (top, bottom, left, right) при ограниченном пространстве.
  • Возможность применения кастомных модификаторов Popper для точной настройки поведения.

Ключевой объект attachTo объединяет DOM-элемент и позицию, а Popper.js отвечает за выравнивание, смещение и предотвращение выхода подсказки за пределы окна.

Модульность и расширяемость

Shepherd.js спроектирован с модульной архитектурой, что позволяет:

  • Подключать кастомные стили и темы через CSS-классы.
  • Добавлять собственные компоненты кнопок и контроллеров.
  • Подписываться на события тура и шагов для интеграции с логикой приложения (например, отслеживание завершения или отказа от тура).

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

Интеграция с другими библиотеками

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

  • React – через создание оберток вокруг Shepherd.Tour и использование эффекта useEffect для инициализации и уничтожения тура.
  • Vue – через директивы и реактивные данные для динамического добавления шагов.
  • Angular – через сервисы, управляющие экземплярами тура, с подпиской на события шага и навигации.

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

Событийная система

Shepherd.js построен на событийной модели, обеспечивающей высокий уровень контроля. Основные события:

  • На уровне тура: start, complete, cancel, activeStepChange.
  • На уровне шагов: show, hide, complete, cancel.

События позволяют отслеживать точный момент взаимодействия пользователя с элементами интерфейса, а также создавать кастомные действия, например:

tour.on('complete', () => {
  console.log('Пользователь завершил тур');
});

tour.steps[0].on('show', () => {
  console.log('Показан первый шаг');
});
Оглавление