VeeValidate v4 终极指南：精通 Vue 3 组合式 API 表单验证

你好，Vue 开发者们！你是否曾被复杂的表单状态管理和繁琐的验证逻辑搞得头昏脑胀？如果是，那么 vee-validate 就是你的救星！🎉

vee-validate 是一个为 Vue.js 量身打造的表-单验证库。它能帮你处理表单验证中的各种棘手问题，如值跟踪、错误收集、表单提交等，让你可以专注于业务逻辑，而不是重复造轮子。

特别是 v4 版本，它完全拥抱 Vue 3 的组合式 API (Composition API)，提供了前所未有的灵活性和强大的功能。准备好让你的表单开发体验焕然一新了吗？让我们开始吧！

核心优势

• ✅ Vue 3 优先：完全基于组合式 API 设计，与 Vue 3 的开发模式完美契合。
• ✅ 轻量且模块化：只引入你需要的功能，有效控制打包体积。
• ✅ 功能强大：支持同步/异步规则、字段级/表单级验证、本地化 (i18n) 等。
• ✅ 非侵入式：无需将你的表单组件包裹在特定的结构中，易于与现有代码或 UI 库集成。
• ✅ TypeScript 支持：提供一流的 TypeScript 类型定义，带来更安全的开发体验。

---

安装

首先，将 vee-validate 和它的伙伴 @vee-validate/rules（包含了大量预设的验证规则）添加到你的项目中：

npm install vee-validate @vee-validate/rules --save

---

快速上手：组合式 API 的魔力

vee-validate 的精髓在于它的组合式函数：useForm 和 useField。

• useForm: 创建一个表单上下文，用于管理整个表单的状态、验证和提交。
• useField: 创建一个与表单字段绑定的响应式引用，并为其附加验证规则。

定义全局验证规则

为了方便使用，我们可以在应用的入口文件（如 main.js）中全局配置验证规则。

// main.js
import { defineRule } from "vee-validate";
import * as rules from "@vee-validate/rules";
import { configure } from "vee-validate";
import { localize } from "@vee-validate/i18n";
import zh_CN from "@vee-validate/i18n/dist/locale/zh_CN.json";

// 批量定义所有 @vee-validate/rules 提供的规则
Object.keys(rules).forEach((rule) => {
  defineRule(rule, rules[rule]);
});

// 配置 VeeValidate
configure({
  generateMessage: localize("zh_CN", zh_CN), // 加载中文语言包
  validateOnInput: true, // 输入时即时验证
});

小提示：@vee-validate/i18n 提供了多语言支持，让你的错误提示更友好。

创建你的第一个验证表单

现在，让我们创建一个登录表单组件 LoginForm.vue。

<template>
  <div class="min-h-screen bg-gray-50 flex items-center justify-center p-4">
    <div class="w-full max-w-md">
      <form
        @submit="onSubmit"
        class="bg-white shadow-lg rounded-lg p-8 space-y-6"
      >
        <h2 class="text-2xl font-bold text-gray-800 text-center">用户登录</h2>

        <div>
          <input
            v-model="email"
            type="email"
            placeholder="请输入邮箱"
            class="w-full px-4 py-3 border rounded-lg focus:ring-2 focus:ring-blue-500 outline-none"
            :class="errors.email ? 'border-red-500' : 'border-gray-300'"
          />
          <span v-if="errors.email" class="text-red-500 text-sm block mt-1">{{
            errors.email
          }}</span>
        </div>

        <div>
          <input
            v-model="password"
            type="password"
            placeholder="请输入密码"
            class="w-full px-4 py-3 border rounded-lg focus:ring-2 focus:ring-blue-500 outline-none"
            :class="errors.password ? 'border-red-500' : 'border-gray-300'"
          />
          <span
            v-if="errors.password"
            class="text-red-500 text-sm block mt-1"
            >{{ errors.password }}</span
          >
        </div>

        <div>
          <input
            v-model="confirmPassword"
            type="password"
            placeholder="请再次输入密码"
            class="w-full px-4 py-3 border rounded-lg focus:ring-2 focus:ring-blue-500 outline-none"
            :class="
              errors.confirmPassword ? 'border-red-500' : 'border-gray-300'
            "
          />
          <span
            v-if="errors.confirmPassword"
            class="text-red-500 text-sm block mt-1"
            >{{ errors.confirmPassword }}</span
          >
        </div>

        <button
          type="submit"
          class="w-full bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white font-semibold py-3 px-6 rounded-lg"
        >
          {{ isSubmitting ? "登录中..." : "登录" }}
        </button>
      </form>
    </div>
  </div>
