Интеграция с Vue

Для использования Shepherd.js в Vue необходимо сначала установить библиотеку через npm или yarn:

npm install shepherd.js
# или
yarn add shepherd.js

После установки импортируется CSS для корректного отображения подсказок:

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

Для Vue 3 рекомендуется создавать экземпляр Shepherd в составе компонента или через отдельный сервис, который будет управлять всеми шагами тура.

export default {
  data() {
    return {
      tour: null
    };
  },
  mounted() {
    this.tour = new Shepherd.Tour({
      defaultStepOptions: {
        scrollTo: true,
        cancelIcon: {
          enabled: true
        },
        classes: 'shepherd-theme-arrows'
      }
    });
  }
};

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

Каждый шаг создается с указанием селектора элемента, текста подсказки и позиции:

this.tour.addStep({
  id: 'step-1',
  text: 'Это главный заголовок страницы.',
  attachTo: {
    element: '.header-title',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: this.tour.next
    }
  ]
});

this.tour.addStep({
  id: 'step-2',
  text: 'Здесь отображается основное меню.',
  attachTo: {
    element: '.main-menu',
    on: 'right'
  },
  buttons: [
    {
      text: 'Назад',
      action: this.tour.back
    },
    {
      text: 'Далее',
      action: this.tour.next
    }
  ]
});

Шаги можно добавлять динамически, в зависимости от состояния компонента или данных, используя реактивность Vue.

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

Shepherd.js предоставляет методы для управления туром:

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

В компоненте Vue управление туром можно привязать к кнопкам или событиям:

<button @click="tour.start()">Начать тур</button>

Интеграция с реактивными данными

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

watch(() => this.isFeatureAvailable, (newVal) => {
  if (newVal) {
    this.tour.addStep({
      id: 'feature-step',
      text: 'Эта функция доступна только при включении настройки.',
      attachTo: {
        element: '.feature-button',
        on: 'top'
      },
      buttons: [
        { text: 'Закрыть', action: this.tour.cancel }
      ]
    });
  }
});

Такой подход позволяет создавать адаптивные туры, которые меняются вместе с интерфейсом.

Использование событий Shepherd.js

Shepherd.js поддерживает события для отслеживания действий пользователя:

  • show — когда шаг показывается.
  • hide — когда шаг скрывается.
  • complete — когда тур завершен.
  • cancel — когда тур отменен.

В Vue их можно использовать через on:

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

this.tour.on('show', (step) => {
  console.log(`Показывается шаг: ${step.id}`);
});

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

Использование кастомных компонентов Vue внутри подсказок

Shepherd.js поддерживает кастомные элементы внутри подсказок через опцию text с HTML:

this.tour.addStep({
  id: 'custom-step',
  text: `
    <div>
      <h3>Заголовок</h3>
      <p>Описание шага с <strong>форматированием</strong>.</p>
      <button id="custom-btn">Нажми меня</button>
    </div>
  `,
  attachTo: {
    element: '.custom-element',
    on: 'bottom'
  }
});

Для работы с событиями кнопок в Vue можно использовать делегирование через mounted хук или $nextTick.

Динамическая подгрузка шагов из данных

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

const steps = [
  { id: 'step-1', element: '.header-title', text: 'Заголовок', position: 'bottom' },
  { id: 'step-2', element: '.main-menu', text: 'Меню', position: 'right' }
];

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

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

Настройка тем и стилей

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

.shepherd-theme-custom {
  background-color: #fff;
  color: #333;
  border-radius: 10px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

Применение темы в туре:

this.tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-custom',
    scrollTo: true
  }
});

Управление позиционированием

Shepherd.js автоматически позиционирует шаги относительно элемента. Для Vue-компонентов с динамическим DOM важно учитывать момент появления элемента. Использование nextTick гарантирует, что элемент присутствует в DOM перед привязкой шага:

this.$nextTick(() => {
  this.tour.addStep({
    id: 'dynamic-step',
    text: 'Динамический элемент готов.',
    attachTo: { element: '.dynamic-element', on: 'top' },
    buttons: [{ text: 'Закрыть', action: this.tour.cancel }]
  });
});

Это предотвращает ошибки позиционирования и гарантирует корректное отображение подсказок.

Оглавление