Создание плагинов

Shepherd.js построен вокруг концепции туров, которые состоят из последовательности шагов. Для расширения функционала библиотеки используется система плагинов, позволяющая подключать дополнительное поведение к шагам или туру в целом. Плагин — это объект с методами, которые Shepherd.js вызывает в определённые моменты жизненного цикла тура.

Базовая структура плагина выглядит следующим образом:

const myPlugin = {
  id: 'example-plugin', // уникальный идентификатор плагина
  initialize(tour) {
    // вызывается при добавлении плагина к туру
  },
  onStart() {
    // выполняется при запуске тура
  },
  onShow(step) {
    // вызывается перед отображением каждого шага
  },
  onComplete() {
    // вызывается после завершения тура
  }
};

id — обязательное поле, идентификатор плагина.
initialize(tour) — инициализация плагина при добавлении к туру, здесь можно сохранять ссылки на тур или шаги, добавлять слушатели событий.
onStart() — логика, выполняемая при старте тура.
onShow(step) — возможность модифицировать шаг перед его показом.
onComplete() — завершающие действия после окончания тура.

Подключение плагина к туру

Плагин добавляется с помощью метода use объекта тура:

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

tour.use(myPlugin);

tour.start();

Важно помнить, что метод use может принимать массив плагинов, что позволяет подключать несколько расширений сразу. Плагины регистрируются в порядке добавления, и порядок вызова их методов соответствует этому порядку.

Доступ к шагам и их модификация

Плагин получает доступ к шагам через объект тура. В методе initialize удобно подготовить все необходимые изменения:

const highlightPlugin = {
  id: 'highlight-step',
  initialize(tour) {
    this.tour = tour;
    tour.on('show', (step) => {
      const element = step.options.attachTo?.element;
      if (element) {
        element.style.border = '2px solid red';
      }
    });
  }
};

Здесь используется событие show тура для изменения DOM элемента, к которому привязан шаг. Использование событий — основной способ взаимодействия плагина с туром и его шагами.

Создание кастомных действий для шагов

Плагины позволяют добавлять собственные кнопки и действия для шагов. Для этого применяются события или модификация опций шага внутри onShow:

const actionPlugin = {
  id: 'custom-action',
  onShow(step) {
    step.addButton({
      text: 'Сделать что-то',
      action: () => {
        console.log('Действие выполнено');
        step.next();
      }
    });
  }
};

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

Управление состоянием плагина

Каждый плагин может хранить своё состояние. Для этого используют свойства объекта плагина или WeakMap для безопасного хранения данных, привязанных к туре или шагам:

const counterPlugin = {
  id: 'step-counter',
  initialize(tour) {
    this.count = 0;
    tour.on('show', () => {
      this.count++;
      console.log(`Показано шагов: ${this.count}`);
    });
  }
};

Такой подход позволяет отслеживать прогресс или состояние взаимодействия пользователя с туром.

Взаимодействие нескольких плагинов

При использовании нескольких плагинов важно учитывать порядок их подключения. Методы onShow, onStart и другие вызываются последовательно, в порядке регистрации. Если два плагина изменяют одни и те же свойства шага, последний зарегистрированный плагин может перезаписать изменения предыдущего. Для предотвращения конфликтов рекомендуется:

Использовать уникальные идентификаторы шагов или классы CSS для модификаций.
Проверять наличие изменений перед их применением.
Взаимодействовать через события тура, а не напрямую изменять шаги других плагинов.

Практические примеры плагинов

Автоматическое пролистывание шагов через таймер

const autoNextPlugin = {
  id: 'auto-next',
  onShow(step) {
    setTimeout(() => step.next(), 3000);
  }
};

Подсветка элементов с помощью CSS-анимации

const pulsePlugin = {
  id: 'pulse-highlight',
  onShow(step) {
    const el = step.options.attachTo?.element;
    if (el) el.classList.add('pulse-animation');
    step.on('hide', () => el?.classList.remove('pulse-animation'));
  }
};

Логирование действий пользователя

const logPlugin = {
  id: 'action-logger',
  initialize(tour) {
    tour.on('complete', () => console.log('Тур завершён'));
    tour.on('cancel', () => console.log('Тур отменён'));
  }
};

Эти примеры демонстрируют, что плагин может выполнять любые задачи: модифицировать шаги, управлять DOM, отслеживать события или интегрировать внешние сервисы.