Классы для шагов

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

Конструктор шага

Для создания нового шага используется метод addStep объекта Tour:

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

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага с подсказкой.',
  attachTo: {
    element: '.example-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

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

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

  • text / title – текст или заголовок, отображаемый в подсказке. Можно использовать HTML.

  • attachTo – объект с параметрами привязки к элементу на странице:

    • element – CSS-селектор или DOM-элемент.
    • on – позиция подсказки относительно элемента (top, bottom, left, right).

  • buttons – массив кнопок управления шагом. Каждая кнопка может иметь текст, CSS-классы и функцию действия (action).

  • classes – CSS-классы, применяемые к подсказке, для кастомизации внешнего вида.

  • scrollTo – настройка прокрутки страницы к элементу.

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

Класс Step предоставляет ряд методов для управления поведением шага:

  • show() – отображает текущий шаг.
  • hide() – скрывает подсказку.
  • cancel() – отменяет шаг и завершает тур.
  • destroy() – удаляет элемент подсказки и очищает ресурсы.
  • updateStepOptions(options) – позволяет динамически изменять параметры шага после его создания.

Пример динамического обновления текста:

const step = tour.getById('example-step');
step.updateStepOptions({
  text: 'Новый текст подсказки для этого шага.'
});

События шагов

Shepherd.js позволяет подписываться на события конкретного шага через объект events при его создании. Основные события:

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

Пример с обработкой события:

tour.addStep({
  id: 'event-step',
  text: 'Шаг с событием show.',
  attachTo: { element: '.target', on: 'top' },
  buttons: [{ text: 'Далее', action: tour.next }],
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт')
  }
});

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

Шаги можно полностью стилизовать через:

  • classes – добавление CSS-классов.
  • popperOptions – настройка позиционирования с помощью библиотеки Popper.js.
  • scrollTo – управление прокруткой при отображении шага.

Пример кастомного позиционирования:

tour.addStep({
  id: 'custom-step',
  text: 'Позиция с кастомным Popper.',
  attachTo: { element: '.custom', on: 'right' },
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: { offset: [0, 20] }
      }
    ]
  }
});

Использование нескольких кнопок

Каждый шаг может содержать несколько кнопок, каждая из которых выполняет отдельное действие:

  • action: tour.next – переход к следующему шагу.
  • action: tour.back – возврат к предыдущему шагу.
  • action: tour.complete – завершение всего тура.
  • action: function – кастомная функция, выполняемая при нажатии.
buttons: [
  { text: 'Пропустить', action: tour.cancel, classes: 'shepherd-button-secondary' },
  { text: 'Вперёд', action: tour.next, classes: 'shepherd-button-primary' }
]

Организация логики шага

Класс Step поддерживает сложные сценарии:

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

Пример с асинхронной проверкой:

tour.addStep({
  id: 'async-step',
  text: 'Асинхронный шаг',
  attachTo: { element: '.async', on: 'bottom' },
  beforeShowPromise: () => {
    return new Promise((resolve, reject) => {
      if (document.querySelector('.async').offsetHeight > 0) {
        resolve();
      } else {
        reject();
      }
    });
  }
});

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

Оглавление