text

Shepherd.js — это библиотека для создания интерактивных пошаговых туров по интерфейсу веб-приложений. Для начала необходимо подключить библиотеку. Есть несколько способов:

Через npm:

npm install shepherd.js

Через CDN:

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

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

Для создания тура используется класс Shepherd.Tour:

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

Пояснения:

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

Добавление шагов осуществляется методом addStep:

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага с подсказкой.',
  attachTo: {
    element: '.example-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Ключевые параметры шага:

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

Управление навигацией

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

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

Пример динамического управления:

document.querySelector('#start-tour').addEventListener('click', () => {
  tour.start();
});

Методы next и back можно вызывать внутри кнопок шагов для плавной навигации.

Настройка внешнего вида и позиционирования

Shepherd.js поддерживает детальную кастомизацию через CSS-классы и опции шага. Основные возможности:

  • Классы: можно использовать классы из Tailwind или собственного CSS.
  • Привязка к элементам: через attachTo с параметрами element и on.
  • Скроллинг: объект scrollTo позволяет автоматически прокручивать страницу до видимой области целевого элемента.
  • Модальные оверлеи: для затемнения фонового интерфейса можно подключить библиотеку tether или использовать собственный слой через CSS.

Пример позиционирования подсказки справа от элемента:

tour.addStep({
  id: 'right-step',
  text: 'Подсказка справа',
  attachTo: { element: '#target', on: 'right' }
});

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

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

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

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

Пример использования событий:

tour.on('complete', () => {
  console.log('Тур завершён!');
});

tour.addStep({
  id: 'event-step',
  text: 'Шаг с событием',
  attachTo: { element: '#event', on: 'top' }
}).on('show', () => {
  console.log('Шаг отображён');
});

События позволяют реализовать сложные логики: изменение состояния UI, запуск анимаций, подгрузку данных.

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

Шаги можно создавать программно на основе данных или состояния приложения. Пример генерации шагов из массива:

const stepsData = [
  { id: 'step1', selector: '#one', text: 'Первый шаг' },
  { id: 'step2', selector: '#two', text: 'Второй шаг' },
  { id: 'step3', selector: '#three', text: 'Третий шаг' }
];

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

Такой подход упрощает поддержку больших туров и позволяет гибко менять их структуру.

Работа с пользовательскими кнопками и действиями

Кнопки могут выполнять любые функции, не ограничиваясь next и back. Пример:

tour.addStep({
  id: 'custom-action-step',
  text: 'Шаг с кастомным действием',
  attachTo: { element: '#custom', on: 'top' },
  buttons: [
    {
      text: 'Закрыть',
      action: () => {
        alert('Тур закрыт');
        tour.cancel();
      }
    },
    {
      text: 'Следующий',
      action: tour.next
    }
  ]
});

Любое действие кнопки может вызывать методы Shepherd.js, манипулировать DOM или запускать внешние функции.

Поддержка мобильных устройств

Shepherd.js корректно работает на мобильных устройствах. Для улучшения опыта стоит учитывать:

  • scrollTo для автоматической прокрутки.
  • Адаптивные позиции шагов: top, bottom, left, right.
  • Возможность скрывать или изменять текст шагов для маленьких экранов.
  • Использование CSS медиазапросов для изменения размера подсказки.

Пример адаптивного класса:

.shepherd-content {
  max-width: 300px;
}

@media (min-width: 768px) {
  .shepherd-content {
    max-width: 500px;
  }
}

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

Shepherd.js легко интегрируется с React, Vue и Angular через жизненные циклы компонентов:

React пример:

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

function TourComponent() {
  useEffect(() => {
    const tour = new Shepherd.Tour({ defaultStepOptions: { scrollTo: true } });
    tour.addStep({ id: 'step1', text: 'Привет', attachTo: { element: '#react', on: 'bottom' }, buttons: [{ text: 'Далее', action: tour.next }] });
    tour.start();
  }, []);

  return 
Элемент для подсказки
;
}

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

Оглавление