before-show

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

Подключение обработчика before-show

Каждый шаг в Shepherd.js создается через метод tour.addStep(), который принимает объект с конфигурацией шага. Внутри этого объекта можно определить событие before-show с помощью ключа beforeShow, куда передается функция-обработчик:

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

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага с before-show',
  attachTo: { element: '.example-element', on: 'bottom' },
  beforeShow: () => {
    console.log('Шаг готовится к отображению');
    document.querySelector('.example-element').classList.add('highlight');
  }
});

tour.start();

В этом примере перед отображением шага на элемент .example-element добавляется CSS-класс highlight. Функция beforeShow выполняется один раз перед показом шага.

Использование before-show для динамического контента

before-show особенно полезно, когда текст, кнопки или другие элементы шага должны формироваться динамически. Например:

tour.addStep({
  id: 'dynamic-step',
  text: () => {
    const username = document.querySelector('#username').value;
    return `Привет, ${username}! Добро пожаловать в тур.`;
  },
  attachTo: { element: '#welcome', on: 'right' },
  beforeShow: () => {
    const welcomeBox = document.querySelector('#welcome');
    welcomeBox.style.backgroundColor = '#f0f8ff';
  }
});

В данном случае текст шага генерируется динамически с учетом текущего значения поля #username, а также изменяется фон элемента перед отображением шага.

Асинхронные операции в before-show

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

tour.addStep({
  id: 'async-step',
  text: 'Загрузка данных...',
  attachTo: { element: '#data-section', on: 'top' },
  beforeShow: async () => {
    const data = await fetch('/api/info').then(res => res.json());
    return data.message;
  }
});

Если функция beforeShow возвращает текст, Shepherd автоматически обновит содержимое шага перед его показом.

Комбинация с другими событиями

before-show работает в связке с другими событиями Shepherd.js, такими как show, before-hide и hide. Основная логика использования:

  • before-show — подготовка шага до его отображения.
  • show — действия сразу после того, как шаг стал видимым.
  • before-hide — подготовка к скрытию шага.
  • hide — действия после скрытия шага.

Пример комбинированного использования:

tour.addStep({
  id: 'combo-step',
  text: 'Следующий шаг будет показан через 1 секунду',
  attachTo: { element: '#combo', on: 'bottom' },
  beforeShow: () => new Promise(resolve => setTimeout(resolve, 1000)),
  show: () => console.log('Шаг показан!'),
});

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

Управление позиционированием и состоянием элементов

Событие before-show позволяет корректировать позицию шага, особенно если элементы динамически изменяют размер или положение:

tour.addStep({
  id: 'position-step',
  text: 'Проверяем позицию перед показом',
  attachTo: { element: '#dynamic-element', on: 'left' },
  beforeShow: () => {
    const el = document.querySelector('#dynamic-element');
    if (el.offsetWidth < 100) {
      el.style.width = '150px';
    }
  }
});

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

Практические советы по использованию before-show

  • Использовать для добавления классов или анимаций к целевым элементам.
  • Генерировать динамический текст и кнопки в зависимости от состояния приложения.
  • Реализовывать асинхронные операции, например загрузку данных или ожидание готовности DOM.
  • Проверять состояние целевых элементов и корректировать позиционирование перед показом шага.
  • Минимизировать время выполнения beforeShow, чтобы не задерживать отображение тура без необходимости.

Ограничения и особенности

  • before-show вызывается каждый раз, когда шаг собирается отображаться. Если шаг повторно показывается, функция сработает снова.
  • Возвращаемое значение функции используется только для обновления текста, другие параметры шага необходимо изменять через методы шагов (step.updateStepOptions, step.setText и др.).
  • Асинхронные операции могут замедлить показ шага, поэтому важно контролировать время выполнения.

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

Оглавление