Интерфейс StepOptions

Объект StepOptions в Shepherd.js используется для точной настройки каждого шага турa. Он является ключевым элементом управления поведением, внешним видом и интерактивностью шага. Каждый шаг создается через конструктор tour.addStep(options), где options — это объект StepOptions.

id

Тип: string id — уникальный идентификатор шага. Он используется для ссылок между шагами и возможности динамического управления туром (например, переход к конкретному шагу с помощью tour.show('stepId')).

title и text

Тип: string или HTMLElement title задает заголовок шага, а text — основной контент. text может быть как строкой, так и DOM-элементом, что позволяет внедрять сложные компоненты, списки, таблицы или интерактивные элементы внутри шага.

attachTo

Тип: Object { element: string | HTMLElement, on: string } Позволяет привязать шаг к конкретному элементу страницы. Параметр element указывает CSS-селектор или DOM-узел, к которому прикрепляется подсказка. Параметр on определяет позицию относительно элемента: 'top', 'bottom', 'left', 'right'. Пример:

attachTo: {
  element: '#submitButton',
  on: 'bottom'
}

buttons

Тип: Array<Object> Определяет набор кнопок на шаге. Каждая кнопка задается объектом с параметрами:

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

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

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

cancelIcon

Тип: Object Настройки иконки закрытия шага. Содержит свойства:

  • enabled — включение/отключение иконки (булево)
  • label — текст для accessibility (screen reader)
  • className — кастомные CSS-классы

Пример:

cancelIcon: {
  enabled: true,
  label: 'Закрыть',
  className: 'custom-cancel-icon'
}

scrollTo

Тип: boolean | Object Определяет поведение прокрутки при открытии шага. Если true, Shepherd автоматически прокручивает страницу, чтобы элемент был видим. Можно передать объект с параметрами behavior и block:

scrollTo: { beh * avior: 'smooth', block: 'center' }

highlightClass

Тип: string CSS-класс, применяемый к элементу, к которому привязан шаг, для подсветки во время показа шага. Позволяет визуально выделить активный элемент.

modalOverlay

Тип: boolean Если установлено в true, создается затемненный фон вокруг шага, блокирующий взаимодействие с остальной страницей. Полезно для привлечения внимания пользователя к конкретному шагу.

when

Тип: Object Позволяет подписаться на события шага, такие как:

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

Пример:

when: {
  show: () => console.log('Шаг отображен'),
  complete: () => console.log('Шаг завершен')
}

Дополнительные возможности

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

Содержимое шага можно изменять в процессе выполнения тура с помощью методов updateStepOptions или изменения свойств DOM-элементов, на которые ссылается text или title. Это позволяет строить адаптивные подсказки, реагирующие на действия пользователя.

Встроенные функции навигации

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

  • tour.next() — переход к следующему шагу
  • tour.back() — возврат к предыдущему шагу
  • tour.complete() — завершение тура
  • tour.cancel() — прерывание тура

Кнопки можно комбинировать с кастомными функциями, чтобы реализовать сложную логику переходов.

Настройка визуальной позиции

Помимо attachTo.on, Shepherd поддерживает опцию advanceOn, позволяющую автоматически переходить к следующему шагу по событию, например:

advanceOn: { selector: '#nextBtn', event: 'click' }

Это позволяет создавать туры без необходимости нажимать стандартные кнопки Shepherd, интегрируя подсказки в существующий интерфейс.

Интернационализация и доступность

Каждый элемент StepOptions поддерживает работу с aria-атрибутами и доступность через title, text и cancelIcon.label. Это обеспечивает соответствие стандартам WCAG и корректное использование с экранными читалками.

Практические рекомендации

  • Для сложных интерфейсов лучше использовать комбинацию attachTo, highlightClass и modalOverlay, чтобы пользователи точно понимали, какой элемент активен.
  • Обновление text и title во время тура позволяет создавать интерактивные подсказки без перезапуска тура.
  • Подписка на события через when дает возможность логировать действия пользователя или запускать дополнительные функции на каждом шаге.

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

Оглавление