Различия между complete и cancel

В библиотеке Shepherd.js для создания интерактивных пошаговых инструкций по интерфейсу веб-приложений ключевыми событиями являются complete и cancel. Несмотря на внешнюю схожесть — оба события прерывают или завершают текущий тур — их семантика и последствия для состояния приложения различны.

Событие complete

Событие complete вызывается, когда тур доходит до естественного завершения, то есть пользователь проходит все шаги до конца. Оно сигнализирует о нормальном окончании тура.

Ключевые особенности complete:

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

  • Используется для выполнения действий после успешного завершения:

    • Сохранение состояния пользователя (например, флаг tutorialCompleted = true в localStorage или базе данных).
    • Активация элементов интерфейса, которые были заблокированы до завершения тура.
    • Отправка аналитических событий о прохождении полного тура.

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

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

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в тур!',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

tour.on('complete', () => {
  console.log('Тур пройден полностью');
  localStorage.setItem('tutorialCompleted', 'true');
});

tour.start();

Событие cancel

Событие cancel возникает, когда пользователь прерывает тур до его естественного завершения. Это может быть сделано через крестик, кнопку отмены или вызов метода tour.cancel() программно.

Ключевые особенности cancel:

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

  • Используется для обработки отказа пользователя:

    • Можно показать уведомление о том, что тур был пропущен.
    • Сбросить временные изменения интерфейса, которые создавались для тура.
    • Логировать прерывание для аналитики.

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

tour.on('cancel', () => {
  console.log('Тур был прерван пользователем');
  alert('Вы прервали тур. Чтобы пройти его позже, нажмите "Начать тур"');
});

Различия на уровне логики приложения

Характеристика complete cancel
Причина вызова Тур пройден до конца Тур прерван до конца
Состояние пользователя Успешное завершение Неуспешное или прерванное завершение
Типичные действия Сохранение прогресса, активация функций Сообщение пользователю, очистка временных данных
Вызов через API Завершение последнего шага, tour.complete() Вызов tour.cancel(), кнопка отмены

Программное различие между complete и cancel

Методы tour.complete() и tour.cancel() могут вызываться программно, и это напрямую влияет на генерацию событий:

  • tour.complete() → генерирует событие complete
  • tour.cancel() → генерирует событие cancel

Примечательно, что вызов tour.hide() или закрытие шага вручную не инициирует ни одно из этих событий, если не завершён весь тур или не вызван cancel().

// Программное завершение
if (условиеУспешногоПрохождения) {
  tour.complete(); // вызовет complete
} else {
  tour.cancel();   // вызовет cancel
}

Рекомендации по использованию

  1. Разграничивать логику: действия после complete должны отличаться от действий после cancel. Не стоит использовать одно событие для обработки обоих случаев.
  2. Сохранять состояние пользователя: только complete должен фиксировать факт полного прохождения тура.
  3. Аналитика и статистика: события cancel полезны для изучения того, где пользователи теряют интерес или сталкиваются с проблемами в интерфейсе.
  4. Интерфейс: кнопки и элементы управления должны ясно различать завершение и отмену тура для пользователя.

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

Оглавление