Добавление шагов методом addStep

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: { enabled: true }
  }
});

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

В этом примере создаётся шаг с идентификатором intro, текстом подсказки и привязкой к элементу интерфейса .start-button. Кнопка Далее автоматически вызывает следующий шаг тура.

Основные параметры addStep

  1. id Уникальный идентификатор шага. Используется для ссылок, навигации и обновления шага во время выполнения тура. Обязательный параметр.

  2. text Содержимое подсказки. Может быть простым текстом или HTML-разметкой. Поддерживаются строки, а также функции, возвращающие динамический контент.

  3. attachTo Определяет элемент, к которому будет “прикреплён” шаг, и направление позиции. Формат:

    attachTo: { element: '.selector', on: 'position' }

    Позиции включают: top, bottom, left, right, auto. Если элемент отсутствует на странице, шаг будет показан без привязки.

  4. buttons Массив объектов кнопок, каждая кнопка может иметь текст и действие. Доступные действия: tour.next, tour.back, tour.cancel и собственные функции.

  5. classes Дополнительные CSS-классы для шага, позволяющие настраивать внешний вид подсказок.

  6. scrollTo Логическое значение, определяющее, должен ли шаг автоматически прокручивать страницу к прикреплённому элементу.

  7. when Объект с событиями шага:

    when: {
  show: () => console.log('Шаг показан'),
  hide: () => console.log('Шаг скрыт')
}

Продвинутая конфигурация шагов

Динамический контент

Шаг может содержать функцию, возвращающую текст, что полезно для адаптации подсказки под состояние интерфейса:

tour.addStep({
  id: 'dynamic-step',
  text: () => `Вы выбрали ${document.querySelector('#userChoice').value}`,
  attachTo: { element: '#userChoice', on: 'right' },
  buttons: [{ text: 'Следующий', action: tour.next }]
});

Условные шаги

Можно создавать шаги, которые отображаются только при выполнении определённых условий:

if (user.isLoggedIn) {
  tour.addStep({
    id: 'logged-in-step',
    text: 'Вы вошли в систему!',
    attachTo: { element: '#profile', on: 'bottom' },
    buttons: [{ text: 'Продолжить', action: tour.next }]
  });
}

Анимации и стили

Shepherd.js поддерживает кастомные классы и темы для каждого шага. Это позволяет применять анимации через CSS или адаптировать подсказки под дизайн приложения:

tour.addStep({
  id: 'animated-step',
  text: 'Посмотрите на эту кнопку',
  attachTo: { element: '#animatedButton', on: 'top' },
  classes: 'custom-animation highlight-step',
  buttons: [{ text: 'Далее', action: tour.next }]
});

Использование addStep в сложных турах

Метод addStep можно вызывать многократно для построения длинных последовательностей. Каждый шаг может ссылаться на следующий через действия кнопок, обеспечивая полное управление логикой тура:

tour.addStep({
  id: 'step-1',
  text: 'Это первый шаг.',
  attachTo: { element: '#first', on: 'bottom' },
  buttons: [{ text: 'Далее', action: tour.next }]
});

tour.addStep({
  id: 'step-2',
  text: 'Второй шаг с объяснением.',
  attachTo: { element: '#second', on: 'top' },
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ]
});

Практические советы

  • Идентификаторы должны быть уникальными — это упрощает управление шагами через методы getById и updateStep.
  • Использовать scrollTo: true для элементов вне видимой области — шаг будет автоматически прокручен в зону видимости.
  • Оптимизировать привязку элементов — если селектор не существует, шаг может не отобразиться корректно.
  • Комбинировать статический и динамический контент — удобно для интерактивных форм или SPA, где состояние интерфейса меняется.

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

Оглавление