Класс Step

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

Создание объекта Step

Объект Step создается через конструктор Shepherd.Step с передачей конфигурационного объекта:

const step = new Shepherd.Step(tour, {
  id: 'intro-step',
  text: 'Добро пожаловать в наш тур!',
  attachTo: {
    element: '.header-logo',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Ключевые параметры:

  • id — уникальный идентификатор шага. Используется для ссылки на конкретный шаг.

  • text — содержимое подсказки. Может быть строкой или функцией, возвращающей строку.

  • attachTo — объект, определяющий элемент DOM и позицию подсказки относительно него:

    • element — селектор или объект HTMLElement.
    • on — позиция подсказки (top, bottom, left, right и их вариации с start/end).

  • buttons — массив объектов кнопок, каждая кнопка может выполнять действия, например, tour.next(), tour.back() или кастомные функции.

Методы класса Step

  1. show() Отображает текущий шаг. Можно вызвать вручную, если требуется контроль над последовательностью:
step.show();
  1. hide() Скрывает текущую подсказку без удаления шага из тура:
step.hide();
  1. destroy() Удаляет шаг полностью, освобождая ресурсы и DOM-элементы:
step.destroy();
  1. updateStepOptions(options) Позволяет динамически изменять конфигурацию шага:
step.updateStepOptions({
  text: 'Обновленный текст подсказки',
  buttons: [{ text: 'Закрыть', action: tour.complete }]
});
  1. complete() Помечает шаг как завершенный, вызывая все связанные с этим события:
step.complete();
  1. cancel() Отменяет шаг, вызывая события отмены:
step.cancel();

Позиционирование и attachTo

Параметр attachTo контролирует, к какому элементу привязана подсказка и где она отображается относительно элемента. Поддерживаются следующие позиции:

  • top, top-start, top-end
  • bottom, bottom-start, bottom-end
  • left, left-start, left-end
  • right, right-start, right-end

Например:

attachTo: {
  element: '#menu-button',
  on: 'right'
}

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

События шага

Step поддерживает систему событий для гибкого управления поведением:

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

Пример подписки на события:

step.on('show', () => {
  console.log('Шаг отображен');
});

step.on('complete', () => {
  console.log('Шаг завершен');
});

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

Step позволяет полностью настраивать внешний вид подсказок через CSS-классы и опции темы:

  • classes — добавляет CSS-классы к контейнеру шага.
  • scrollTo — определяет поведение прокрутки страницы до элемента (true, false или объект с опциями).
  • modalOverlayOpeningPadding — отступ для модального оверлея вокруг элемента.

Пример:

const step = new Shepherd.Step(tour, {
  id: 'custom-step',
  text: 'Пользовательский стиль шага',
  classes: 'custom-step highlight',
  scrollTo: { beh * avior: 'smooth', block: 'center' }
});

Управление кнопками и действиями

Кнопки шага создаются через массив объектов с ключами:

  • text — текст на кнопке.
  • action — функция или метод шага/тура, который будет вызван.
  • classes — CSS-классы кнопки для стилизации.

Пример кнопки для перехода к следующему шагу:

{
  text: 'Далее',
  action: tour.next,
  classes: 'shepherd-button-primary'
}

Динамические шаги

Step поддерживает динамическое создание и обновление шагов во время выполнения тура. Это полезно, когда элементы интерфейса создаются асинхронно:

tour.addStep({
  id: 'dynamic-step',
  text: () => document.querySelector('#status').textContent,
  attachTo: { element: '#status', on: 'top' }
});

Использование функций для параметров позволяет шагам автоматически адаптироваться к текущему состоянию DOM.

Итоговые рекомендации по использованию Step

  • Всегда задавать уникальный id для каждого шага.
  • Использовать attachTo для точного позиционирования подсказок.
  • Применять updateStepOptions() для динамического изменения шага.
  • Подписываться на события show, complete и cancel для контроля поведения.
  • Настраивать кнопки с логикой tour.next() и tour.back() для последовательной навигации.

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

Оглавление