addStep

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

Создание шага

Синтаксис базового использования:

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

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

id – уникальный идентификатор шага, используется для управления шагами через методы тура (next, back, show и т.д.).
text – текст, который будет отображаться на шаге.
attachTo – объект, указывающий на DOM-элемент и позицию, относительно которого будет располагаться всплывающее окно.
buttons – массив кнопок с действиями, позволяющими навигацию по туру.

Настройка позиции шага

attachTo предоставляет гибкость в позиционировании:

attachTo: {
  element: '#menu-button',
  on: 'right'
}

element – селектор или DOM-элемент, к которому будет прикреплен шаг.
on – сторона элемента, на которой появится окно (top, bottom, left, right).

Можно также использовать align для уточнения выравнивания, например: { on: 'bottom', align: 'start' }.

Управление кнопками

Каждая кнопка шага задается объектом с параметрами:

buttons: [
  {
    text: 'Назад',
    action: tour.back
  },
  {
    text: 'Далее',
    action: tour.next
  },
  {
    text: 'Закрыть',
    action: tour.cancel,
    classes: 'shepherd-button-secondary'
  }
]

text – текст кнопки.
action – функция, вызываемая при клике. Может быть встроенной (tour.next, tour.back, tour.cancel) или кастомной функцией.
classes – дополнительные CSS-классы для стилизации кнопки.

Настройка внешнего вида и поведения

addStep позволяет передавать опции, определяющие визуальный стиль и функциональные особенности:

tour.addStep({
  id: 'feature-highlight',
  text: 'Подсветка важной функции.',
  classes: 'shepherd-theme-arrows shepherd-theme-custom',
  scrollTo: { beh * avior: 'smooth', block: 'center' },
  modalOverlayOpeningPadding: 10,
  cancelIcon: {
    enabled: true
  }
});

classes – CSS-классы для кастомного оформления.
scrollTo – управление прокруткой к элементу; можно использовать объект с behavior и block.
modalOverlayOpeningPadding – отступ для модального фона.
cancelIcon – отображение иконки закрытия шага.

Использование хуков и событий

Шаги, созданные через addStep, могут реагировать на события:

tour.addStep({
  id: 'example-step',
  text: 'События перед и после показа шага.',
  when: {
    show: function() { console.log('Шаг показан'); },
    hide: function() { console.log('Шаг скрыт'); }
  }
});

when – объект с событиями: show, hide, complete, cancel.
Позволяет интегрировать шаг с логикой приложения, запускать анимации, менять состояние элементов на странице.

Динамическое добавление шагов

Метод addStep можно использовать в любой момент работы тура:

if (userIsAdmin) {
  tour.addStep({
    id: 'admin-step',
    text: 'Дополнительный шаг для администратора.',
    attachTo: { element: '#admin-panel', on: 'left' }
  });
}

Шаги не обязаны быть определены заранее.
Позволяет строить туры с условной логикой и адаптировать опыт пользователя.

Пример комплексного шага

tour.addStep({
  id: 'complex-step',
  title: 'Важная функция',
  text: 'Это шаг с заголовком, кнопками и кастомными событиями.',
  attachTo: { element: '#feature', on: 'bottom' },
  classes: 'shepherd-theme-arrows shepherd-custom-step',
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Закрыть', action: tour.cancel, classes: 'shepherd-button-secondary' }
  ],
  scrollTo: { beh * avior: 'smooth', block: 'center' },
  when: {
    show: () => console.log('Complex step shown'),
    hide: () => console.log('Complex step hidden')
  },
  cancelIcon: { enabled: true }
});

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