Добавление массива шагов методом addSteps

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

Структура объектов шагов

Каждый элемент массива, передаваемого в addSteps, представляет собой объект с набором параметров:

  • id (string, обязательный) — уникальный идентификатор шага. Используется для управления и обращения к шагу.

  • text (string или функция, обязательный) — содержимое текста шага. Можно использовать как обычную строку, так и функцию, возвращающую HTML или текст для динамического контента.

  • attachTo (объект, необязательный) — описание привязки шага к элементу DOM. Состоит из двух полей:

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

  • buttons (массив объектов, необязательный) — набор кнопок для шага. Каждая кнопка описывается через объект с полями:

    • text — надпись на кнопке.
    • action — функция, выполняемая при нажатии.
    • classes — CSS-классы кнопки.

  • classes (string или массив строк, необязательный) — дополнительные CSS-классы для стилизации шага.

  • scrollTo (boolean или объект, необязательный) — управление прокруткой страницы при отображении шага. Значение true вызывает стандартную прокрутку к элементу, объект позволяет детально настроить поведение.

Пример структуры шага:

{
  id: 'step1',
  text: 'Это первый шаг тура',
  attachTo: { element: '#header', on: 'bottom' },
  buttons: [
    {
      text: 'Далее',
      action: tour.next,
      classes: 'shepherd-button-primary'
    }
  ],
  classes: 'custom-step-class',
  scrollTo: true
}

Использование метода addSteps

Метод вызывается на экземпляре тура:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shadow-md bg-purple-dark',
    scrollTo: { beh * avior: 'smooth', block: 'center' }
  }
});

tour.addSteps([
  {
    id: 'intro',
    text: 'Добро пожаловать в наш тур!',
    attachTo: { element: '.intro', on: 'bottom' },
    buttons: [
      { text: 'Далее', action: tour.next }
    ]
  },
  {
    id: 'feature',
    text: 'Здесь можно увидеть основную функциональность.',
    attachTo: { element: '.feature', on: 'top' },
    buttons: [
      { text: 'Назад', action: tour.back },
      { text: 'Далее', action: tour.next }
    ]
  }
]);

tour.start();

Ключевые моменты при использовании addSteps:

  • Масштабируемость — удобно для туров с большим количеством шагов. Все шаги можно описать централизованно в массиве.
  • Консистентность — единая структура объектов облегчает поддержку и модификацию шагов.
  • Интеграция с defaultStepOptions — шаги наследуют настройки по умолчанию, но могут переопределять их локально.

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

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

const stepsData = [
  { id: 'step1', text: 'Первый динамический шаг', attachTo: { element: '#item1', on: 'top' } },
  { id: 'step2', text: 'Второй шаг', attachTo: { element: '#item2', on: 'bottom' } }
];

tour.addSteps(stepsData.map(step => ({
  ...step,
  buttons: [
    { text: 'Далее', action: tour.next },
    { text: 'Назад', action: tour.back }
  ]
})));

Такой подход позволяет строить туры на лету, подстраиваясь под контент и пользовательский интерфейс.

Особенности поведения и отладка

  1. Проверка идентификаторов — id должен быть уникальным, иначе поведение шага будет непредсказуемым.
  2. Привязка к элементам — если элемент не найден на странице, шаг не будет отображаться. Рекомендуется использовать проверки или динамическое создание элементов.
  3. Кнопки и действия — action может быть как встроенным методом (tour.next, tour.back), так и пользовательской функцией, что позволяет внедрять сложную логику.
  4. Наследование опций — addSteps автоматически применяет defaultStepOptions, что делает код лаконичным и поддерживаемым.

Продвинутые сценарии

  • Условные шаги: можно фильтровать массив шагов перед добавлением, чтобы отображать их только при определённых условиях.
  • Многоязычность: массив шагов можно хранить в формате JSON с локализованными текстами и подставлять нужные значения в text.
  • Динамическая анимация: свойства attachTo и scrollTo позволяют создавать плавные переходы между шагами, улучшая восприятие тура.

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

Оглавление