Генерация шагов по данным

Shepherd.js — это библиотека для создания интерактивных туров по интерфейсу веб-приложения. Основная единица любого тура — шаг (step). Каждый шаг содержит описание, позицию на странице, триггеры для показа и действия при переходе.

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

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

Важные параметры шага:

  • id — уникальный идентификатор шага. Используется для навигации (tour.show('id')).
  • text — содержимое шага. Может быть строкой или функцией, возвращающей строку.
  • attachTo — объект с элементом DOM и позицией (top, bottom, left, right). Указывает, где шаг будет прикреплен.
  • buttons — массив объектов кнопок. Каждая кнопка описывает текст, действие (action) и стили.
  • when — объект событий. Позволяет выполнять коллбэки на события шага (show, hide, complete).

Генерация шагов на основе данных

Для динамического создания шагов часто используют массив объектов с конфигурацией. Такой подход позволяет автоматически строить тур без ручного добавления каждого шага.

const stepsData = [
  { id: 'step1', selector: '.menu', text: 'Главное меню приложения.' },
  { id: 'step2', selector: '.search', text: 'Поле поиска для быстрого доступа.' },
  { id: 'step3', selector: '.footer', text: 'Нижняя панель с дополнительными ссылками.' }
];

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

Такой подход позволяет:

  • Легко изменять контент — достаточно обновить массив данных.
  • Поддерживать большие туры — не нужно вручную создавать десятки шагов.
  • Интегрировать с API — шаги можно получать с сервера или из конфигурационных файлов.

Условная генерация шагов

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

stepsData.forEach(step => {
  const element = document.querySelector(step.selector);
  if (element) {
    tour.addStep({
      id: step.id,
      text: step.text,
      attachTo: { element: step.selector, on: 'bottom' },
      buttons: [
        { text: 'Далее', action: tour.next }
      ]
    });
  }
});

Этот метод предотвращает ошибки при создании шага для несуществующего элемента.

Использование функций для динамического контента

Шаги могут содержать динамический текст и действия, используя функции:

tour.addStep({
  id: 'user-step',
  text: () => `Привет, ${getCurrentUserName()}! Здесь твои персональные настройки.`,
  attachTo: { element: '.profile', on: 'right' },
  buttons: [
    { text: 'Следующий', action: tour.next }
  ]
});

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

Автоматическая навигация по шагам

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

tour.addStep({
  id: 'step1',
  text: 'Начало тура.',
  buttons: [
    { text: 'Далее', action: () => {
        tour.next();
        console.log('Переход к следующему шагу');
      }
    }
  ],
  when: {
    show: () => console.log('Шаг 1 показан'),
    hide: () => console.log('Шаг 1 скрыт')
  }
});

События позволяют:

  • Логировать действия пользователя.
  • Изменять шаги динамически.
  • Встраивать сложную логику с условиями и API.

Интеграция с внешними источниками данных

Шаги могут генерироваться не только из статического массива, но и из данных, полученных от сервера:

fetch('/api/tour-steps')
  .then(res => res.json())
  .then(data => {
    data.forEach(step => {
      const el = document.querySelector(step.selector);
      if (el) {
        tour.addStep({
          id: step.id,
          text: step.text,
          attachTo: { element: step.selector, on: step.position || 'bottom' },
          buttons: step.buttons || [{ text: 'Далее', action: tour.next }]
        });
      }
    });
  });

Это позволяет создавать гибкие, обновляемые туры, где шаги можно модифицировать без изменения фронтенд-кода.

Советы по генерации больших туров

  1. Использовать массив объектов — централизует конфигурацию шагов.
  2. Проверять наличие элементов — предотвращает ошибки при динамическом рендеринге интерфейса.
  3. Использовать функции для текста и действий — позволяет адаптировать тур под текущий контекст пользователя.
  4. Интегрировать события when — добавляет контроль над отображением и скрытием шагов.
  5. Делать шаги модульными — можно подключать или отключать отдельные секции тура в зависимости от условий.

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

Оглавление