Интерфейс TourOptions

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

Инициализация тура с TourOptions

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  },
  useModalOverlay: true
});
  • defaultStepOptions — задаёт настройки для всех шагов по умолчанию.
  • useModalOverlay — включает полупрозрачную маску на остальной части страницы, выделяя активный элемент.

Ключевые свойства объекта TourOptions

  1. defaultStepOptions Определяет набор опций, применяемых ко всем шагам тура, если конкретный шаг не переопределяет их.

    • classes — CSS-классы для стилизации подсказки.
    • scrollTo — автоматическая прокрутка страницы к элементу.
    • attachTo — объект с указанием целевого элемента и позиции подсказки относительно него:
attachTo: {
  element: '#button-id',
  on: 'bottom'
}

  1. useModalOverlay Логическое значение true/false. При true весь интерфейс, кроме целевого элемента, затемняется, создавая эффект модального окна.

  2. keyboardNavigation Разрешает навигацию с клавиатуры (Esc, ArrowRight, ArrowLeft). По умолчанию true.

  3. exitOnEsc Управляет поведением тура при нажатии клавиши Esc. По умолчанию true.

  4. tourName Уникальное имя тура, полезное для сохранения прогресса или идентификации в многотуровой системе.

  5. useModal Позволяет показывать тур в модальном слое. Отличается от useModalOverlay наличием дополнительного контроля над стилями и событиями.

Методы управления туром через TourOptions

  • start() — запускает тур.
  • next() / back() — переход к следующему или предыдущему шагу.
  • cancel() — полное завершение тура.
  • complete() — завершение тура с возможностью обработки события окончания.
  • addStep(stepOptions) — добавление нового шага с опциями, переопределяющими defaultStepOptions.

Обработка событий

TourOptions позволяет регистрировать глобальные события через объект events:

const tour = new Shepherd.Tour({
  defaultStepOptions: { scrollTo: true },
  events: {
    'start': () => console.log('Тур начат'),
    'complete': () => console.log('Тур завершен'),
    'show': () => console.log('Шаг показан')
  }
});
  • start — вызывается при запуске тура.
  • complete — при завершении последнего шага.
  • show — каждый раз, когда показывается новый шаг.
  • cancel — при принудительной остановке тура.

Конфигурация кнопок через TourOptions

Кнопки задаются на уровне шагов (StepOptions), но через defaultStepOptions можно создать единый стиль для всего тура:

defaultStepOptions: {
  buttons: [
    {
      text: 'Назад',
      action: tour.back,
      classes: 'shepherd-button-secondary'
    },
    {
      text: 'Далее',
      action: tour.next,
      classes: 'shepherd-button-primary'
    }
  ]
}
  • text — отображаемый текст кнопки.
  • action — функция, вызываемая при нажатии.
  • classes — CSS-класс кнопки.

Настройка позиционирования

Shepherd.js использует библиотеку Popper.js для позиционирования подсказок. Через TourOptions можно задать глобальные правила:

defaultStepOptions: {
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: { offset: [0, 10] }
      }
    ]
  }
}
  • offset — смещение подсказки относительно целевого элемента.
  • modifiers — массив объектов, изменяющих поведение Popper.js (например, ограничение выхода за экран, смещение).

Примеры практических настроек

  1. Тур с затемнением экрана и прокруткой к элементу:
const tour = new Shepherd.Tour({
  defaultStepOptions: { scrollTo: true, classes: 'shepherd-theme-arrows' },
  useModalOverlay: true
});
  1. Тур с кастомными кнопками и обработкой событий:
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    buttons: [
      { text: 'Назад', action: tour.back },
      { text: 'Далее', action: tour.next }
    ]
  },
  events: {
    start: () => console.log('Начало тура'),
    complete: () => console.log('Тур завершен')
  }
});
  1. Тур с пользовательским смещением и ограничением по экрану:
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      modifiers: [
        { name: 'preventOverflow', options: { padding: 10 } },
        { name: 'offset', options: { offset: [0, 20] } }
      ]
    }
  }
});

Итоговые рекомендации по TourOptions

  • Использовать defaultStepOptions для единых стилей и поведения всех шагов.
  • Активировать useModalOverlay для фокусировки на элементах.
  • Управлять событиями через events, чтобы реализовать кастомные логики при старте, показе и завершении тура.
  • Для сложного позиционирования использовать popperOptions.
  • Применять глобальные кнопки через buttons в defaultStepOptions для консистентного интерфейса.

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

Оглавление