show

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага',
  attachTo: { element: '.my-element', on: 'bottom' }
});

tour.getById('example-step').show();

В этом примере шаг с идентификатором example-step отображается сразу при вызове метода show. Это важно для динамических сценариев, когда шаги могут запускаться не по порядку, а в зависимости от действий пользователя.

Особенности поведения метода show

  1. Автоматическое управление видимостью: Метод show скрывает предыдущий активный шаг перед показом нового. Это предотвращает наложение всплывающих окон.

  2. Обработка привязки к элементу (attachTo): Если шаг привязан к DOM-элементу, show автоматически вычисляет положение тултипа относительно указанного направления (top, bottom, left, right). При отсутствии элемента в DOM шаг не будет показан, и в консоль будет выведено предупреждение.

  3. События жизненного цикла: Метод show инициирует стандартные события Shepherd:

    • before-show — вызывается перед отображением шага, позволяет изменять содержимое или стили.
    • show — вызывается после того, как шаг стал видимым.
    • cancel и complete остаются привязанными к завершению тура, но show напрямую их не вызывает.
const step = tour.addStep({
  id: 'lifecycle-step',
  text: 'Следите за событиями жизненного цикла'
});

step.on('before-show', () => console.log('Перед показом шага'));
step.on('show', () => console.log('Шаг показан'));

step.show();

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

Метод show не принимает аргументы, однако поведение шага можно контролировать через опции шага при его создании:

  • scrollTo — если true, страница автоматически прокручивается до элемента, к которому привязан шаг.
  • highlightClass — CSS-класс для выделения элемента во время шага.
  • buttons — массив кнопок с действиями (next, back, cancel) для текущего шага.
tour.addStep({
  id: 'scroll-step',
  text: 'Этот шаг прокручивает страницу к элементу',
  attachTo: { element: '#target', on: 'top' },
  scrollTo: true,
  buttons: [
    { text: 'Назад', action: tour.back },
    { text: 'Далее', action: tour.next }
  ]
}).show();

Взаимодействие с другими методами тура

  • next и back: Методы навигации по шагам корректно обновляют текущий шаг, даже если последний был показан через show.
  • cancel и complete: Метод show не завершает тур, поэтому для закрытия всех шагов необходимо вызвать эти методы отдельно.
  • hide: Метод show автоматически скрывает предыдущий активный шаг, но для управления видимостью вне последовательности можно использовать hide() вручную.
tour.getById('first-step').show();
// Позже скрываем шаг без перехода к следующему
tour.getById('first-step').hide();

Управление анимацией и позиционированием

Shepherd.js использует библиотеку Popper.js для точного позиционирования тултипов. Метод show учитывает:

  • текущую видимость и положение элемента в viewport
  • динамическое изменение размеров окна или контента
  • возможное смещение с помощью опции offset
tour.addStep({
  id: 'offset-step',
  text: 'Показ с кастомным смещением',
  attachTo: { element: '.button', on: 'right', offset: { x: 10, y: 20 } }
}).show();

Применение в динамических интерфейсах

Метод show особенно полезен в сложных интерфейсах с элементами, которые загружаются асинхронно:

async function showStepAfterLoad() {
  await waitForElement('.dynamic-element');
  tour.getById('dynamic-step').show();
}

Это гарантирует, что шаг не будет показан до того, как элемент появится на странице, предотвращая ошибки позиционирования и пустые тултипы.

Практическая оптимизация

  • Использовать show совместно с before-show для динамического обновления текста или состояния кнопок.
  • Проверять наличие элемента перед вызовом show, особенно в SPA и ленивой загрузке контента.
  • Минимизировать количество вызовов show для ускорения отклика интерфейса, так как каждый вызов пересчитывает позицию и прокрутку страницы.

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

Оглавление