Жизненный цикл шага

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

Создание и инициализация шага

Шаг создаётся через объект Shepherd.Tour с помощью метода addStep:

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

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

Ключевые моменты при инициализации:

  • id — уникальный идентификатор шага.
  • text — содержимое подсказки.
  • attachTo — объект с целевым элементом и позицией подсказки относительно него.
  • buttons — массив кнопок управления (Далее, Назад, Закрыть), каждая с определённым действием (tour.next, tour.back, tour.cancel).

При добавлении шага объект не отображается сразу. Он лишь создаётся и сохраняется в коллекции шагов тура.

События шага

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

  • show — шаг становится видимым.
  • before-show — срабатывает до появления шага.
  • hide — шаг скрывается.
  • complete — пользователь завершил шаг через действие.
  • cancel — шаг завершён принудительно (например, закрытие тура).

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

tour.on('show', function() {
  console.log('Шаг показан');
});

tour.on('hide', function() {
  console.log('Шаг скрыт');
});

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

Показ и скрытие шага

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

  • step.show() — отображает шаг.
  • step.hide() — скрывает шаг.
  • tour.next() — переходит к следующему шагу.
  • tour.back() — возвращается к предыдущему шагу.

Важно помнить:

  • show() автоматически проверяет наличие элемента attachTo.element. Если элемент отсутствует, Shepherd.js не отображает подсказку.
  • hide() удаляет подсказку с DOM, но шаг остаётся в памяти тура.
const step = tour.addStep({
  id: 'second-step',
  text: 'Следующий шаг',
  attachTo: { element: '.next-element', on: 'top' }
});

step.show(); // явное отображение
step.hide(); // скрытие

Управление кнопками и действиями

Каждая кнопка шага связана с определённой функцией (action), что даёт полный контроль над поведением:

buttons: [
  {
    text: 'Пропустить',
    action: () => {
      console.log('Шаг пропущен');
      tour.next();
    }
  },
  {
    text: 'Закрыть',
    action: tour.cancel
  }
]
  • action может быть любой функцией.
  • Использование tour.next() и tour.back() обеспечивает линейное прохождение тура.
  • tour.cancel() мгновенно завершает весь тур, независимо от текущего шага.

Автоматизация жизненного цикла

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

tour.addStep({
  id: 'auto-step',
  text: 'Эта подсказка появляется через 2 секунды',
  when: {
    show: () => console.log('Шаг автоматически показан'),
    hide: () => console.log('Шаг скрыт')
  }
});

setTimeout(() => {
  tour.show('auto-step');
}, 2000);
  • when позволяет привязать обработчики непосредственно к жизненному циклу шага.
  • Можно комбинировать события и действия кнопок для создания динамического и адаптивного тура.

Доступ к состоянию шага

Каждый шаг имеет методы и свойства для получения текущего состояния:

  • step.isOpen() — возвращает true, если шаг отображён.
  • step.el — DOM-элемент подсказки.
  • step.options — объект с настройками шага.

Пример проверки перед показом:

if (!step.isOpen()) {
  step.show();
}

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

Удаление шага

Шаг можно полностью удалить из тура:

tour.removeStep('intro');
  • После удаления шаг не может быть показан повторно.
  • Важно очищать шаги, если они создаются динамически, чтобы избежать утечек памяти.

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

Оглавление