Options API

Библиотека Shepherd.js предоставляет гибкий механизм настройки через объект параметров (options), используемый при создании тура и отдельных шагов. Options API определяет поведение, внешний вид и логику взаимодействия с пользователем.

Ключевые точки применения:

  • глобальные настройки тура (new Shepherd.Tour(options))
  • настройки отдельных шагов (tour.addStep(options))

Глобальные параметры тура

При инициализации тура объект options задаёт поведение по умолчанию для всех шагов.

defaultStepOptions

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

Ключевые свойства:

  • cancelIcon — управление кнопкой закрытия
  • classes — CSS-классы для стилизации
  • scrollTo — автопрокрутка к элементу

useModalOverlay

Добавляет затемнение остальной части интерфейса, фокусируя внимание на активном шаге.

useModalOverlay: true

Особенности:

  • блокирует взаимодействие с фоном
  • улучшает UX в обучающих сценариях

exitOnEsc

Определяет, можно ли закрыть тур клавишей Escape.

exitOnEsc: true

keyboardNavigation

Управление переходами с помощью клавиатуры.

keyboardNavigation: true

Поддержка:

  • стрелки влево/вправо
  • Escape

Параметры шага (Step Options)

Каждый шаг тура конфигурируется отдельно и может переопределять глобальные настройки.

tour.addStep({
  id: 'example-step',
  text: 'Описание шага',
  attachTo: { element: '.btn', on: 'bottom' }
});

id

Уникальный идентификатор шага.

id: 'step-1'

Используется для:

  • навигации (tour.show('step-1'))
  • отладки

text

Контент шага. Поддерживает:

  • строку
  • HTML
  • DOM-элемент
  • функцию
text: 'Нажмите сюда для продолжения'

или

text: () => document.createElement('div')

attachTo

Привязка шага к элементу DOM.

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

Параметры:

  • element — CSS-селектор или DOM-узел
  • on — позиция (top, bottom, left, right, auto)

Если элемент отсутствует:

  • шаг отображается по центру

buttons

Массив кнопок управления.

buttons: [
  {
    text: 'Назад',
    action: tour.back
  },
  {
    text: 'Далее',
    action: tour.next
  }
]

Свойства кнопки:

  • text — текст
  • action — функция
  • classes — CSS-классы
  • secondary — вторичный стиль

advanceOn

Автоматический переход при событии.

advanceOn: {
  selector: '.btn',
  event: 'click'
}

Полезно для:

  • интерактивных обучающих сценариев
  • отслеживания действий пользователя

beforeShowPromise

Асинхронная логика перед показом шага.

beforeShowPromise: () => {
  return new Promise(resolve => {
    setTimeout(resolve, 500);
  });
}

Применение:

  • ожидание загрузки данных
  • анимации
  • рендер UI

scrollTo

Настройка прокрутки к элементу.

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

или просто:

scrollTo: true

highlightClass

Добавляет CSS-класс к целевому элементу.

highlightClass: 'highlighted'

Используется для:

  • визуального выделения
  • кастомной стилизации

canClickTarget

Разрешает или запрещает взаимодействие с элементом.

canClickTarget: false

cancelIcon

Настройка кнопки закрытия.

cancelIcon: {
  enabled: true,
  label: 'Закрыть'
}

classes

Дополнительные CSS-классы для шага.

classes: 'custom-tooltip'

Поведение позиционирования

Shepherd использует Popper.js для позиционирования элементов. Через Options API можно передавать дополнительные настройки.

popperOptions

popperOptions: {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10]
      }
    }
  ]
}

Позволяет:

  • настраивать отступы
  • изменять стратегию позиционирования

Условия отображения

when

Позволяет реагировать на события жизненного цикла шага.

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

Доступные события:

  • show
  • hide
  • cancel
  • complete

Управление прокруткой и фокусом

scrollToHandler

Кастомная функция прокрутки:

scrollToHandler: (element) => {
  element.scrollIntoView({ beh * avior: 'smooth' });
}

Работа с динамическими элементами

Options API позволяет учитывать динамически появляющиеся элементы через комбинацию:

  • beforeShowPromise
  • attachTo
  • advanceOn

Пример:

tour.addStep({
  attachTo: { element: '.dynamic', on: 'bottom' },
  beforeShowPromise: () => waitForElement('.dynamic')
});

Переопределение глобальных настроек

Любой параметр из defaultStepOptions может быть переопределён на уровне шага:

tour.addStep({
  text: 'Особый шаг',
  scrollTo: false
});

Комбинирование параметров

Options API позволяет гибко комбинировать настройки:

tour.addStep({
  id: 'complex-step',
  text: 'Сложный шаг',
  attachTo: { element: '.item', on: 'left' },
  scrollTo: { beh * avior: 'smooth' },
  highlightClass: 'focus',
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ],
  when: {
    show: () => console.log('start'),
    hide: () => console.log('end')
  }
});

Типичные сценарии использования Options API

1. Обучающий тур интерфейса

  • useModalOverlay
  • highlightClass
  • scrollTo

2. Интерактивный onboarding

  • advanceOn
  • beforeShowPromise

3. Контекстные подсказки

  • attachTo
  • classes

4. Асинхронные интерфейсы

  • beforeShowPromise
  • кастомные обработчики событий

Взаимодействие с API тура

Options API тесно связан с методами экземпляра тура:

  • tour.next()
  • tour.back()
  • tour.show(id)
  • tour.cancel()

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

Расширение и масштабирование

При построении сложных интерфейсов Options API используется как слой конфигурации:

  • вынос общих настроек в defaultStepOptions
  • генерация шагов через функции
  • интеграция с фреймворками (React, Vue)

Пример генерации:

const createStep = (selector, text) => ({
  attachTo: { element: selector, on: 'bottom' },
  text
});

Практика структурирования options

Рекомендуемый подход:

  • минимизировать дублирование через defaultStepOptions
  • использовать функции для динамических данных
  • изолировать стили через классы
  • контролировать асинхронность через beforeShowPromise

Такой подход делает код:

  • предсказуемым
  • масштабируемым
  • легко поддерживаемым
Оглавление