Метод once для одноразовой подписки

Метод once в Shepherd.js предоставляет возможность подписки на события, которые должны срабатывать только один раз за жизненный цикл шага или тура. Это особенно полезно для обработки событий, которые не должны повторяться при повторных активациях шага или при навигации по туру.

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

step.once(event, callback);
tour.once(event, callback);

  • event — строка, название события, на которое необходимо подписаться. Shepherd поддерживает множество событий, таких как:

    • show — срабатывает при показе шага;
    • hide — срабатывает при скрытии шага;
    • complete — срабатывает при завершении тура;
    • cancel — срабатывает при отмене тура;
    • active — срабатывает при активации шага.

  • callback — функция, которая будет вызвана при возникновении события. После первого срабатывания подписка автоматически удаляется.

Отличие once от on

Метод on подписывает обработчик на событие, который может срабатывать многократно:

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

В отличие от on, once гарантирует, что обработчик будет вызван только один раз, независимо от того, сколько раз событие происходит:

step.once('show', () => {
  console.log('Это сообщение выведется только один раз');
});

Такое поведение предотвращает повторное выполнение логики, которая должна запускаться только при первой активации, например: начальная настройка интерфейса, запуск анимации, или запись статистики.

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

Одноразовая обработка показа шага
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в тур',
  attachTo: { element: '.header', on: 'bottom' }
});

tour.steps[0].once('show', () => {
  console.log('Шаг intro показан впервые');
});

tour.start();

В этом примере обработчик сработает только при первом показе шага intro, и при повторном возврате к этому шагу console.log уже не выполнится.

Одноразовое завершение тура
tour.once('complete', () => {
  alert('Тур завершён впервые');
});

Такой подход особенно полезен для действий, которые должны выполняться только при первом завершении тура, например, запись информации в базу данных или отправка аналитики.

Поддерживаемые события для once

Метод once работает с теми же событиями, что и on:

  • Тур: start, complete, cancel, active, inactive, show, hide
  • Шаг: show, hide, complete, cancel, active, inactive

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

Особенности и нюансы

  1. Автоматическое снятие подписки: после первого срабатывания обработчик удаляется автоматически. Не требуется ручного удаления.
  2. Совместимость с другими обработчиками: once не мешает существующим обработчикам, добавленным через on.
  3. Асинхронные действия: если внутри callback выполняются асинхронные операции, важно учитывать, что они будут запущены только один раз, даже если шаг будет показан повторно.
  4. Использование с динамическими шагами: если шаги создаются динамически, once можно назначать после добавления шага к туру, но до его показа.

Практические сценарии

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

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

Оглавление