back

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

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

Для начала работы необходимо создать объект тура:

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});
  • defaultStepOptions — глобальные настройки для всех шагов тура.
  • classes — CSS-класс для стилизации подсказок.
  • scrollTo — автоматически прокручивает страницу к элементу, если он вне видимой области.

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

Каждый шаг добавляется методом addStep и включает минимум:

  • id — уникальный идентификатор шага.
  • text — содержимое подсказки (текст, HTML).
  • attachTo — элемент DOM, к которому привязывается подсказка, и позиция относительно него.
  • buttons — массив кнопок для навигации между шагами.

Пример добавления шага:

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать! Это первый шаг тура.',
  attachTo: {
    element: '#start-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});
  • attachTo.element может быть селектором CSS или элементом DOM.
  • attachTo.on задаёт позицию подсказки: top, bottom, left, right.
  • action определяет функцию при нажатии кнопки (tour.next, tour.back, tour.cancel).

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

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

buttons: [
  {
    text: 'Назад',
    action: tour.back,
    classes: 'shepherd-button-secondary'
  },
  {
    text: 'Далее',
    action: tour.next,
    classes: 'shepherd-button-primary'
  },
  {
    text: 'Пропустить',
    action: tour.cancel
  }
]
  • tour.next — переход к следующему шагу.
  • tour.back — возврат к предыдущему шагу.
  • tour.cancel — завершение тура.
  • Классы кнопок позволяют создавать визуальные различия (например, основной и второстепенный стиль).

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

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

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

На уровне шага можно использовать события show, hide:

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

Встроенные функции и методы

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

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

Пример условного запуска шага:

if (document.querySelector('#special-feature')) {
  tour.show('feature-step');
} else {
  tour.next();
}

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

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

  • shepherd-theme-arrows — стрелки у подсказки.
  • shepherd-theme-default — стандартная тема без стрелок.

Дополнительно можно переопределять CSS для кастомизации:

.shepherd-button-primary {
  background-color: #1e90ff;
  color: #fff;
}

.shepherd-theme-arrows .shepherd-arrow {
  border-color: #1e90ff;
}
  • Изменение цвета кнопок и стрелок помогает интегрировать тур в существующий UI.
  • Каждому шагу можно задавать индивидуальный класс через classes.

Советы по созданию сложных туров

  1. Динамические шаги — шаги могут добавляться в зависимости от состояния страницы.
  2. Условные кнопки — кнопки могут изменять действие при разных условиях.
  3. Использование scrollTo — помогает пользователю видеть скрытые элементы.
  4. Встраивание HTML-контента — можно включать списки, изображения и интерактивные элементы.
  5. События шагов для аналитики — отслеживание прогресса пользователя через show/hide.

Пример полного тура

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

tour.addStep({
  id: 'step1',
  text: 'Начнем с кнопки запуска.',
  attachTo: { element: '#start', on: 'bottom' },
  buttons: [{ text: 'Далее', action: tour.next }]
});

tour.addStep({
  id: 'step2',
  text: 'Здесь представлены основные функции.',
  attachTo: { element: '#features', on: 'right' },
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ]
});

tour.addStep({
  id: 'step3',
  text: 'Финальный шаг, наслаждайтесь!',
  attachTo: { element: '#end', on: 'top' },
  buttons: [{ text: 'Завершить', action: tour.complete }]
});

tour.start();

Этот пример демонстрирует последовательность шагов, базовую навигацию и завершение тура.

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

Оглавление