active

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

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

Пояснение ключевых настроек:

  • defaultStepOptions — задаёт базовые параметры для всех шагов тура, включая кнопку закрытия (cancelIcon) и прокрутку (scrollTo).
  • useModalOverlay — затемняет остальную часть страницы, фокусируя внимание на активном элементе.

Добавление шагов и их настройка

Каждый шаг создаётся методом addStep, принимающим объект с обязательными и опциональными параметрами:

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в наш интерфейс!',
  attachTo: {
    element: '#start-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Основные параметры шага:

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

Дополнительно шаги могут содержать:

  • advanceOn — событие, после которого шаг автоматически переключается.
  • highlightClass — CSS-класс, который добавляется к целевому элементу.

Управление туром: запуск и завершение

Методы управления туром позволяют гибко контролировать поведение:

tour.start();    // Запуск тура с первого шага
tour.next();     // Переход к следующему шагу
tour.back();     // Возврат к предыдущему шагу
tour.cancel();   // Прерывание тура
tour.complete(); // Завершение тура

Особенности поведения:

  • При вызове start() тур автоматически отображает первый шаг.
  • next() и back() учитывают логику последовательности шагов, которую можно задавать с помощью step.showNext() или step.showPrevious().

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

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

tour.addStep({
  id: 'dynamic-step',
  text: 'Этот шаг появился динамически!',
  attachTo: { element: '#dynamic-element', on: 'top' },
  buttons: [{ text: 'Закрыть', action: tour.complete }]
});

Удаление шага выполняется методом removeStep:

tour.removeStep('dynamic-step');

Это полезно для туров с условными сценариями, где шаги зависят от действий пользователя.

Активные шаги и их особенности

Понятие active step (активный шаг) — центральное для Shepherd.js. Активный шаг — это шаг, который в данный момент отображается на странице. Его можно получить и управлять им напрямую:

const currentStep = tour.getCurrentStep();
currentStep.updateStepOptions({ text: 'Обновленный текст для текущего шага' });

Методы работы с активным шагом:

  • show() — отображает шаг, делая его активным.
  • hide() — скрывает шаг без завершения тура.
  • scrollTo() — прокручивает страницу так, чтобы элемент шага был виден.
  • updateStepOptions() — позволяет изменить текст, кнопки или позицию на лету.

Привязка действий к событиям активного шага

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

tour.on('show', (event) => {
  console.log(`Активный шаг: ${event.step.id}`);
});

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

События, связанные с активным шагом:

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

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

Настройка визуального выделения активного шага

Для акцентирования внимания на активном шаге можно использовать подсветку:

tour.addStep({
  id: 'highlighted',
  text: 'Обратите внимание на этот элемент!',
  attachTo: { element: '#important', on: 'right' },
  highlightClass: 'shepherd-highlight'
});

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

Управление прокруткой для активного шага

Активный шаг может автоматически скроллиться в видимую область:

tour.addStep({
  id: 'scroll-step',
  text: 'Элемент будет автоматически виден.',
  attachTo: { element: '#offscreen', on: 'top' },
  scrollTo: true
});
  • scrollTo: true прокручивает страницу к элементу.
  • Можно задать поведение прокрутки через объект { beh * avior: 'smooth', block: 'center' } для плавного перемещения.

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

Shepherd.js эффективно работает с динамическим контентом, создаваемым через фреймворки вроде Vue, React или Angular. Для корректной работы с динамическими элементами:

  • Шаги следует добавлять после рендера элементов в DOM.
  • Использовать события show для проверки видимости элемента и вызова scrollTo().
tour.on('show', (event) => {
  const el = document.querySelector(event.step.options.attachTo.element);
  if (el) event.step.scrollTo();
});

Это обеспечивает корректное отображение активного шага даже при асинхронной загрузке компонентов.

Оглавление