Метод cancel

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

Синтаксис и базовое использование

tour.cancel();
  • tour — экземпляр Shepherd.Tour.
  • Метод не принимает аргументов.
  • При вызове все активные шаги немедленно закрываются, а тур считается завершённым.

Пример:

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

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

tour.start();

В этом примере кнопка на шаге напрямую вызывает tour.cancel, что обеспечивает мгновенное завершение тура без необходимости перехода к следующему шагу.

Отличие cancel от других методов управления туром

Метод Основное действие Отличие
next() Переход к следующему шагу Тур продолжается
back() Возврат к предыдущему шагу Тур продолжается
complete() Завершение тура после выполнения всех шагов Выполняются колбеки onComplete
cancel() Немедленное завершение тура Прерывает тур в любой момент, выполняются колбеки onCancel

Ключевой момент: cancel() не выполняет переход к следующему шагу и не активирует шаги, оставшиеся в очереди.

Колбеки при отмене тура

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

Пример:

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

tour.on('cancel', () => {
  console.log('Тур был отменён пользователем.');
  // Можно сбросить состояния элементов интерфейса
});

tour.addStep({
  id: 'step1',
  text: 'Это первый шаг.'
});

tour.start();

// Пример отмены через код
setTimeout(() => {
  tour.cancel();
}, 5000);

В данном примере тур автоматически отменяется через 5 секунд, а колбек выводит сообщение в консоль.

Использование cancel для динамических интерфейсов

В сложных интерфейсах, где шаги тура могут динамически добавляться или удаляться, метод cancel гарантирует:

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

Пример динамического удаления тура при навигации между страницами SPA:

window.addEventListener('beforeunload', () => {
  if (tour) {
    tour.cancel();
  }
});

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

  • Использовать cancel в обработчиках событий, которые могут прервать тур (например, закрытие модального окна или переход на другую страницу).
  • Подключать колбек onCancel для восстановления интерфейса в исходное состояние.
  • Не использовать cancel для перехода между шагами — для этого предназначены next() и back().
  • В сочетании с методами addStep и start обеспечивает полную контроль над поведением интерактивного тура.

Важные особенности

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

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

Оглавление