vee-validate-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

logaretm/vee-validate

vee-validate

logaretm/vee-validate

vee-validate

Version: 4.15.1 (Jun 2025) Deps: @vue/devtools-api@^7.5.2, type-fest@^4.8.3 Tags: prev: 1.0.0-beta.10 (Nov 2016), next-edge: 4.5.0-alpha.2 (Jul 2021), edge: 4.5.0-alpha.6 (Aug 2021), next: 4.5.8 (Jan 2022), alpha: 4.12.0-alpha.1 (Nov 2023), beta: 5.0.0-beta.0 (Aug 2025), latest: 4.15.1 (Jun 2025)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • Releases — changelog, breaking changes, new APIs

版本: 4.15.1（2025年6月） 依赖: @vue/devtools-api@^7.5.2, type-fest@^4.8.3 标签: prev: 1.0.0-beta.10（2016年11月）, next-edge: 4.5.0-alpha.2（2021年7月）, edge: 4.5.0-alpha.6（2021年8月）, next: 4.5.8（2022年1月）, alpha: 4.12.0-alpha.1（2023年11月）, beta: 5.0.0-beta.0（2025年8月）, latest: 4.15.1（2025年6月）

参考资料: 文档 — API参考、指南 • GitHub问题 — 漏洞、解决方案、边缘情况 • 版本发布 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes for vee-validate v4.x — prioritize these over legacy patterns.

BREAKING:
```
v-model
```
support disabled by default in v4.10.0 for performance; enable via
```
configure({ validateOnModelUpdate: true })
```
or per-field
```
syncVModel
```
source
NEW:
```
defineField
```
introduced in v4.9.0 — replaces
```
defineComponentBinds
```
and
```
defineInputBinds
```
for cleaner Composition API integration source
DEPRECATED: Reactive initial values deprecated in v4.12.0; use non-reactive objects or getters to prevent unintended sync source
NEW:
```
useFormContext
```
exposed in v4.14.0 for accessing form state in deeply nested components without manual injection source
NEW:
```
setValue
```
exposed on
```
Field
```
instances and slot props in v4.13.0 for manual value updates source
NEW: Composition setter hooks (
```
useSetFieldValue
```
,
```
useSetFormValues
```
,
```
useSetFormErrors
```
) added in v4.11.0 for external state management source
NEW:
```
handleBlur
```
accepts
```
shouldValidate
```
parameter since v4.10.0 to control validation triggers on blur events source
NEW:
```
syncVModel
```
accepts target model prop name as a string in v4.10.0 for custom model support source
NEW:
```
isValidating
```
state added to
```
useForm
```
and form slot props in v4.9.3 to track async validation status source
NEW:
```
move(oldIdx, newIdx)
```
added to
```
FieldArray
```
in v4.6.0 for reordering items within array fields source
NEW: Specialized state hooks (
```
useIsFieldDirty
```
,
```
useIsFormValid
```
,
```
useFieldValue
```
) added in v4.1.0 for granular state access source
DEPRECATED:
```
handleInput
```
deprecated in v4.4.0; use
```
handleChange
```
for both input and change events source
NEW:
```
label
```
support in
```
defineField
```
added in v4.12.0 for consistent error message generation source
NEW:
```
ResetFormOpts
```
with
```
force
```
flag added to
```
useResetForm
```
in v4.13.0 to clear values without merging source

Also changed:

defineComponentBinds

deprecated ·

defineInputBinds

deprecated ·

useFieldModel

deprecated ·

unsetValueOnUnmount

config added ·

keepValuesOnUnmount

reactivity improved ·

useForm

validate returns object ·

useResetForm

hook added ·

nested field meta querying

new v4.12.3

本节记录vee-validate v4.x版本特有的API变更 — 优先遵循这些内容而非旧有模式。

破坏性变更：v4.10.0中默认禁用
```
v-model
```
支持以提升性能；可通过
```
configure({ validateOnModelUpdate: true })
```
或为单个字段设置
```
syncVModel
```
来启用来源
新增特性：v4.9.0中引入
```
defineField
```
— 替代
```
defineComponentBinds
```
和
```
defineInputBinds
```
，实现更简洁的Composition API集成来源
已弃用：v4.12.0中弃用响应式初始值；使用非响应式对象或getter避免意外同步来源
新增特性：v4.14.0中暴露
```
useFormContext
```
，无需手动注入即可在深层嵌套组件中访问表单状态来源
新增特性：v4.13.0中在
```
Field
```
实例和插槽props上暴露
```
setValue
```
，用于手动更新值来源
新增特性：v4.11.0中添加组合式设置器钩子（
```
useSetFieldValue
```
,
```
useSetFormValues
```
,
```
useSetFormErrors
```
），用于外部状态管理来源
新增特性：自v4.10.0起，
```
handleBlur
```
接受
```
shouldValidate
```
参数，用于控制失焦事件触发的验证行为来源
新增特性：v4.10.0中
```
syncVModel
```
接受目标model属性名称作为字符串，支持自定义model 来源
新增特性：v4.9.3中为
```
useForm
```
和表单插槽props添加
```
isValidating
```
状态，用于跟踪异步验证状态来源
新增特性：v4.6.0中为
```
FieldArray
```
添加
```
move(oldIdx, newIdx)
```
，用于重新排序数组字段内的项来源
新增特性：v4.1.0中添加专用状态钩子（
```
useIsFieldDirty
```
,
```
useIsFormValid
```
,
```
useFieldValue
```
），用于细粒度状态访问来源
已弃用：v4.4.0中弃用
```
handleInput
```
；使用
```
handleChange
```
处理输入和变更事件来源
新增特性：v4.12.0中为
```
defineField
```
添加
```
label
```
支持，用于生成一致的错误信息来源
新增特性：v4.13.0中为
```
useResetForm
```
添加带
```
force
```
标志的
```
ResetFormOpts
```
，无需合并即可清除值来源

