addSteps

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

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

tour.addSteps([
  {
    id: 'step-1',
    text: 'Первый шаг вашего тура',
    attachTo: { element: '#button1', on: 'bottom' },
    buttons: [
      {
        text: 'Далее',
        action: tour.next
      }
    ]
  },
  {
    id: 'step-2',
    text: 'Второй шаг с описанием функции',
    attachTo: { element: '#input1', on: 'right' },
    buttons: [
      {
        text: 'Назад',
        action: tour.back
      },
      {
        text: 'Далее',
        action: tour.next
      }
    ]
  }
]);

tour.start();

Структура шага

Каждый объект шага может содержать следующие ключевые свойства:

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

  • text – основной текст шага, который будет отображен в тултипе.

  • attachTo – объект, определяющий элемент DOM и позицию тултипа относительно него:

    • element – CSS-селектор или DOM-элемент, к которому привязывается шаг.
    • on – позиция тултипа: 'top', 'bottom', 'left', 'right'.

  • buttons – массив кнопок управления. Каждая кнопка может иметь:

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

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

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

  • advanceOn – событие, по которому шаг автоматически переходит к следующему, например { selector: '#nextBtn', event: 'click' }.

Гибкость addSteps

Метод addSteps позволяет задавать массив шагов сразу, что упрощает организацию тура и уменьшает количество вызовов addStep. При необходимости каждый шаг можно модифицировать после добавления через методы getById и updateStepOptions:

const step2 = tour.getById('step-2');
step2.updateStepOptions({
  text: 'Обновленный текст второго шага'
});

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

Навигация и управление шагами

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

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

Можно комбинировать эти методы с кнопками шага или событиями DOM, используя advanceOn для автоматического перехода:

{
  id: 'step-3',
  text: 'Этот шаг автоматически переходит по клику на кнопку',
  attachTo: { element: '#submit', on: 'top' },
  advanceOn: { selector: '#submit', event: 'click' }
}

Кастомизация и темы

Каждый шаг поддерживает настройку визуального оформления через classes и scrollTo. Для глобальной настройки можно использовать defaultStepOptions, которые применяются ко всем шагам тура, что сокращает дублирование кода. Например, можно задать общий стиль, включить иконку отмены, а также плавную прокрутку страницы.

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

Динамическое формирование шагов

addSteps поддерживает генерацию шагов на лету. Можно создавать массив шагов на основе данных или состояния интерфейса:

const stepsData = [
  { id: 'step-1', element: '#btn1', text: 'Нажмите здесь' },
  { id: 'step-2', element: '#input1', text: 'Заполните поле' }
];

const steps = stepsData.map(step => ({
  id: step.id,
  text: step.text,
  attachTo: { element: step.element, on: 'bottom' },
  buttons: [{ text: 'Далее', action: tour.next }]
}));

tour.addSteps(steps);

Такой подход делает addSteps универсальным инструментом для интерфейсов с изменяющейся структурой или различными режимами работы.

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

Каждый шаг поддерживает события:

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

События можно использовать для логирования действий пользователя или триггеров в приложении:

tour.on('show', function() {
  console.log('Шаг отображен');
});

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

Оглавление