Публикация расширений

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

npm install shepherd.js

или

yarn add shepherd.js

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

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

Для старых проектов возможно использование CDN:

<link rel="stylesheet" href="https://unpkg.com/shepherd.js/dist/css/shepherd.css" />
<script src="https://unpkg.com/shepherd.js/dist/js/shepherd.min.js"></script>

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

Основой любого тура является объект Shepherd.Tour. Его создание выполняется через конструктор с передачей конфигурации:

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

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

  • classes — CSS-класс для стилизации подсказок. Shepherd поддерживает несколько встроенных тем (shepherd-theme-arrows, shepherd-theme-default и др.).
  • scrollTo — автоматическая прокрутка страницы к элементу, к которому привязан шаг.
  • cancelIcon — настройка значка закрытия подсказки.

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

Каждый шаг тура добавляется с помощью метода addStep и содержит следующие основные параметры:

tour.addStep({
  id: 'example-step',
  text: 'Описание действия на этом шаге',
  attachTo: {
    element: '.example-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Пояснения ключевых полей:

  • id — уникальный идентификатор шага. Используется для ссылок и управления навигацией.
  • text — основной текст подсказки. Может содержать HTML-разметку.
  • attachTo — объект, указывающий, к какому элементу DOM привязать подсказку, и с какой стороны (top, bottom, left, right).
  • buttons — массив кнопок, каждая из которых имеет текст и действие. Возможные действия: tour.next(), tour.back(), tour.cancel().

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

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

  • when — объект, содержащий обработчики событий. Например:
when: {
  show: () => console.log('Шаг показан'),
  hide: () => console.log('Шаг скрыт')
}
  • advanceOn — позволяет автоматически переходить к следующему шагу при определённом событии на элементе:
advanceOn: { selector: '.next-button', event: 'click' }
  • modalOverlayOpeningPadding — отступы для модального оверлея. Позволяет оставить пространство вокруг подсвечиваемого элемента.

Публикация расширений и модификация тура

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

Кастомные шаги

Создание кастомного шага осуществляется через наследование от Shepherd.Step:

class CustomStep extends Shepherd.Step {
  constructor(tour, options) {
    super(tour, options);
  }

  open() {
    console.log('Открыт кастомный шаг');
    super.open();
  }
}

После этого шаг добавляется в тур аналогично стандартным шагам:

tour.addStep(new CustomStep(tour, {
  id: 'custom-step',
  text: 'Кастомный шаг',
  attachTo: { element: '#custom', on: 'top' }
}));

Плагины для интеграции

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

Shepherd.plugins = Shepherd.plugins || {};

Shepherd.plugins.analyticsPlugin = {
  init(tour) {
    tour.on('complete', () => {
      console.log('Тур завершён, отправка данных в аналитику');
    });
  }
};

Для активации плагина достаточно вызвать:

Shepherd.plugins.analyticsPlugin.init(tour);

Настройка глобальных параметров для публикации

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

Shepherd.defaults = {
  classes: 'shepherd-theme-arrows custom-global',
  scrollTo: true,
  useModalOverlay: true
};
  • useModalOverlay — включает затемнение фона за подсказкой.
  • custom-global — дополнительный класс для унифицированной стилизации.

Советы по публикации расширений

  1. Изоляция кода — расширение не должно напрямую модифицировать внутренние методы Shepherd.js, лучше использовать наследование и события.
  2. Совместимость с CSS — стили нового шага должны быть независимыми, чтобы не ломать темы Shepherd.
  3. Документация — каждый плагин должен содержать описание параметров, событий и методов для использования другими разработчиками.
  4. События — использование событий (show, hide, complete) позволяет интегрировать расширения без изменения ядра библиотеки.

Автоматизация публикации

Для публикации расширений в npm или интеграции с проектами рекомендуется:

  • Собрать расширение через сборщики (Webpack, Vite).
  • Минимизировать CSS и JS для уменьшения размера.
  • Включить инструкции по установке и подключению в README.md.

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

Оглавление