Метод show для перехода к шагу

Метод show является ключевым инструментом управления пошаговыми инструкциями в библиотеке Shepherd.js. Он позволяет программно переключаться на определённый шаг тура, независимо от текущего положения пользователя в последовательности шагов. Это особенно полезно для динамических интерфейсов, где требуется управлять навигацией по шагам не только через кнопки «Next» и «Back», но и через внешние события или действия пользователя.

Синтаксис метода

tour.show([stepId])
  • stepId (необязательный) — идентификатор шага, к которому нужно перейти. Если параметр не указан, show вызовет отображение текущего активного шага или первого шага, если тур только начинается.

Принцип работы

Метод show выполняет следующие действия:

  1. Определяет целевой шаг: если указан stepId, библиотека ищет шаг с соответствующим идентификатором среди зарегистрированных шагов тура. Если не найден, метод игнорирует вызов.
  2. Активирует шаг, вызывая его методы beforeShowPromise, attach, и show.
  3. Обновляет состояние тура, включая текущий активный шаг (currentStep).
  4. Управляет видимостью подсказок, обеспечивая плавный переход между шагами без наложения предыдущих подсказок.

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: {
      enabled: true
    },
    classes: 'shepherd-theme-arrows',
    scrollTo: { beh * avior: 'smooth', block: 'center' }
  }
});

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

tour.addStep({
  id: 'step-2',
  text: 'Это второй шаг тура',
  attachTo: { element: '#element2', on: 'top' },
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ]
});

tour.start();

// Переход к конкретному шагу по событию
document.querySelector('#goto-step-2').addEventListener('click', () => {
  tour.show('step-2');
});

В этом примере метод show позволяет мгновенно перейти ко второму шагу при нажатии на внешнюю кнопку, минуя первый шаг.

Особенности использования

  • Переход к следующему или предыдущему шагу: хотя для навигации обычно используют next и back, show даёт полный контроль над порядком шагов, что полезно для нелинейных туров.
  • События шагов: при вызове show будут триггерены все события шага (show, hide, complete, cancel), что позволяет встроить сложную логику отображения подсказок.
  • Работа с динамическими элементами: если элемент, к которому нужно прикрепить шаг, динамически создаётся, важно убедиться, что он существует в DOM к моменту вызова show, иначе шаг не прикрепится.
  • Асинхронные шаги: можно использовать beforeShowPromise для выполнения асинхронных действий перед отображением шага, например, загрузки данных или анимации интерфейса.

Советы по организации кода

  1. Уникальные идентификаторы: каждый шаг должен иметь уникальный id. Это гарантирует корректную работу метода show при переходе к конкретному шагу.
  2. Централизация логики навигации: если тур включает сложные сценарии, лучше управлять переходами через show, а не через последовательность кнопок, чтобы избежать дублирования кода.
  3. Проверка существования шага: перед вызовом show(stepId) можно использовать tour.getById(stepId) для проверки наличия шага. Это предотвращает ошибки при динамическом создании шагов.

Пример асинхронного шага с show

tour.addStep({
  id: 'step-async',
  text: 'Загрузка данных...',
  attachTo: { element: '#dynamic-element', on: 'right' },
  beforeShowPromise: () => fetch('/api/data')
    .then(response => response.json())
    .then(data => {
      document.querySelector('#dynamic-element').textContent = data.message;
    })
});

tour.show('step-async');

Метод show гарантирует, что шаг отобразится только после завершения beforeShowPromise, обеспечивая синхронизацию с внешними процессами.

Итог

Метод show является мощным инструментом Shepherd.js для гибкого управления пошаговыми турами. Он позволяет:

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

Использование show делает туры более интерактивными, настраиваемыми и адаптивными к любым сценариям работы приложения.

Оглавление