Плюрализация

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

Инициализация тура

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

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

Ключевые моменты:

  • defaultStepOptions позволяет задать общие параметры для всех шагов.
  • useModalOverlay затемняет фон, выделяя активный элемент.

Добавление шагов

Каждый шаг тура определяется с помощью метода addStep. Основные параметры:

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

Объяснение параметров:

  • id — уникальный идентификатор шага.
  • text — текст подсказки.
  • attachTo — объект с element (CSS-селектор) и on (позиция подсказки относительно элемента).
  • buttons — массив кнопок с текстом и функцией действия.

Настройка навигации

Shepherd.js позволяет гибко управлять переходами между шагами:

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

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

buttons: [
  {
    text: 'Подробнее',
    action: () => {
      console.log('Пользователь нажал Подробнее');
      tour.next();
    }
  }
]

Работа с событиями

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

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур завершён'));
tour.on('cancel', () => console.log('Тур отменён'));

Шаги также могут обрабатывать события show, hide и cancel:

tour.addStep({
  id: 'feature',
  text: 'Этот шаг демонстрирует функциональность.',
  attachTo: { element: '#feature', on: 'top' },
  when: {
    show: () => console.log('Шаг отображён'),
    hide: () => console.log('Шаг скрыт')
  }
});

Продвинутая кастомизация

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

tour.addStep({
  id: 'custom',
  text: `
    <h3>Заголовок</h3>
    <p>Подробное описание с HTML-разметкой</p>
  `,
  classes: 'custom-shepherd-step',
  attachTo: { element: '#custom-element', on: 'right' }
});

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

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

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

const stepsData = [
  { element: '#login', text: 'Введите логин' },
  { element: '#password', text: 'Введите пароль' }
];

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

Управление порядком и условными шагами

Shepherd.js поддерживает условное отображение шагов:

tour.addStep({
  id: 'premium-feature',
  text: 'Эта функция доступна только для премиум-пользователей.',
  attachTo: { element: '#premium', on: 'top' },
  beforeShowPromise: () => {
    return new Promise((resolve, reject) => {
      if (user.isPremium) resolve();
      else reject();
    });
  }
});

Использование beforeShowPromise позволяет пропускать шаги, если условия не выполняются.

Анимация и скролл

Для улучшения пользовательского опыта можно включить плавную прокрутку к элементу:

defaultStepOptions: {
  scrollTo: { beh * avior: 'smooth', block: 'center' }
}

Это обеспечивает корректное позиционирование подсказок на странице при динамическом контенте.

Интеграция с фреймворками

Shepherd.js легко интегрируется с React, Vue и Angular. В React используется компонентная обёртка или вызов тура в useEffect:

useEffect(() => {
  tour.start();
}, []);

В Vue можно запускать тур после рендера через mounted, а в Angular — через ngAfterViewInit.

Сохранение прогресса

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

tour.on('complete', () => localStorage.setItem('tourCompleted', true));
if (!localStorage.getItem('tourCompleted')) {
  tour.start();
}

Это позволяет создавать адаптивные туры, которые учитывают действия пользователя.

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

Оглавление