</template>

<script setup>
import { useForm, useField } from "vee-validate";

const { defineField, errors, handleSubmit, isValid, isSubmitting } = useForm({
  validationSchema: {
    email: (v) =>
      !v
        ? "此字段是必填项"
        : !/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(v)
        ? "请输入有效的邮箱地址"
        : true,
    password: (v) =>
      !v ? "此字段是必填项" : v.length < 8 ? "密码至少需要8个字符" : true,
    confirmPassword: (v, { form }) =>
      !v
        ? "此字段是必填项"
        : v !== form.password
        ? "两次输入的密码不一致"
        : true,
  },
});

const [email] = defineField("email");
const [password] = defineField("password");
const [confirmPassword] = defineField("confirmPassword");

const onSubmit = handleSubmit(async (values) => {
  console.log("表单数据:", values);
  // 模拟异步请求
  await new Promise((resolve) => setTimeout(resolve, 2000));
  alert("登录成功！");
});
</script>

在这个例子中，我们做了几件重要的事情：

1. 定义 Schema：使用一个简单的对象来定义每个字段的验证规则，规则之间用 | 分隔。
2. 创建表单：useForm 接收 validationSchema 并返回了我们需要的一切：
   • handleSubmit: 一个包裹了我们提交逻辑的函数，它会先执行验证。
   • errors: 一个包含当前所有字段错误的响应式对象。
   • meta: 一个包含表单元信息的对象，如 meta.valid 表示表单是否有效。
   • isSubmitting: 一个布尔值 ref，在 handleSubmit 的异步操作期间为 true。
3. 绑定字段：useField('fieldName') 为每个字段创建了一个双向绑定的 value，并将其连接到表单上下文中。
4. 处理提交：handleSubmit 接收两个函数作为参数，第一个是验证成功时的回调，第二个是验证失败时的回调。

---

✨ 组件化方案：<Form> 和 <Field>

除了组合式 API，vee-validate 也提供了 <Form> 和 <Field> 组件，让你可以用更声明式的方式构建表单。这在与第三方 UI 组件库（如 Element Plus, Naive UI）集成时特别有用。

<template>
  <Form
    @submit="onSubmit"
    :validation-schema="schema"
    v-slot="{ errors, isSubmitting }"
  >
    <div class="form-group">
      <label>邮箱</label>
      <Field
        name="email"
        type="email"
        class="form-control"
        :class="{ 'is-invalid': errors.email }"
      />
      <ErrorMessage name="email" class="error-message" />
    </div>

    <div class="form-group">
      <label>密码</label>
      <Field
        name="password"
        type="password"
        class="form-control"
        :class="{ 'is-invalid': errors.password }"
      />
      <ErrorMessage name="password" class="error-message" />
    </div>

    <button type="submit" :disabled="isSubmitting">提交</button>
  </Form>
</template>

<script setup>
import { Form, Field, ErrorMessage } from "vee-validate";

const schema = {
  email: "required|email",
  password: "required|min:8",
};

function onSubmit(values) {
  console.log("提交成功:", values);
}
</script>

• <Form> 组件负责处理表单的提交和状态管理。
• <Field> 组件会自动处理 v-model 和验证状态。
• <ErrorMessage> 组件则专门用于显示指定字段的错误信息。

---

总结

vee-validate v4 为 Vue 3 带来了现代化、高效率的表单验证体验。无论是使用灵活的组合式 API 还是声明式的组件，它都能帮你优雅地处理复杂的表单逻辑。

现在，你已经掌握了 vee-validate 的基本用法。赶快在你的下一个项目里尝试一下，告别繁琐的表单验证代码，享受编码的乐趣吧！