Понятие шага

В библиотеке Shepherd.js шаг представляет собой базовую единицу интерактивного тура по веб-интерфейсу. Каждый шаг отвечает за отображение определённой информации пользователю, указание на элемент страницы и управление навигацией между другими шагами. Понимание структуры и возможностей шага является ключевым для эффективного построения обучающих туров.

Создание шага

Шаг создаётся с помощью метода addStep объекта тура (Tour). Основная структура шага включает несколько обязательных и опциональных параметров:

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

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага, который показывает подсказку на элементе.',
  attachTo: {
    element: '#my-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});
  • id – уникальный идентификатор шага, необходимый для навигации и управления состоянием тура.
  • text – текст подсказки. Может быть строкой или функцией, возвращающей строку для динамического контента.
  • attachTo – объект, указывающий, к какому элементу привязывается подсказка, и с какой стороны (on может быть top, bottom, left, right, а также сочетания вроде top-start).
  • buttons – массив объектов кнопок, определяющих действия пользователя на шаге (next, back, cancel и собственные функции).

Опции шага

Позиционирование

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

  • attachTo.element – CSS-селектор или DOM-элемент, к которому привязывается подсказка.
  • attachTo.on – положение относительно элемента. Можно комбинировать направления (top-start, bottom-end).
  • advanceOn – событие, по которому шаг автоматически продвигается, например:
advanceOn: { selector: '#next-button', event: 'click' }

Управление поведением

  • scrollTo – прокрутка страницы к элементу. Если задано true, библиотека плавно перемещает видимую область к цели.
  • when – объект с событиями шага (show, hide, complete). Позволяет выполнять колбэки при изменении состояния шага:
when: {
  show: () => console.log('Шаг показан'),
  hide: () => console.log('Шаг скрыт')
}

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

  • classes – CSS-классы для стилизации подсказки.
  • title – заголовок шага, отображаемый отдельным блоком.
  • arrow – включение/выключение стрелки указателя (true/false).

Динамические шаги

Шаги могут генерироваться динамически в зависимости от состояния страницы или действий пользователя. Например, можно создавать шаги для элементов, которые появляются после AJAX-загрузки:

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

Навигация между шагами

Каждый шаг поддерживает встроенные методы навигации:

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

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

Взаимодействие с пользователем

Шаг может содержать интерактивные элементы, такие как формы, ссылки или кнопки. Для улучшения UX используют:

  • modalOverlay: true – затемнение фона, чтобы сфокусировать внимание на подсказке.
  • canClickTarget: false – блокировка кликов по элементу под подсказкой.
  • highlightClass – CSS-класс для подсвечивания целевого элемента.

События шага

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

  • show – шаг стал видимым.
  • hide – шаг скрыт.
  • complete – шаг завершён через кнопку next или вручную.
  • cancel – шаг прерван.

Пример подписки на событие:

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

Множественные шаги и их упорядочивание

Шаги можно добавлять в любом порядке, но порядок навигации определяется последовательностью их добавления и методами next/back. Shepherd.js поддерживает:

  • Условные шаги, которые пропускаются при определённых условиях.
  • Повторное использование шагов в разных турах или их динамическое обновление.

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

  • Каждый шаг создаёт DOM-элемент подсказки при показе, поэтому количество одновременно отображаемых шагов не должно быть чрезмерным.
  • Для динамических страниц рекомендуется использовать scrollTo: true, чтобы подсказки всегда были видимыми.
  • События show и hide позволяют оптимизировать создание контента, например, загружать данные только при отображении шага.

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

Оглавление