Первый тур

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

npm install shepherd.js

Для использования в браузере через 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>

Важно помнить, что Shepherd.js зависит от библиотеки tippy.js, которая используется для позиционирования подсказок. Если подключение происходит через npm, зависимость подтягивается автоматически.

Создание экземпляра тура

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

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

Основные параметры defaultStepOptions:

  • classes – определяет CSS-класс для стилизации подсказки.
  • scrollTo – автоматически прокручивает страницу к целевому элементу.
  • cancelIcon – отображение кнопки закрытия подсказки.

Добавление шагов тура

Каждый шаг тура описывается объектом с набором опций: текст подсказки, элемент, к которому она привязана, кнопки и позиционирование.

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в первый тур по приложению!',
  attachTo: {
    element: '#main-header',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Важные опции шага:

  • id – уникальный идентификатор шага.
  • text – содержимое подсказки, может быть HTML.
  • attachTo – объект с полями element и on, определяющий привязку к элементу и позицию подсказки (top, bottom, left, right).
  • buttons – массив кнопок с действием (например, tour.next, tour.back, tour.complete).

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

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

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

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

tour.addStep({
  id: 'feature',
  text: 'Здесь вы можете управлять настройками.',
  attachTo: { element: '#settings-button', on: 'right' },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: () => {
        console.log('Переходим к следующему шагу');
        tour.next();
      }
    }
  ]
});

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

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

  • themes – предустановленные стили (shepherd-theme-arrows, shepherd-theme-default).
  • modal – включение модального фона вокруг подсказки.
  • classes – добавление пользовательских CSS-классов.
  • text/html – возможность вставлять HTML-разметку в подсказку.
tour.addStep({
  id: 'custom',
  text: '<strong>Особое уведомление:</strong> настройка активирована.',
  classes: 'shepherd-theme-default custom-step',
  attachTo: { element: '#custom-element', on: 'top' }
});

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

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

  • show – вызывается при отображении шага.
  • hide – вызывается при скрытии шага.
  • complete – вызывается при завершении тура.
  • cancel – вызывается при отмене тура.
tour.on('complete', () => {
  alert('Тур завершен!');
});

tour.addStep({
  id: 'feature-step',
  text: 'Это шаг с событием.',
  attachTo: { element: '#feature', on: 'left' },
  buttons: [{ text: 'Далее', action: tour.next }],
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт')
  }
});

Анимация и прокрутка

Shepherd.js автоматически поддерживает прокрутку к целевому элементу при помощи scrollTo: true. Дополнительно можно настроить анимацию появления подсказок через CSS или через опции Tippy.js:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: { beh * avior: 'smooth', block: 'center' },
    popperOptions: {
      modifiers: [
        { name: 'offset', options: { offset: [0, 10] } }
      ]
    }
  }
});

Многоуровневые туры и условные шаги

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

tour.addStep({
  id: 'conditional',
  text: 'Вы видите этот шаг только при включенной опции.',
  attachTo: { element: '#optional', on: 'bottom' },
  buttons: [
    {
      text: 'Далее',
      action: () => {
        if (userSettings.optionEnabled) {
          tour.show('optional-step');
        } else {
          tour.next();
        }
      }
    }
  ]
});

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

Shepherd.js корректно работает на мобильных устройствах, автоматически позиционируя подсказки и масштабируя их при необходимости. Рекомендуется использовать scrollTo: true для лучшего взаимодействия и учитывать размеры экрана при добавлении кастомных CSS-классов.

Хранение состояния тура

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

if (!localStorage.getItem('tourCompleted')) {
  tour.start();
}

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

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

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

Оглавление