Класс Tour

Shepherd.js — это библиотека для создания интерактивных пошаговых руководств по интерфейсу веб-приложений. Центральным элементом управления туром является класс Tour. Он инкапсулирует весь процесс создания, управления и завершения последовательности шагов.

Создание экземпляра Tour

Экземпляр Tour создается с помощью конструктора:

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

Пояснения:

  • defaultStepOptions — объект, задающий общие параметры для всех шагов тура. Позволяет не дублировать настройки для каждого шага.
  • scrollTo — автоматически прокручивает страницу к целевому элементу.
  • cancelIcon — добавляет кнопку закрытия тура на каждом шаге.
  • classes — CSS-класс для кастомизации внешнего вида шагов.
  • useModalOverlay — затемняет фон страницы, фокусируя внимание на элементе тура.

Добавление шагов

Шаги добавляются методом addStep. Каждый шаг описывается объектом с обязательным ключом id и параметрами text, attachTo и buttons:

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

Ключевые параметры шагов:

  • id — уникальный идентификатор шага.

  • text — текстовое содержание подсказки.

  • attachTo — объект, задающий привязку подсказки к элементу страницы:

    • element — CSS-селектор или DOM-элемент.
    • on — позиция подсказки относительно элемента (top, bottom, left, right).

  • buttons — массив кнопок управления шагом. Каждая кнопка может выполнять действия, такие как tour.next(), tour.back(), tour.complete().

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

Экземпляр класса Tour предоставляет несколько методов для управления прогрессом:

  • start() — запускает тур с первого шага.
  • next() — переходит к следующему шагу.
  • back() — возвращается к предыдущему шагу.
  • cancel() — завершает тур принудительно.
  • complete() — отмечает тур как завершенный и скрывает все шаги.
  • show(stepId) — показывает указанный шаг по идентификатору.
  • hide() — скрывает текущий шаг без завершения тура.

Пример использования методов:

tour.start(); // запускает тур
tour.next();  // переходит к следующему шагу
tour.complete(); // завершает тур

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

Shepherd.js позволяет гибко настраивать стиль подсказок через CSS-классы и параметры шага:

tour.addStep({
  id: 'custom-step',
  text: 'Шаг с кастомной кнопкой и стилем',
  classes: 'shepherd-theme-arrows custom-step',
  buttons: [
    {
      text: 'Закрыть',
      action: tour.cancel,
      classes: 'btn btn-danger'
    }
  ]
});
  • classes — применяемые CSS-классы для конкретного шага.
  • Кнопки могут иметь свои классы для кастомизации внешнего вида.

Обработка событий

Класс Tour поддерживает события, которые помогают отслеживать прогресс или реагировать на действия пользователя:

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур завершен'));
tour.on('show', (event) => console.log('Показан шаг:', event.step.id));
tour.on('cancel', () => console.log('Тур отменен'));

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

Интеграция с динамическими элементами

Shepherd.js корректно работает с элементами, которые появляются на странице динамически. Для этого важно, чтобы шаг добавлялся после рендеринга элемента, или использовать метод tour.addStep динамически при необходимости. Также полезно комбинировать с scrollTo и проверкой наличия элемента перед отображением шага.

if (document.querySelector('#dynamic-element')) {
  tour.addStep({
    id: 'dynamic-step',
    text: 'Шаг для динамического элемента',
    attachTo: {
      element: '#dynamic-element',
      on: 'top'
    },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
}

Продвинутые параметры шага

Дополнительно шаги могут включать:

  • modal — создание модального overlay для фокусировки.
  • scrollTo — позиционирование с плавной прокруткой.
  • highlightClass — CSS-класс для подсветки целевого элемента.
  • advanceOn — событие, на котором автоматически переходит к следующему шагу:
tour.addStep({
  id: 'auto-advance',
  text: 'Этот шаг пропускается по клику на кнопку',
  attachTo: { element: '#btn', on: 'right' },
  advanceOn: { selector: '#btn', event: 'click' }
});

Примеры типичных сценариев

  1. Простой линейный тур:

    • последовательность шагов без ветвлений, стандартные кнопки «Далее» и «Назад».

  2. Тур с модальным overlay:

    • затемнение фона для концентрации внимания, полезно для сложных интерфейсов.

  3. Тур с авто-продвижением:

    • шаги переходят автоматически при наступлении события (например, клик по кнопке или ввод текста).

  4. Динамический тур:

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

Использование класса Tour в Shepherd.js предоставляет полный контроль над интерактивным руководством, позволяет строить как простые линейные туры, так и сложные динамические сценарии с кастомными стилями и обработкой событий.

Оглавление