useForm

根据 tinyval Schema 创建表单状态。

签名

function useForm<S extends Schema, V extends object>(schema: S, options: FormOptions<V>): Form<V, Infer<S>>

选项

选项	类型	默认值	说明
initial	V	—	字段初始值。必填。form.values 的类型由它决定
mode	'blur' | 'input' | 'submit'	'blur'	何时显示字段错误 —— 见 错误
debounce	number	300	输入时执行异步检查前的延迟，毫秒
focusOnError	boolean	true	提交失败时聚焦第一个有错误的字段（按 name 属性）
extractErrors	(error) => errors	422 响应	如何从 handleSubmit 的异常中提取字段错误。默认支持通过 axios 和 ofetch 返回的 Laravel 422，以及 tinyval 的 ValidationError
id	string	useId()	字段 id 的前缀。在 Vue 3.5+ 中默认使用 useId() —— 在 SSR 下保持一致
messages、labels、maxDepth			与 validate 相同：该表单的语言和字段名称

返回值

一个响应式对象。请整体使用它（form.errors.email），不要解构 —— 否则会失去响应性。

表单会提供给嵌套组件：在其中 useField('email')、useFieldArray('items')、useFormContext() 以及 TvField 等组件无需显式传入表单即可使用。

字段	说明
values	用于 v-model 的字段值
errors	当前应显示的错误（取决于 mode）以及服务端错误：{ email: '...', 'items.0.title': '...' }
allErrors	所有当前错误，包括尚未显示的
valid	表单有效且没有服务端错误
dirty	值与初始值不同
changes	只包含修改过的字段 —— 例如用于 PATCH，见 编辑
touched	用户已离开过的字段：{ email: true }
validating	正在进行异步检查
submitting	正在提交（handleSubmit）
submitted	表单至少提交过一次 —— 之后显示所有错误
submitCount	尝试提交的次数
submitSucceeded	最近一次提交是否成功
data	校验后的数据（经过 trim、coerce…）或 undefined

方法	说明
touch(path)	将字段标记为已访问 —— 通常在 @blur 时调用。touch('items') 会标记所有嵌套字段
handleSubmit(onValid, onInvalid?)	@submit 处理函数：阻止页面提交，校验表单，并用校验后的数据调用 onValid(data)，或调用 onInvalid(errors)
validate(paths?)	校验表单并显示所有错误。传入路径时只校验这些字段，见 分步表单。返回 Promise<boolean>
isDirty(path)	字段是否被修改
setValue(path, value)、setValues(values)	设置单个字段 / 多个字段的值
setErrors(errors)	显示服务端错误：{ email: '...' } 或 Laravel 格式 { email: ['...'] }
setFieldError(path, message?)	单个字段的错误；字段修改后消失。不传文本则移除
clearErrors(path?)	隐藏字段或整个表单的错误，直到下次离开字段 / 提交
setTouched(path, value?)	将字段标记或取消标记为已访问
resetField(path, value?)	恢复字段的初始值；传入 value 时设置新的初始值
validateField(path)	校验单个字段并显示其错误
reset(values?)	恢复初始（或新的）值，并清除错误、touched、submitted。新值会成为 dirty 的基准
bind(path)	modelValue、onUpdate:modelValue 和 onBlur —— 用于 UI 组件库

另请参阅

• useField、useFieldArray
• useDraft、useLeaveGuard