Утилитарные функции

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true,
    cancelIcon: {
      enabled: true
    }
  },
  useModalOverlay: true
});
  • defaultStepOptions задаёт базовые настройки для всех шагов: стили, поведение скроллинга и наличие кнопки закрытия.
  • useModalOverlay позволяет затемнять фон и выделять элементы, повышая внимание пользователя на текущем шаге.

Создание шагов и их утилитарные свойства

Каждый шаг тура создаётся методом addStep. Важные утилиты включают условное отображение, динамическое позиционирование и обработку событий.

tour.addStep({
  id: 'intro',
  text: 'Это основной шаг с подсказкой.',
  attachTo: {
    element: '.header',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Следующий',
      action: tour.next
    }
  ],
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт')
  }
});
  • attachTo – связывает шаг с элементом DOM и определяет позицию подсказки.
  • buttons – массив кнопок, каждая из которых может использовать утилитарные функции tour.next, tour.back, tour.cancel.
  • when – объект событий для управления поведением шага.

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

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

  • tour.start() – запуск тура с первого шага.
  • tour.next() / tour.back() – переход вперёд и назад.
  • tour.cancel() – полное завершение тура.
  • tour.complete() – завершение тура и вызов всех callback событий завершения.

Пример динамического управления шагами:

if (document.querySelector('.special-element')) {
  tour.addStep({
    id: 'special',
    text: 'Эта подсказка появляется только при наличии элемента.',
    attachTo: { element: '.special-element', on: 'right' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
}

Динамическое позиционирование и адаптивность

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

  • scrollTo: true – прокрутка страницы к элементу.
  • cancelIcon.enabled – возможность закрыть шаг независимо от кнопок.
  • popperOptions – настройка библиотечного движка Popper.js для более точного позиционирования:
popperOptions: {
  modifiers: [
    { name: 'offset', options: { offset: [0, 10] } },
    { name: 'preventOverflow', options: { padding: 8 } }
  ]
}
  • offset задаёт отступ подсказки.
  • preventOverflow предотвращает выход подсказки за пределы окна.

Управление потоками шагов

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

tour.addStep({
  id: 'decision',
  text: 'Выберите один из вариантов:',
  buttons: [
    {
      text: 'Опция A',
      action: () => {
        tour.show('optionA');
      }
    },
    {
      text: 'Опция B',
      action: () => {
        tour.show('optionB');
      }
    }
  ]
});
  • Метод show(id) позволяет прыгать к конкретному шагу.
  • Утилитарная возможность создания «ветвящихся» сценариев делает тур гибким для разных пользовательских путей.

Пользовательские утилитарные функции

Можно расширять функциональность тура с помощью пользовательских утилит:

function highlightElement(selector) {
  const el = document.querySelector(selector);
  if (!el) return;
  el.style.boxShadow = '0 0 0 4px rgba(255, 165, 0, 0.6)';
}

tour.on('show', () => highlightElement('.highlighted'));
tour.on('hide', () => document.querySelector('.highlighted').style.boxShadow = '');
  • tour.on(event, callback) позволяет подписываться на глобальные события тура (start, complete, cancel, show, hide).
  • Пользовательские функции помогают выделять элементы, динамически менять контент шагов или интегрировать тур с внутренней логикой приложения.

Локализация и динамический текст

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

tour.addStep({
  id: 'localized',
  text: () => `Привет, ${userName}!`,
  buttons: [
    {
      text: () => (userLang === 'en' ? 'Next' : 'Далее'),
      action: tour.next
    }
  ]
});
  • Текст и кнопки могут быть функциями, возвращающими строки в зависимости от состояния приложения.
  • Это позволяет создавать полностью динамичные и персонализированные подсказки.

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

Для акцентирования внимания на конкретных элементах:

const tourWithOverlay = new Shepherd.Tour({
  useModalOverlay: true,
  defaultStepOptions: { modalOverlayOpeningPadding: 10 }
});
  • modalOverlayOpeningPadding – отступ между элементом и затемнённым фоном.
  • useModalOverlay делает тур визуально более выразительным, позволяя создавать эффект «маски» вокруг активного элемента.

Итоговые утилиты

Shepherd.js объединяет несколько категорий утилитарных функций:

  1. Управление шагами – addStep, show, next, back, cancel, complete.
  2. События и callbacks – when, on.
  3. Позиционирование – attachTo, scrollTo, popperOptions.
  4. Динамический контент – функции в text, buttons.
  5. Интерактивность – условные шаги и ветвящиеся потоки.
  6. Визуальные эффекты – модальные оверлеи, подсветка элементов.

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

Оглавление