Создание React-компонента тура

Для работы с Shepherd.js в React необходимо установить библиотеку и её зависимости. Основная команда для установки через npm:

npm install shepherd.js

Shepherd.js требует наличие CSS-стилей, которые обеспечивают корректное отображение подсказок и навигационных элементов тура. Их можно подключить в корневом компоненте React:

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

После подключения CSS и установки библиотеки можно импортировать Shepherd в компонент:

import Shepherd from 'shepherd.js';

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

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: {
      enabled: true
    },
    scrollTo: { beh * avior: 'smooth', block: 'center' },
    classes: 'shepherd-theme-arrows'
  },
  useModalOverlay: true
});

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

  • defaultStepOptions – настройки для всех шагов тура по умолчанию. Позволяет задать стиль, поведение кнопок и автоматическую прокрутку.
  • useModalOverlay – затемняет фон вокруг текущего шага, делая внимание пользователя сосредоточенным на подсказке.

Определение шагов тура

Шаги добавляются методом addStep, каждый шаг описывает элемент DOM, к которому привязывается подсказка, текст, кнопки управления и расположение:

tour.addStep({
  id: 'intro-step',
  text: 'Это первый шаг вашего тура.',
  attachTo: {
    element: '.intro-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

tour.addStep({
  id: 'feature-step',
  text: 'Здесь отображается основная функциональность.',
  attachTo: {
    element: '.feature-panel',
    on: 'right'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Закрыть',
      action: tour.cancel
    }
  ]
});

Особенности attachTo:

  • element – CSS-селектор или DOM-узел, к которому привязывается подсказка.
  • on – позиция подсказки относительно элемента (top, bottom, left, right).
  • viewport – можно управлять поведением подсказки при выходе за пределы видимой области.

Интеграция с React-компонентом

Для использования Shepherd.js в React рекомендуется создавать кастомный хук или компонент-обёртку. Это обеспечивает корректное управление жизненным циклом тура.

Пример компонента React, инициирующего тур после монтирования:

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

const TourComponent = () => {
  useEffect(() => {
    const tour = new Shepherd.Tour({
      defaultStepOptions: {
        cancelIcon: { enabled: true },
        scrollTo: { beh * avior: 'smooth', block: 'center' },
        classes: 'shepherd-theme-arrows'
      },
      useModalOverlay: true
    });

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

    tour.addStep({
      id: 'feature',
      text: 'Обратите внимание на этот функциональный блок.',
      attachTo: { element: '.feature', on: 'right' },
      buttons: [
        { text: 'Назад', action: tour.back },
        { text: 'Закрыть', action: tour.cancel }
      ]
    });

    tour.start();

    return () => tour.cancel();
  }, []);

  return null;
};

export default TourComponent;

Обратите внимание:

  • Тур запускается внутри useEffect, чтобы гарантировать наличие всех DOM-элементов.
  • Возврат функции tour.cancel() обеспечивает корректное удаление всех подсказок при размонтировании компонента, предотвращая утечки памяти.

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

Каждая кнопка шага может иметь собственное действие:

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

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

Shepherd.js позволяет изменять стиль подсказок через классы и темы. Включены стандартные темы:

  • shepherd-theme-arrows – стрелки на подсказках.
  • shepherd-theme-default – минималистичный стиль.
  • shepherd-theme-dark – тёмная тема.

Класс можно задать глобально через defaultStepOptions.classes или для отдельного шага:

tour.addStep({
  id: 'custom-step',
  text: 'Пользовательская подсказка',
  attachTo: { element: '.custom-element', on: 'top' },
  classes: 'shepherd-theme-dark'
});

Работа с динамическим контентом

В React компоненты могут появляться и исчезать. Для корректной работы туров:

  1. Проверять наличие DOM-элемента перед вызовом attachTo.
  2. Использовать условные шаги или задержку запуска:
useEffect(() => {
  const checkElement = setInterval(() => {
    const element = document.querySelector('.dynamic-element');
    if (element) {
      tour.start();
      clearInterval(checkElement);
    }
  }, 100);

  return () => clearInterval(checkElement);
}, []);

Обработка событий тура

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

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

Пример подписки:

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

tour.on('show', (event) => {
  console.log('Показан шаг:', event.step.id);
});

Эти события позволяют интегрировать тур с аналитикой или выполнять дополнительные действия в приложении.

Использование модального оверлея и фокусировки

Опция useModalOverlay создаёт затемнённый фон и предотвращает взаимодействие пользователя с остальной частью страницы. Для улучшения UX можно управлять фокусом:

tour.addStep({
  id: 'focus-step',
  text: 'Этот элемент важен',
  attachTo: { element: '.focus-element', on: 'right' },
  buttons: [{ text: 'Далее', action: tour.next }],
  canClickTarget: false
});
  • canClickTarget: false блокирует клики на элементе во время шага.
  • Опция scrollTo обеспечивает плавную прокрутку и центрирование элемента.

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

Оглавление