start

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

Установка и подключение

Shepherd.js можно подключить двумя способами:

  1. Через npm:
npm install shepherd.js
  1. Через CDN:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/shepherd.js/dist/css/shepherd.css" />
<script src="https://cdn.jsdelivr.net/npm/shepherd.js/dist/js/shepherd.min.js"></script>

После подключения необходимо создать экземпляр тура:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: {
      enabled: true
    }
  }
});

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

Создание шагов

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

  • id — уникальный идентификатор шага.
  • text — текст подсказки, поддерживает HTML.
  • attachTo — объект {element: 'селектор', on: 'позиция'} для привязки подсказки к элементу.
  • buttons — массив кнопок для навигации.

Пример:

tour.addStep({
  id: 'step-1',
  text: 'Это главный элемент интерфейса.',
  attachTo: {
    element: '#main-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Вперёд',
      action: tour.next
    }
  ]
});

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

Позиционирование подсказок

Shepherd.js поддерживает несколько позиций относительно элемента:

  • top, bottom, left, right
  • top-start, top-end, bottom-start, bottom-end
  • left-start, left-end, right-start, right-end

Позицию можно изменять динамически через параметр attachTo.on.

Настройка визуального оформления

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

  • .shepherd-element — основной контейнер подсказки.
  • .shepherd-header — заголовок шага.
  • .shepherd-content — текст подсказки.
  • .shepherd-footer — область кнопок.

Пример кастомизации:

.shepherd-element {
  background-color: #2a2a2a;
  color: #fff;
  border-radius: 8px;
  padding: 15px;
}

.shepherd-button {
  background-color: #ff6600;
  color: white;
  border: none;
  padding: 8px 12px;
  border-radius: 4px;
}

Управление туром

Основные методы тура:

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

Shepherd.js поддерживает события:

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

Пример подписки на событие:

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

Продвинутая навигация

Для сложных сценариев можно использовать условные переходы:

tour.addStep({
  id: 'step-conditional',
  text: 'Выберите вариант для продолжения.',
  buttons: [
    {
      text: 'Вариант 1',
      action: () => {
        tour.next('step-variant-1');
      }
    },
    {
      text: 'Вариант 2',
      action: () => {
        tour.next('step-variant-2');
      }
    }
  ]
});

Здесь next('step-variant-1') указывает на конкретный следующий шаг по ID, позволяя создавать ветвящиеся туры.

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

Shepherd.js легко интегрируется с React, Vue и Angular. Основная стратегия:

  1. Создать тур при монтировании компонента.
  2. Добавить шаги после рендера DOM.
  3. Запустить тур после загрузки страницы или компонента.

Пример для React:

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

function AppTour() {
  useEffect(() => {
    const tour = new Shepherd.Tour({
      defaultStepOptions: { scrollTo: true }
    });

    tour.addStep({
      id: 'welcome',
      text: 'Добро пожаловать!',
      buttons: [{ text: 'Далее', action: tour.next }]
    });

    tour.start();
  }, []);

  return null;
}

Управление прокруткой и адаптивность

Shepherd.js автоматически скроллит страницу к элементу через scrollTo: true. Для более сложных случаев можно использовать beforeShowPromise для асинхронного ожидания загрузки элементов:

tour.addStep({
  id: 'async-step',
  text: 'Элемент будет доступен через 1 секунду.',
  attachTo: { element: '#async-element', on: 'top' },
  beforeShowPromise: () => new Promise(resolve => setTimeout(resolve, 1000)),
  buttons: [{ text: 'Далее', action: tour.next }]
});

Работа с локализацией и HTML-контентом

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

tour.addStep({
  id: 'html-step',
  text: '<strong>Важно:</strong> выполните это действие.',
  buttons: [{ text: 'Понятно', action: tour.next }]
});

Для локализации достаточно формировать текст шагов динамически или подключать внешние ресурсы с переводами.

Кастомные кнопки и действия

Помимо стандартных next и back, можно создавать свои действия:

tour.addStep({
  id: 'custom-step',
  text: 'Нажмите кнопку для выполнения действия.',
  buttons: [
    {
      text: 'Скрыть элемент',
      action: () => {
        document.querySelector('#special').style.display = 'none';
        tour.next();
      }
    }
  ]
});

Использование модулей и плагинов

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

Если нужно, могу продолжить с разделами «Оптимизация производительности и управление большим количеством шагов» и «Сложные сценарии туров с условиями и ветвлениями», где подробно разбирается продвинутое использование Shepherd.js в реальных проектах.

Хотите, чтобы я добавил эти разделы?

Оглавление