其他变更：

defineComponentBinds

已弃用 ·

defineInputBinds

已弃用 ·

useFieldModel

已弃用 · 添加

unsetValueOnUnmount

配置 · 改进

keepValuesOnUnmount

响应式 ·

useForm

的validate方法返回对象 · 添加

useResetForm

钩子 · 新增v4.12.3的嵌套字段元数据查询

Best Practices

最佳实践

Prefer
```
defineField()
```
for binding components and inputs — returns a
```
v-model
```
ref and a props object for clean, non-deprecated binding source

const [email, emailProps] = defineField('email', {
  validateOnBlur: true,
  props: state => ({ 'aria-invalid': !!state.errors.length })
});

Display errors conditionally using
```
meta.touched
```
— prevents "aggressive" validation where error messages appear before the user interacts with the field source
Use
```
toTypedSchema()
```
for comprehensive TypeScript safety — wraps Yup, Zod, or Valibot schemas to differentiate between input (UI) and output (submitted) types source

import { toTypedSchema } from '@vee-validate/zod';
import * as z from 'zod';

const { values } = useForm({
  validationSchema: toTypedSchema(z.object({ email: z.string().email() }))
});

Mark validation schemas as non-reactive — wrap schemas in
```
markRaw
```
or declare them outside of
```
ref
```
/
```
reactive
```
to avoid unnecessary deep reactivity overhead source
Tree-shake schema validator imports — only import the specific functions you need (e.g.,
```
import { string } from 'yup'
```
) to keep bundle sizes to a minimum source
Pass reactive field names as getters in
```
useField
```
— use a function (e.g.,
```
() => props.name
```
) to ensure vee-validate tracks name changes in dynamic forms source
Enable
```
keepValuesOnUnmount
```
for multi-step forms — preserves field state when components are hidden via
```
v-if
```
or tab switching source

const { values } = useForm({
  keepValuesOnUnmount: true
});

Use
```
field.key
```
for stable iteration in
```
v-for
```
—
```
useFieldArray
```
provides unique identifiers that persist through array operations, unlike indices source
Escape field names with
```
[]
```
to disable automatic nesting — wrap names (e.g.,
```
[user.name]
```
) to treat dots as literal characters rather than object paths source
Filter submission values with
```
handleSubmit.withControlled()
```
— ensures only fields explicitly registered via
```
useField
```
or
```
defineField
```
are included in the payload source

优先使用
```
defineField()
```
绑定组件和输入框 — 返回
```
v-model
```
引用和props对象，实现简洁且未被弃用的绑定方式来源

const [email, emailProps] = defineField('email', {
  validateOnBlur: true,
  props: state => ({ 'aria-invalid': !!state.errors.length })
});

使用
```
meta.touched
```
条件显示错误信息 — 避免在用户与字段交互前就显示错误信息的"激进"验证方式来源
使用
```
toTypedSchema()
```
实现全面的TypeScript类型安全 — 包装Yup、Zod或Valibot schema，区分输入（UI）和输出（提交）类型来源

import { toTypedSchema } from '@vee-validate/zod';
import * as z from 'zod';

const { values } = useForm({
  validationSchema: toTypedSchema(z.object({ email: z.string().email() }))
});

将验证schema标记为非响应式 — 使用
```
markRaw
```
包装schema或在
```
ref
```
/
```
reactive
```
外部声明，避免不必要的深度响应式开销来源
按需导入schema验证器函数 — 仅导入所需的特定函数（如
```
import { string } from 'yup'
```
），最小化包体积来源
在
```
useField
```
中以getter形式传递响应式字段名称 — 使用函数（如
```
() => props.name
```
）确保vee-validate跟踪动态表单中的名称变更来源
为多步骤表单启用
```
keepValuesOnUnmount
```
— 当组件通过
```
v-if
```
或标签切换隐藏时保留字段状态来源

const { values } = useForm({
  keepValuesOnUnmount: true
});

在
```
v-for
```
中使用
```
field.key
```
实现稳定迭代 —
```
useFieldArray
```
提供的唯一标识符在数组操作中保持不变，不同于索引来源
使用
```
[]
```
转义字段名称以禁用自动嵌套 — 包裹名称（如
```
[user.name]
```
），将点视为字面量字符而非对象路径来源
使用
```
handleSubmit.withControlled()
```
过滤提交值 — 确保仅包含通过
```
useField
```
或
```
defineField
```
显式注册的字段来源

vee-validate-skilld

Original

Translation

logaretm/vee-validate
`vee-validate`

logaretm/vee-validate
`vee-validate`

API Changes

API变更

Best Practices

最佳实践