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

Shepherd.js предоставляет гибкий механизм создания интерактивных пошаговых туров по веб-приложению. Для полноценного пользовательского опыта важно обеспечить корректную работу туров в контексте динамических форм и элементов, управляемых сторонними библиотеками валидации, такими как Formik, Yup, jQuery Validation, VeeValidate и другие.

Синхронизация состояния шагов с валидацией

При работе с формами ключевым моментом является согласование состояния туров и состояния формы. Shepherd.js позволяет использовать коллбеки beforeShowPromise, beforeShow, show и hide для контроля момента отображения шага. Это позволяет:

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

Пример интеграции с Yup:

import Shepherd from 'shepherd.js';
import * as Yup from 'yup';

const schema = Yup.object().shape({
  name: Yup.string().required('Введите имя'),
  email: Yup.string().email('Неверный формат').required('Введите email'),
});

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

tour.addStep({
  id: 'step-name',
  text: 'Введите ваше имя',
  attachTo: { element: '#name', on: 'bottom' },
  buttons: [
    {
      text: 'Далее',
      action: async () => {
        const name = document.querySelector('#name').value;
        try {
          await schema.validateAt('name', { name });
          tour.next();
        } catch (err) {
          alert(err.message);
        }
      }
    }
  ]
});

Ключевой момент: использование async/await позволяет дождаться результата валидации перед переходом к следующему шагу, предотвращая нарушение логики формы.

Обработка динамически создаваемых полей

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

Использовать beforeShowPromise для ожидания появления элемента:

tour.addStep({
  id: 'step-dynamic',
  text: 'Заполните поле, которое появится позже',
  attachTo: { element: '#dynamic-field', on: 'top' },
  beforeShowPromise: () => {
    return new Promise(resolve => {
      const checkExist = setInterval(() => {
        if (document.querySelector('#dynamic-field')) {
          clearInterval(checkExist);
          resolve();
        }
      }, 100);
    });
  },
});

Совмещать с валидацией, чтобы пользователь не мог пропустить обязательные поля.

Связывание Shepherd.js с событиями библиотек валидации

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

Formik: можно использовать validateForm и isValid из контекста формы для управления шагами Shepherd.
jQuery Validation: коллбек submitHandler позволяет автоматически переходить к следующему шагу после успешной валидации.

Пример с jQuery Validation:

$('#myForm').validate({
  rules: {
    name: 'required',
    email: { required: true, email: true }
  },
  submitHandler: function(form) {
    tour.next();
  }
});

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

Валидация на каждом шаге тура

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

tour.addStep({
  id: 'step-email',
  text: 'Введите email',
  attachTo: { element: '#email', on: 'right' },
  buttons: [
    {
      text: 'Далее',
      action: () => {
        const emailField = document.querySelector('#email');
        if (!emailField.value.match(/^\S+@\S+\.\S+$/)) {
          alert('Email введен некорректно');
        } else {
          tour.next();
        }
      }
    }
  ]
});

Такой подход обеспечивает пошаговую валидацию и предотвращает прогрессирование тура с некорректными данными.

Поддержка кастомной визуальной индикации ошибок

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

Добавление класса error к полю формы.
Использование tour.getCurrentStep().updateStepOptions({ text: '...' }) для динамического изменения текста шага.
Интеграция с библиотеками типа Tippy.js для отображения ошибок рядом с элементом.

Пример обновления шага с сообщением об ошибке:

const step = tour.getCurrentStep();
step.updateStepOptions({ text: 'Введите корректный email' });

Совместимость с асинхронной валидацией

Если используется серверная проверка (например, уникальность email), необходимо обрабатывать асинхронные запросы перед переходом к следующему шагу:

action: async () => {
  const email = document.querySelector('#email').value;
  const response = await fetch(`/validate-email?email=${email}`);
  const data = await response.json();
  if (!data.valid) {
    alert('Email уже занят');
  } else {
    tour.next();
  }
}

Использование async/await и обработка ошибок предотвращает преждевременный прогресс шага.