vee-validate-skilld

vee-validate 4.15.1

适用于 Vue 3 的表单验证。以下事实来自准备好的源代码（dist/vee-validate.d.ts、dist/vee-validate.mjs、package.json）以及官方文档：https://vee-validate.logaretm.com/v4/。

环境

• 包 [email protected]（package.json:3）。需要 peer 依赖 vue ^3.4.26（package.json:42）。
• ESM + CJS，sideEffects: false，单一入口 vee-validate（package.json:11-26）。
• v4 仅支持 Vue 3。Vue 2 需要 vee-validate 2.x/3.x（README:69-72）。
• Schema 适配器位于独立包中：@vee-validate/yup、@vee-validate/zod、@vee-validate/valibot；全局规则在 @vee-validate/rules 中；消息在 @vee-validate/i18n 中。

两种 API 风格

组合式 API（新代码首选）。 useForm + defineField + handleSubmit：

<script setup>
import { useForm } from 'vee-validate';

function required(value) {
  return value ? true : 'This field is required';
}

const { defineField, handleSubmit, errors } = useForm({
  validationSchema: { field: required },
});

const [field, fieldProps] = defineField('field');

const onSubmit = handleSubmit(values => {
  console.log(values);
});
</script>

<template>
  <form @submit="onSubmit">
    <input v-model="field" v-bind="fieldProps" />
    <span>{{ errors.field }}</span>
    <button>Submit</button>
  </form>
</template>

来源：README:84-118，https://vee-validate.logaretm.com/v4/guide/composition-api/getting-started/

声明式组件。 使用作用域插槽的 Form + Field：

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

function required(value) {
  return value ? true : 'This field is required';
}

function onSubmit(values) {
  console.log(values);
}
</script>

<template>
  <Form v-slot="{ errors }" @submit="onSubmit">
    <Field name="field" :rules="required" />
    <span>{{ errors.field }}</span>
    <button>Submit</button>
  </Form>
</template>

来源：README:122-153，https://vee-validate.logaretm.com/v4/guide/components/handling-forms/

核心规则

• 使用 defineField(path, config?) 绑定字段。它会返回 [model, props]；使用 v-bind 展开 props，并使用 v-model 绑定 model（dist/vee-validate.d.ts:443，https://vee-validate.logaretm.com/v4/api/use-form/#definefield）。
• 不要直接写入 values.field；请使用 defineField 的 model、setFieldValue 或 useSetFieldValue。
• useFieldModel、defineComponentBinds 和 defineInputBinds 已弃用，应改用 defineField（dist/vee-validate.d.ts:444-459）。
• 仅在用户交互后显示错误，例如使用 v-if="errorMessage && meta.touched"，以避免验证体验过于激进（https://vee-validate.logaretm.com/v4/guide/best-practices/#avoiding-aggressive-validation）。
• 使用 TypeScript 时，请使用对应的 @vee-validate/* 包中的 toTypedSchema 包装 yup/zod/valibot schema。直接传入原始 schema 而不进行包装会报错："No such validator 'VVTypedSchema' exists"（https://vee-validate.logaretm.com/v4/guide/composition-api/typed-schema/，https://github.com/logaretm/vee-validate/discussions/4819）。
• 自定义组件中的 useField 默认不能同步其 v-model（syncVModel 默认为 false，这是 4.10.0 中的破坏性变更）。可为每个字段设置 syncVModel: true，或设置模型 prop 名称字符串以启用同步（dist/vee-validate.mjs:1862）。
• 字段名称是路径。点号用于嵌套对象，[0] 用于数组索引；将名称括在方括号中，例如 [user.name]，即可将点号视为字面字符（https://vee-validate.logaretm.com/v4/guide/composition-api/nested-objects-and-arrays/）。
• errors 对象始终是扁平的：请使用字段名称中的确切路径字符串进行引用，包括方括号（https://vee-validate.logaretm.com/v4/guide/composition-api/nested-objects-and-arrays/）。
• 使用 useFieldArray 返回的 fields 遍历数组字段，并将 v-for 的 key 设为 entry.key（稳定 ID，绝不能使用索引）（https://vee-validate.logaretm.com/v4/guide/composition-api/nested-objects-and-arrays/）。
• 将响应式字段名称作为 getter 传入（useField(() => props.name)），以便 vee-validate 跟踪名称变化（https://vee-validate.logaretm.com/v4/guide/composition-api/caveats/）。
• 保持 schema 非响应式：在 ref/reactive 外声明，或使用 markRaw 包装，以避免深层响应式带来的开销（https://vee-validate.logaretm.com/v4/guide/best-practices/#reactive-schemas）。
• handleSubmit.withControlled(cb) 只提交通过 useField/defineField 注册的字段（dist/vee-validate.d.ts:430-432）；请注意，类型化 schema 仍可能包含所有初始值（未解决的问题：https://github.com/logaretm/vee-validate/issues/4960）。

验证模式

全局默认值：validateOnBlur: true、validateOnChange: true、validateOnInput: false、validateOnModelUpdate: true、bails: true。使用 configure() 进行全局更改；请注意，这四个触发标志仅适用于 <Field> 组件，不适用于 useField（https://vee-validate.logaretm.com/v4/api/configuration/）。若要仅在提交时验证，请在 defineField 配置中或全局禁用输入、变更和失焦触发（https://github.com/logaretm/vee-validate/discussions/4903）。

参考资料

• 组合式 API：useForm、defineField、useField、useFieldArray、状态与设置器组合函数、表单上下文。
• 组件：Form、Field、FieldArray、ErrorMessage 的 props、插槽、渲染、v-model 规则。
• 验证：验证器函数、对象架构、类型化架构、全局规则、i18n、独立的 validate 工具函数。
• API 概览：所有运行时导出和重要类型，引用自 dist/vee-validate.d.ts。
• 版本变更：从 4.9.0 到 4.15.1 的 API 新增、破坏性变更和弃用内容。
• 注意事项：组合式 API 的注意事项、嵌套路径规则、数组字段、已知未解决问题。