next

Для начала работы с Shepherd.js необходимо подключить библиотеку в проект. Она доступна через npm, yarn или CDN.

Установка через npm:

npm install shepherd.js

Подключение в проекте:

import Shepherd from 'shepherd.js';
import 'shepherd.js/dist/css/shepherd.css';

Использование CDN:

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

Создание нового тура

Тур создается через объект Shepherd.Tour, где можно задать глобальные настройки:

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

Ключевые опции:

  • defaultStepOptions — общие параметры для всех шагов.
  • classes — стили для шагов.
  • scrollTo — автоматическая прокрутка к целевому элементу.
  • useModalOverlay — затемнение фона вокруг подсказки.

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

Каждый шаг добавляется методом addStep и описывается объектом с настройками.

tour.addStep({
  id: 'step-1',
  text: 'Это первый шаг тура.',
  attachTo: {
    element: '.button-start',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Основные свойства шага:

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

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

Shepherd.js позволяет полностью контролировать действия кнопок:

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

Можно добавлять кастомные функции:

buttons: [
  {
    text: 'Закрыть',
    action() {
      alert('Тур завершен');
      tour.cancel();
    }
  }
]

Позиционирование шагов

Позиция шага относительно элемента задается в объекте attachTo:

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

Возможные позиции:

  • top, bottom, left, right — основные стороны.
  • Суффиксы -start, -end для смещения по краям.
  • center — по центру элемента.

Кастомизация внешнего вида

Shepherd.js использует CSS-классы для изменения стиля:

  • Темы: shepherd-theme-arrows, shepherd-theme-dark.
  • Кастомные классы можно добавить через classes.
  • Подсветка элементов: highlightClass.
tour.addStep({
  id: 'step-2',
  text: 'Проверка стиля',
  attachTo: { element: '#feature', on: 'top' },
  classes: 'custom-step-style',
  highlightClass: 'highlighted-element'
});

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

Shepherd.js поддерживает множество событий, позволяющих реагировать на действия пользователя:

tour.on('start', () => console.log('Тур начат'));
tour.on('complete', () => console.log('Тур завершен'));
tour.on('show', (step) => console.log(`Показан шаг: ${step.id}`));

Основные события:

  • start — начало тура.
  • complete — успешное завершение.
  • cancel — отмена тура.
  • show — показ нового шага.
  • hide — скрытие шага.

Интерактивные элементы и формы

Shepherd.js позволяет добавлять формы и интерактивные элементы прямо в шаги:

tour.addStep({
  id: 'step-form',
  text: '',
  attachTo: { element: '#form-container', on: 'bottom' },
  buttons: [
    {
      text: 'Сохранить',
      action() {
        const name = document.querySelector('#form-container input').value;
        console.log(`Имя пользователя: ${name}`);
        tour.next();
      }
    }
  ]
});

Использование модальных оверлеев

Опция useModalOverlay затемняет фон вокруг шагов, улучшая концентрацию на подсказке:

const tour = new Shepherd.Tour({
  useModalOverlay: true
});

Можно кастомизировать оверлей через CSS:

.shepherd-modal-overlay-container {
  background-color: rgba(0, 0, 0, 0.6);
}

Сложные последовательности и условные шаги

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

tour.addStep({
  id: 'conditional-step',
  text: 'Выберите вариант',
  buttons: [
    {
      text: 'Вариант 1',
      action() {
        tour.addStep({
          id: 'extra-step',
          text: 'Дополнительная подсказка для варианта 1'
        });
        tour.next();
      }
    },
    {
      text: 'Вариант 2',
      action: tour.next
    }
  ]
});

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

Запуск тура

После добавления всех шагов тур запускается методом start():

tour.start();

Можно проверять состояние тура:

if (!tour.isActive()) {
  tour.start();
}

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

Shepherd.js легко интегрируется с React, Vue и Angular. Основная идея — создание тура в жизненном цикле компонента и управление его шагами через состояние приложения.

Пример для React:

import { useEffect } from 'react';
import Shepherd from 'shepherd.js';

function AppTour() {
  useEffect(() => {
    const tour = new Shepherd.Tour({ defaultStepOptions: { scrollTo: true } });
    tour.addStep({ id: 'step-1', text: 'Первый шаг', attachTo: { element: '#start', on: 'bottom' }, buttons: [{ text: 'Далее', action: tour.next }] });
    tour.start();
  }, []);
}
Оглавление