Валидация форм

В Naive UI управление формами строится вокруг компонента n-form, который обеспечивает структурированное представление данных, поддержку правил валидации и интеграцию с различными элементами ввода. Валидация форм — ключевой инструмент для обеспечения корректного ввода данных пользователем и предотвращения ошибок на фронтенде.

Компонент n-form

n-form выступает контейнером для всех полей формы. Основные свойства:

  • model — объект, содержащий значения всех полей. Связь осуществляется через двустороннее связывание (v-model), что позволяет автоматически отслеживать изменения.
  • rules — объект с правилами валидации для каждого поля. Формат правил аналогичен объекту, где ключ — имя поля, значение — массив правил.
  • label-width — ширина меток полей, задаваемая для выравнивания визуального представления.
  • size — размер элементов формы (small, medium, large), что влияет на отступы и шрифты.

Пример структуры n-form:

<n-form :model="formData" :rules="rules" ref="formRef">
  <n-form-item label="Имя" path="name">
    <n-input v-model:value="formData.name" placeholder="Введите имя" />
  </n-form-item>
  <n-form-item label="Возраст" path="age">
    <n-input-number v-model:value="formData.age" :min="0" :max="120" />
  </n-form-item>
  <n-button @click="submitForm">Отправить</n-button>
</n-form>

Определение правил валидации

Правила в Naive UI задаются как массив объектов. Каждый объект может содержать следующие поля:

  • required — обязательность поля (true или false).
  • type — тип данных (string, number, email, array и т.д.).
  • min / max — ограничения длины или числового значения.
  • pattern — регулярное выражение для проверки формата.
  • message — текст ошибки, отображаемый пользователю.
  • trigger — событие, при котором происходит валидация (blur, input, change).

Пример определения правил:

const rules = {
  name: [
    { required: true, message: 'Имя обязательно', trigger: 'blur' },
    { min: 2, max: 30, message: 'Длина имени от 2 до 30 символов', trigger: 'blur' }
  ],
  age: [
    { type: 'number', required: true, message: 'Возраст обязателен', trigger: 'blur' },
    { min: 0, max: 120, message: 'Возраст должен быть от 0 до 120', trigger: 'blur' }
  ]
}

Валидация отдельных полей

Для проверки конкретного поля можно использовать метод validateField объекта формы:

const formRef = ref(null);

function validateName() {
  formRef.value.validateField('name')
    .then(() => console.log('Имя корректно'))
    .catch(error => console.error('Ошибка в имени:', error));
}

Метод возвращает промис: при успешной валидации он выполняет then, при ошибке — catch.

Полная валидация формы

Метод validate позволяет проверять все поля формы одновременно:

function submitForm() {
  formRef.value.validate()
    .then(() => {
      console.log('Форма успешно заполнена', formData);
    })
    .catch(errors => {
      console.error('Ошибки в форме', errors);
    });
}

Результат ошибки — объект, где ключи соответствуют полям, а значения — массив сообщений об ошибках.

Асинхронные правила валидации

Naive UI поддерживает асинхронные проверки, например, проверку уникальности email через API. Для этого функция правила возвращает промис:

const rules = {
  email: [
    {
      required: true,
      message: 'Email обязателен',
      trigger: 'blur'
    },
    {
      validator: async (rule, value) => {
        const isUnique = await checkEmailUnique(value); // асинхронная проверка
        if (!isUnique) throw new Error('Email уже используется');
      },
      trigger: 'blur'
    }
  ]
};

Динамическая валидация

Правила можно менять на лету, что полезно для форм с зависимыми полями:

function toggleRules(isRequired) {
  rules.age[0].required = isRequired;
}

После изменения правил рекомендуется вызывать resetValidation, чтобы очистить старые ошибки:

formRef.value.resetValidation();

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

Naive UI автоматически распознаёт большинство компонентов ввода (n-input, n-input-number, n-select, n-checkbox) и связывает их с формой через v-model:value. Это упрощает синхронизацию данных и позволяет сосредоточиться на логике валидации.

Особенности:

  • n-select — валидация проверяет выбранное значение.
  • n-checkbox / n-radio — поддерживают массив или одиночное значение.
  • n-date-picker — валидация проверяет формат даты и диапазоны (min-date, max-date).

Пользовательские сообщения и стили ошибок

Ошибки отображаются автоматически в компоненте n-form-item, но можно настроить:

  • show-message — управляет показом сообщения.
  • feedback — позволяет отображать кастомное сообщение вне стандартного блока ошибки.

Пример с кастомным отображением:

<n-form-item label="Email" path="email" :feedback="customFeedback">
  <n-input v-model:value="formData.email" placeholder="Введите email" />
</n-form-item>

Сброс формы и очистка ошибок

Для сброса значений полей используется reset:

formRef.value.reset();

Для очистки только сообщений об ошибках:

formRef.value.resetValidation();

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

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

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

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

Оглавление