Отображение сообщений об ошибках

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

В Shepherd.js ошибки могут возникать на нескольких уровнях: при инициализации тура, при добавлении шагов, при переходе между шагами или при взаимодействии с элементами страницы, к которым привязаны шаги. Для управления этими ситуациями библиотека предоставляет гибкие механизмы обработки и кастомизации сообщений об ошибках.

Настройка обработчика ошибок при инициализации тура

При создании объекта тура (Shepherd.Tour) можно использовать глобальные обработчики ошибок для всех шагов. Например:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  },
  useModalOverlay: true
});

tour.on('error', function(error) {
  console.error('Ошибка тура:', error);
  showCustomErrorMessage(error.message);
});

Здесь:

  • tour.on('error', callback) — глобальный обработчик ошибок, который срабатывает при возникновении любой ошибки, связанной с туром.
  • showCustomErrorMessage — кастомная функция для отображения сообщения пользователю.

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

Валидация элементов перед показом шага

Частая причина ошибок — отсутствие элемента на странице, к которому привязан шаг. Shepherd.js не выводит встроенное уведомление, но позволяет проверять доступность элементов:

const step = {
  id: 'step-1',
  text: 'Нажмите здесь, чтобы продолжить',
  attachTo: {
    element: '#button-next',
    on: 'bottom'
  },
  beforeShowPromise: function() {
    return new Promise((resolve, reject) => {
      const el = document.querySelector('#button-next');
      if (el) {
        resolve();
      } else {
        reject(new Error('Элемент "#button-next" не найден на странице'));
      }
    });
  }
};

tour.addStep(step);
  • beforeShowPromise — ключевой механизм для перехвата потенциальной ошибки до отображения шага.
  • При вызове reject можно передавать объект Error с детальным сообщением.
  • Это предотвращает некорректное отображение шага и позволяет своевременно уведомить пользователя или разработчика.

Кастомные всплывающие сообщения об ошибках

Для более дружественного UX сообщения об ошибках можно отображать внутри модальных оверлеев Shepherd.js или через внешние UI-компоненты.

Пример встроенного сообщения через шаг тура:

tour.addStep({
  id: 'error-step',
  text: () => {
    const error = tour.getCurrentStep().errorMessage;
    return error || 'Произошла непредвиденная ошибка';
  },
  buttons: [
    {
      text: 'Закрыть',
      action: tour.cancel
    }
  ],
  beforeShow: function() {
    this.errorMessage = 'Не удалось найти нужный элемент';
  }
});
  • Использование функции для text позволяет динамически подставлять сообщение об ошибке.
  • Свойство errorMessage шага хранит текст ошибки и может быть использовано для логирования или UI.

Интеграция с внешними логами и уведомлениями

Shepherd.js хорошо сочетается с внешними системами логирования ошибок:

tour.on('error', function(error) {
  fetch('/log-error', {
    method: 'POST',
    body: JSON.stringify({ message: error.message, stack: error.stack }),
    headers: { 'Content-Type': 'application/json' }
  });
});
  • Отправка ошибок на сервер позволяет отслеживать проблемы на разных устройствах и браузерах.
  • Можно настроить разные уровни критичности и отображать пользователю только необходимые уведомления.

Обработка ошибок при навигации между шагами

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

tour.on('show', function(step) {
  try {
    const el = document.querySelector(step.options.attachTo.element);
    if (!el) throw new Error(`Элемент "${step.options.attachTo.element}" отсутствует`);
  } catch (error) {
    console.warn(error.message);
    displayErrorOverlay(error.message);
    tour.cancel();
  }
});
  • Использование try/catch внутри событийного обработчика обеспечивает безопасную проверку элементов.
  • Вызов tour.cancel() корректно завершает тур при критической ошибке.

Советы по структуре сообщений об ошибках

  1. Ясность — текст должен четко объяснять, что произошло.
  2. Локализация — если приложение поддерживает несколько языков, сообщения об ошибках тоже должны быть локализованы.
  3. Контекст — указывайте шаг или элемент, на котором возникла ошибка.
  4. Действия — по возможности предлагайте пользователю пути исправления (например, кнопку «Пропустить шаг» или «Повторить попытку»).

Практическая реализация

Можно объединить все элементы в универсальный обработчик ошибок:

function handleTourError(error, stepId) {
  console.error(`Ошибка на шаге ${stepId}:`, error);
  const overlay = document.createElement('div');
  overlay.className = 'error-overlay';
  overlay.textContent = error.message;
  document.body.appendChild(overlay);
  setTimeout(() => overlay.remove(), 5000);
}

tour.on('error', (error) => handleTourError(error, tour.getCurrentStep()?.id));
  • Такой подход обеспечивает единый стиль сообщений и позволяет быстро адаптировать обработку ошибок под требования проекта.
  • Использование временных оверлеев повышает UX без прерывания работы приложения.

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

Оглавление