Аудит зависимостей

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

npm install shepherd.js

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

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

Если используется классический HTML, подключение через CDN выглядит следующим образом:

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

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

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

Добавление шагов

Шаги тура создаются методом addStep. Каждый шаг может содержать:

  • title — заголовок шага.
  • text — описание или контент.
  • attachTo — объект с элементом и позицией (element: '#id', on: 'bottom').
  • buttons — массив кнопок с действиями (text, action, classes).

Пример создания шагов:

tour.addStep({
  id: 'step1',
  title: 'Навигация по сайту',
  text: 'Здесь находятся основные разделы меню.',
  attachTo: { element: '#menu', on: 'bottom' },
  buttons: [
    {
      text: 'Далее',
      action: tour.next,
      classes: 'shepherd-button-primary'
    }
  ]
});

tour.addStep({
  id: 'step2',
  title: 'Поиск',
  text: 'Используйте поиск для быстрого нахождения контента.',
  attachTo: { element: '#search', on: 'right' },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Закрыть',
      action: tour.cancel
    }
  ]
});

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

Основные методы экземпляра тура:

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

События можно отслеживать через on:

tour.on('show', function() {
  console.log('Шаг показан');
});

tour.on('complete', function() {
  console.log('Тур завершён');
});

Кастомизация внешнего вида

Shepherd.js предоставляет возможность настройки стилей через CSS-классы и опции шагов:

  • classes — добавление CSS-классов к шагу.
  • arrow — отображение или скрытие стрелки подсказки (true/false).
  • modalOverlayOpeningPadding — отступ вокруг выделяемого элемента при модальном оверлее.

Пример кастомного шага:

tour.addStep({
  id: 'customStep',
  title: 'Особый шаг',
  text: 'Этот шаг имеет уникальный стиль.',
  attachTo: { element: '#special', on: 'top' },
  classes: 'custom-shepherd-step',
  buttons: [
    {
      text: 'Закрыть',
      action: tour.cancel,
      classes: 'shepherd-button-danger'
    }
  ]
});

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

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

const dynamicElement = document.querySelector('#dynamic');
if (dynamicElement) {
  tour.addStep({
    id: 'dynamicStep',
    title: 'Динамический элемент',
    text: 'Элемент появился после загрузки страницы.',
    attachTo: { element: '#dynamic', on: 'bottom' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
}

Для SPA (Single Page Application) рекомендуется добавлять шаги после полной загрузки соответствующего компонента, чтобы элементы были доступны в DOM.

Локализация текста

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

tour.addStep({
  id: 'localizedStep',
  title: 'Заголовок',
  text: `
    
Подсказка с HTML содержимым.

    
Можно использовать переводимые строки.

  `,
  attachTo: { element: '#element', on: 'top' }
});

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

Интеграция с другими библиотеками

Shepherd.js хорошо сочетается с:

  • Frameworks: Vue, React, Angular. В React часто используют useEffect для инициализации тура после рендера компонента.
  • State management: Redux, Vuex для сохранения состояния прохождения тура.
  • CSS frameworks: Tailwind, Bootstrap для кастомизации кнопок и шагов.

Пример использования в React:

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

function TourComponent() {
  useEffect(() => {
    const tour = new Shepherd.Tour({ useModalOverlay: true });
    tour.addStep({
      id: 'reactStep',
      title: 'Компонент React',
      text: 'Подсказка привязана к React-элементу',
      attachTo: { element: '#reactElement', on: 'bottom' },
      buttons: [{ text: 'Далее', action: tour.next }]
    });
    tour.start();
  }, []);

  return 
Элемент для подсказки
;
}

Оптимизация производительности

Для крупных туров рекомендуется:

  • Разделять шаги на несколько туров, если их больше 10–15.
  • Загружать Shepherd.js асинхронно при необходимости.
  • Использовать scrollTo только для ключевых элементов, чтобы не перегружать анимацию.
  • Удалять шаги для элементов, которые не присутствуют на текущем экране, предотвращая ошибки attachTo на несуществующих элементах.

Аудит зависимостей Shepherd.js

Shepherd.js зависит от нескольких библиотек:

  1. tether.js — отвечает за позиционирование подсказок относительно элементов.
  2. popper.js — альтернативная библиотека для расчёта позиции подсказок, иногда используется в современных версиях.
  3. CSS reset — Shepherd.css учитывает базовые стили для корректного отображения модальных элементов.

Важно проверять актуальные версии зависимостей и их совместимость при обновлении проекта, чтобы избежать конфликтов стилей и неправильного позиционирования подсказок. Использование инструментов аудита, таких как npm audit, помогает обнаруживать уязвимости в зависимостях Shepherd.js и их подтягиваемых пакетах.

Оглавление