when

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

Синтаксис и структура when

Опция when является объектом, где ключи соответствуют событиям, а значения — функции-обработчики. Пример базовой структуры:

const step = tour.addStep({
  id: 'example-step',
  text: 'Это пример шага с обработчиками событий',
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт'),
    complete: () => console.log('Шаг завершён')
  }
});

Ключевые моменты:

  • События — это строки, соответствующие событиям жизненного цикла шага. Основные события:

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

  • Обработчики — функции, выполняющиеся в момент наступления события. Они могут быть как синхронными, так и асинхронными.

Привязка событий на уровне тура

Помимо событий отдельных шагов, when можно использовать для управления событиями всего тура:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    when: {
      show: () => console.log('Показан шаг любого шага по умолчанию'),
      hide: () => console.log('Скрыт шаг любого шага по умолчанию')
    }
  }
});

Особенности:

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

Асинхронные операции в when

Функции, заданные в when, могут выполнять асинхронные операции, включая fetch, setTimeout, или вызовы библиотек для анимации:

tour.addStep({
  id: 'async-step',
  text: 'Шаг с асинхронной операцией',
  when: {
    show: async () => {
      await fetch('/api/data');
      console.log('Данные загружены перед показом шага');
    }
  }
});
  • Асинхронный обработчик позволяет подготовить контент, выполнить проверку состояния элементов или подгрузку данных до того, как шаг станет видимым.
  • Shepherd автоматически не блокирует интерфейс, поэтому важно использовать промисы или async/await для управления последовательностью действий.

Использование when для динамического изменения шага

Можно динамически изменять свойства шага во время событий:

tour.addStep({
  id: 'dynamic-step',
  text: 'Текст изменится при показе',
  when: {
    show: (event) => {
      const step = event.step;
      step.updateStepOptions({
        text: 'Новый текст после события show'
      });
    }
  }
});
  • event.step даёт доступ к объекту шага, что позволяет изменять текст, кнопки, позицию или любые другие свойства.
  • Позволяет создавать адаптивные подсказки, которые реагируют на действия пользователя.

Обработка пользовательских событий

Помимо стандартных событий, можно создавать собственные события через вызов метода trigger:

tour.on('customEvent', () => console.log('Пользовательское событие вызвано'));
tour.trigger('customEvent');
  • Связь с when остаётся аналогичной: шаги могут подписываться на события тура через when или использовать глобальный tour.on.
  • Это открывает возможности интеграции с внешними библиотеками, например, для анимаций или изменения состояния страницы.

Практические рекомендации

  1. Разделение логики: Использовать when для действий, которые связаны только с отображением и скрытием шагов. Логику туров лучше держать на уровне tour.on.
  2. Минимизировать тяжелые операции: События show и hide вызываются часто, поэтому блокирующие операции могут ухудшить UX.
  3. Асинхронность: Всегда использовать async/await для операций, которые зависят от данных с сервера или от сложных вычислений.
  4. Повторное использование: Создавать общие функции для однотипных событий нескольких шагов, чтобы уменьшить дублирование кода.

Примеры сложного сценария

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    when: {
      show: () => console.log('Пошаговый тур начинается'),
    }
  }
});

tour.addStep({
  id: 'step-1',
  text: 'Первый шаг',
  when: {
    show: () => console.log('Показывается первый шаг'),
    complete: () => console.log('Первый шаг завершён')
  }
});

tour.addStep({
  id: 'step-2',
  text: 'Второй шаг с динамическим контентом',
  when: {
    show: (event) => {
      event.step.updateStepOptions({
        text: `Второй шаг. Текущее время: ${new Date().toLocaleTimeString()}`
      });
    }
  }
});

tour.start();

В этом примере демонстрируются:

  • События на уровне тура и на уровне конкретного шага.
  • Динамическое изменение текста при показе шага.
  • Использование when для отслеживания завершения шагов.

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

Оглавление