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

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

npm install shepherd.js

или

yarn add shepherd.js

Затем в компоненте Svelte подключается CSS-стилизация и сам скрипт:

<script>
  import Shepherd from 'shepherd.js';
  import 'shepherd.js/dist/css/shepherd.css';
</script>

CSS-файл необходим для корректного отображения подсказок, стрелок и кнопок навигации.

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

Тур в Shepherd создается через класс Shepherd.Tour. Основные параметры включают:

  • defaultStepOptions — настройки для всех шагов по умолчанию (кнопки, классы, позиционирование)
  • useModalOverlay — затемнение фона для выделения активного элемента
  • scrollTo — автоматическая прокрутка к целевому элементу

Пример инициализации тура:

<script>
  let tour;

  function initializeTour() {
    tour = new Shepherd.Tour({
      defaultStepOptions: {
        classes: 'shepherd-theme-arrows',
        scrollTo: true,
        showCancelLink: true
      },
      useModalOverlay: true
    });

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

    tour.addStep({
      id: 'step-2',
      text: 'Это второй шаг тура.',
      attachTo: { element: '.second-element', on: 'top' },
      buttons: [
        {
          text: 'Назад',
          action: tour.back
        },
        {
          text: 'Закрыть',
          action: tour.complete
        }
      ]
    });
  }

  function startTour() {
    if (!tour) initializeTour();
    tour.start();
  }
</script>

Ключевым моментом является attachTo, который связывает шаг с DOM-элементом и указывает положение подсказки относительно него.

Реактивность и динамические элементы в Svelte

Svelte управляет DOM через реактивные переменные, поэтому элементы, к которым привязывается тур, могут появляться динамически. Важно запускать initializeTour после того, как элементы появятся в DOM. Это решается через $:, onMount или события:

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    initializeTour();
  });
</script>

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

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

Shepherd позволяет настраивать шаги глубоко:

  • text — строка или функция, возвращающая содержимое
  • title — заголовок шага
  • attachTo — элемент и позиция (top, bottom, left, right)
  • buttons — массив объектов с текстом и действием
  • advanceOn — событие для автоматического перехода к следующему шагу
  • when — объект с обработчиками событий show, hide, complete

Пример автоматического перехода на следующий шаг при клике на элемент:

tour.addStep({
  id: 'step-3',
  text: 'Нажмите на кнопку, чтобы продолжить.',
  attachTo: { element: '.continue-btn', on: 'right' },
  advanceOn: { selector: '.continue-btn', event: 'click' }
});

Глобальная настройка стиля и темы

Shepherd поддерживает темы через CSS-классы:

  • shepherd-theme-arrows — стандартная стрелочная тема
  • shepherd-theme-default — классическая
  • Возможность добавления своих классов через classes в defaultStepOptions или на уровне шага
defaultStepOptions: {
  classes: 'custom-shepherd-theme',
  scrollTo: { beh * avior: 'smooth', block: 'center' }
}

В Svelte удобнее создавать отдельный CSS-файл или <style> в компоненте с нужными стилями и подключать через classes.

Управление туром через компонент Svelte

Тур можно инкапсулировать в отдельный компонент:

<script>
  import { onMount } from 'svelte';
  import Shepherd from 'shepherd.js';
  import 'shepherd.js/dist/css/shepherd.css';

  export let start = false;

  let tour;

  onMount(() => {
    tour = new Shepherd.Tour({
      defaultStepOptions: { classes: 'shepherd-theme-arrows', scrollTo: true },
      useModalOverlay: true
    });

    tour.addStep({ id: 'step-1', text: 'Привет!', buttons: [{ text: 'Далее', action: tour.next }] });

    if (start) tour.start();
  });

  $: if (start && tour) tour.start();
</script>

Такой компонент можно использовать с пропсом start={true}, чтобы запускать тур автоматически или через реактивную переменную.

Обработка событий и интеграция с логикой приложения

Shepherd предоставляет события на уровне тура и шагов:

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

Пример подписки на событие завершения тура:

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

В Svelte можно обновлять состояние приложения на основе этих событий, связывая их с реактивными переменными или store.

Практические рекомендации для Svelte

  • Инициализация тура должна происходить после того, как целевые элементы добавлены в DOM.
  • Для динамически создаваемых компонентов использовать onMount и $: реактивные блоки.
  • Для больших проектов лучше вынести тур в отдельный компонент, чтобы управлять шагами централизованно.
  • Поддержка тем и кастомных стилей упрощается через классы и CSS-модули Svelte.
  • События тура позволяют интегрировать взаимодействие с другими элементами UI без сложной логики в компонентах.

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

Оглавление