inactive

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

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

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: {
      enabled: true
    },
    classes: 'shadow-md bg-purple-dark'
  },
  useModalOverlay: true
});

Ключевые моменты:

  • defaultStepOptions задаёт общие параметры для всех шагов тура.
  • scrollTo: true обеспечивает прокрутку к элементу перед отображением подсказки.
  • cancelIcon добавляет крестик для закрытия тура.
  • classes позволяет применять кастомные стили к подсказкам.
  • useModalOverlay: true затемняет фон вокруг элемента, повышая фокус пользователя.

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

Каждый шаг создаётся методом addStep:

tour.addStep({
  id: 'example-step',
  text: 'Это пример подсказки для элемента.',
  attachTo: {
    element: '#example-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Разбор параметров:

  • id — уникальный идентификатор шага.
  • text — текст подсказки. Можно использовать HTML для форматирования.
  • attachTo — объект, указывающий, к какому элементу привязана подсказка и с какой стороны (top, bottom, left, right).
  • buttons — массив кнопок управления, каждая из которых имеет text и action. Действия могут быть встроенными (tour.next, tour.back) или кастомными функциями.

Варианты отображения подсказок

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

  • Привязка к элементу: подсказка следует за элементом при прокрутке страницы.
  • Модальные окна: при useModalOverlay фон затемняется, подсветка остаётся на целевом элементе.
  • Динамическое позиционирование: библиотека автоматически корректирует позицию, если элемент слишком близко к краю окна.

Пример динамического позиционирования:

tour.addStep({
  id: 'dynamic-step',
  text: 'Подсказка может автоматически менять позицию.',
  attachTo: {
    element: '#dynamic-element',
    on: 'auto'
  }
});

Настройка кнопок и событий

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

tour.addStep({
  id: 'custom-buttons',
  text: 'Кнопка выполняет кастомное действие',
  buttons: [
    {
      text: 'Закрыть',
      action: () => {
        console.log('Тур закрыт');
        tour.cancel();
      }
    }
  ]
});

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

tour.on('start', () => console.log('Тур начался'));
tour.on('complete', () => console.log('Тур завершён'));
tour.on('cancel', () => console.log('Тур отменён'));

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

Модульная организация шагов

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

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

Пример условного добавления шагов:

if (user.isAdmin) {
  tour.addStep({
    id: 'admin-step',
    text: 'Это шаг для администратора',
    attachTo: { element: '#admin-panel', on: 'right' }
  });
}

Кастомизация стилей и анимаций

Shepherd.js использует CSS-классы для управления внешним видом:

  • classes — применяются к контейнеру подсказки.
  • tetherOptions — позволяет тонко настраивать позиционирование через Tether.js.
  • Поддержка кастомных анимаций через CSS-переходы.

Пример с кастомной анимацией:

tour.addStep({
  id: 'animated-step',
  text: 'Подсказка с анимацией появления',
  attachTo: { element: '#animated-element', on: 'top' },
  classes: 'fade-in-slide'
});

Управление жизненным циклом тура

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

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

Поддержка сложных сценариев

Shepherd.js можно использовать для:

  • Многостраничных туров: шаги могут проверять наличие элементов и пропускаться при их отсутствии.
  • Интерактивных действий: шаг может ожидать определенного действия пользователя перед продолжением, используя when или колбэки в кнопках.
  • Локализации текста: текст шагов можно хранить в отдельном объекте для поддержки нескольких языков.

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

tour.addStep({
  id: 'wait-action',
  text: 'Нажмите кнопку, чтобы продолжить',
  attachTo: { element: '#action-btn', on: 'bottom' },
  buttons: [
    {
      text: 'Жду',
      action: () => {} // пустая функция, шаг завершится вручную
    }
  ]
});

document.querySelector('#action-btn').addEventListener('click', () => tour.next());

Интеграция с фреймворками

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

  • React: оборачивается в компонент, шаги управляются через состояние.
  • Vue: шаги создаются в mounted или реактивно через ref.
  • Angular: инициализация в ngAfterViewInit с привязкой к элементам через @ViewChild.

Особенности интеграции:

  • Управление шагами через жизненный цикл компонента.
  • Поддержка динамических элементов интерфейса.
  • Возможность совместного использования событий Shepherd с внутренними событиями приложения.

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

Оглавление