Контекстная помощь

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

Создание нового тура начинается с инициализации объекта Shepherd.Tour с набором опций:

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

Добавление шагов производится методом addStep:

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

Управление навигацией и событиями

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

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

Шаги также могут иметь локальные события:

tour.addStep({
  id: 'feature',
  text: 'Эта кнопка открывает панель настроек.',
  attachTo: { element: '#settings-btn', on: 'right' },
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт')
  }
});
  • when.show выполняется при отображении шага.
  • when.hide выполняется при скрытии шага.

Это позволяет интегрировать интерактивные действия, например подсветку элементов интерфейса или запуск анимаций.

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

Кнопки шага поддерживают множество конфигураций, включая произвольные функции:

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

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

Shepherd.js использует библиотеку Popper.js для расчёта позиции подсказки. attachTo позволяет привязать шаг к элементу и указать направление:

attachTo: {
  element: '#profile-pic',
  on: 'left'
}

Возможные значения on:

  • top
  • bottom
  • left
  • right

Для динамических интерфейсов можно использовать селекторы или DOM-элементы, полученные программно, что позволяет адаптировать тур под разные состояния страницы.

Модальные оверлеи и акцент на элементах

Включение useModalOverlay создаёт затемнённый фон и блокирует взаимодействие с другими элементами страницы, кроме текущего шага. Для отдельных шагов можно использовать свойство modal: true, чтобы акцентировать внимание на конкретной области:

tour.addStep({
  id: 'important-step',
  text: 'Это ключевая функция приложения.',
  attachTo: { element: '#key-feature', on: 'top' },
  modal: true
});

Это создаёт визуальный эффект «фокусировки» на элементе, улучшая восприятие контекстной помощи.

Динамическое управление шагами

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

tour.addStep({
  id: 'extra-step',
  text: 'Этот шаг добавлен в процессе выполнения тура.'
});

tour.removeStep('extra-step');

const step = tour.getById('welcome');
step.updateStepOptions({ text: 'Обновлённый текст шага' });
  • getById возвращает объект шага для изменения его свойств.
  • updateStepOptions позволяет менять текст, кнопки и привязку без перезапуска тура.

Работа с условиями отображения

Можно создавать шаги, которые отображаются только при определённых условиях:

tour.addStep({
  id: 'conditional-step',
  text: 'Этот шаг виден только если пользователь вошёл в систему.',
  beforeShowPromise: () => {
    return new Promise((resolve) => {
      if (user.isLoggedIn) resolve();
      else tour.next();
    });
  }
});
  • beforeShowPromise позволяет выполнить асинхронную проверку перед показом шага.
  • Если условие не выполняется, шаг можно пропустить с помощью tour.next().

Стиль и кастомизация

Shepherd.js поддерживает полное кастомное оформление через CSS:

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

.shepherd-theme-arrows .shepherd-cancel-icon {
  fill: #ff4500;
}
  • Классы темы влияют на подсказки, стрелки и кнопки.
  • Возможна интеграция с существующими CSS-фреймворками, такими как Bootstrap или Tailwind, для единого визуального стиля.

Интеграция с приложением

Туры Shepherd.js легко подключаются к SPA (Single Page Application) на Vue, React или Angular. Основной подход заключается в запуске тура после рендера компонентов и привязке шагов к DOM-элементам с актуальными селекторами:

import Shepherd from 'shepherd.js';

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

// добавление шагов после рендера
setTimeout(() => {
  tour.start();
}, 500);
  • Задержка или использование nextTick гарантирует, что элементы будут доступны для привязки.

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

Оглавление