Интеграция сторонних библиотек

Для начала работы с Shepherd.js необходимо подключить библиотеку в проект. Существует несколько способов: через npm, Yarn или CDN. При использовании npm:

npm install shepherd.js

И затем импорт в модуле:

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

Через CDN достаточно подключить CSS и JS в HTML:

<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>

Создание нового экземпляра тура:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: {
      enabled: true
    }
  },
  useModalOverlay: true
});

Здесь ключевые параметры:

  • scrollTo – автоматически прокручивает страницу до элемента.
  • cancelIcon – добавляет крестик для отмены тура.
  • useModalOverlay – затемняет фон, фокусируя внимание на шаге.

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

Шаги определяются методом addStep и включают текст, прикрепление к элементу и кнопки управления:

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

Ключевые моменты:

  • id – уникальный идентификатор шага.
  • text – содержимое подсказки, поддерживаются HTML-теги.
  • attachTo – объект с element (CSS селектор) и on (позиция: top, bottom, left, right).
  • buttons – массив объектов с текстом кнопки и функцией действия.

Дополнительно можно использовать события шага:

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

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

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

1. Vue.js

В проектах на Vue.js удобно использовать ref для элементов и динамически подключать шаги Shepherd:

import { ref, onMounted } from 'vue';
import Shepherd from 'shepherd.js';

export default {
  setup() {
    const buttonRef = ref(null);

    onMounted(() => {
      const tour = new Shepherd.Tour({
        defaultStepOptions: { scrollTo: true }
      });

      tour.addStep({
        id: 'vue-step',
        text: 'Кнопка Vue.js',
        attachTo: { element: buttonRef.value, on: 'bottom' },
        buttons: [{ text: 'Далее', action: tour.next }]
      });

      tour.start();
    });

    return { buttonRef };
  }
}

2. React

В React можно использовать useEffect для инициализации тура после рендеринга компонентов:

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

function TourComponent() {
  const buttonRef = useRef(null);

  useEffect(() => {
    const tour = new Shepherd.Tour({
      defaultStepOptions: { scrollTo: true }
    });

    tour.addStep({
      id: 'react-step',
      text: 'Кнопка React',
      attachTo: { element: buttonRef.current, on: 'right' },
      buttons: [{ text: 'Далее', action: tour.next }]
    });

    tour.start();
  }, []);

  return <button ref={buttonRef}>Нажми меня</button>;
}

3. Angular

В Angular интеграция выполняется через сервис или хук ngAfterViewInit:

import { AfterViewInit, Component, ViewChild, ElementRef } from '@angular/core';
import Shepherd from 'shepherd.js';

@Component({
  selector: 'app-tour',
  template: `<button #btn>Кнопка Angular</button>`
})
export class TourComponent implements AfterViewInit {
  @ViewChild('btn') button!: ElementRef;

  ngAfterViewInit() {
    const tour = new Shepherd.Tour({
      defaultStepOptions: { scrollTo: true }
    });

    tour.addStep({
      id: 'angular-step',
      text: 'Кнопка Angular',
      attachTo: { element: this.button.nativeElement, on: 'top' },
      buttons: [{ text: 'Далее', action: tour.next }]
    });

    tour.start();
  }
}

Расширение функционала через сторонние библиотеки

1. Работа с анимацией

Shepherd.js можно комбинировать с GSAP для создания плавного появления подсказок:

tour.on('show', () => {
  gsap.from('.shepherd-element', { opacity: 0, y: -20, duration: 0.5 });
});

2. Интеграция с библиотекой форм

Для форм, построенных с помощью Formik или Vue Formulate, удобно использовать attachTo на динамически создаваемых элементах и обновлять тур при изменении DOM:

form.on('fieldAdded', (field) => {
  tour.addStep({
    id: `field-${field.name}`,
    text: `Поле ${field.label}`,
    attachTo: { element: field.element, on: 'right' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
});

3. Поддержка модальных окон

Shepherd.js поддерживает туры внутри модальных окон. Важно вызывать tour.start() после того, как модальное окно полностью показано:

modal.on('shown.bs.modal', () => {
  tour.start();
});

Динамическое создание шагов

В крупных приложениях часто требуется генерировать шаги на основе данных:

const stepsData = [
  { id: 'step1', element: '.el1', text: 'Первый элемент' },
  { id: 'step2', element: '.el2', text: 'Второй элемент' },
  { id: 'step3', element: '.el3', text: 'Третий элемент' }
];

stepsData.forEach(step => {
  tour.addStep({
    id: step.id,
    text: step.text,
    attachTo: { element: step.element, on: 'bottom' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
});

Такой подход облегчает поддержку большого числа шагов, особенно при интеграции с динамическими интерфейсами и сторонними компонентами.

Советы по интеграции

  • Всегда проверять наличие элемента перед привязкой шага, особенно при динамическом DOM.
  • Для SPA-фреймворков вызывать tour.start() после рендеринга соответствующих компонентов.
  • Использовать события Shepherd (show, hide, complete) для синхронизации с внешними библиотеками.
  • Для сложных интерфейсов удобно хранить конфигурацию шагов в отдельном объекте или JSON.

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

Оглавление