React Hook Form API 详细中文文档
date
Oct 24, 2025
slug
react-hook-form-api-detailed-chinese-documentation
status
Published
tags
React Hook Form
summary
本文列举了在 React Hook Form 中常用的钩子函数，并附有示例
type
Post
React Hook Form 全钩子核心属性与方法完整指南
一、useForm：表单核心控制钩子
1. 核心配置属性
属性名 | 类型 | 说明 | 默认值 |
mode | 'onChange'/'onBlur'/'onSubmit'/'onTouched'/'all' | 验证触发时机 | 'onSubmit' |
defaultValues | object/(() => Promise<object>) | 表单默认值 | undefined |
values | object | 响应式覆盖默认值 | undefined |
resolver | Resolver | 集成外部验证库 | undefined |
resetOptions | { keepDirtyValues?: boolean; keepErrors?: boolean } | 重置表单时的状态保留配置 | { keepDirtyValues: false, keepErrors: false } |
shouldFocusError | boolean | 验证失败时自动聚焦到第一个错误字段 | false |
shouldUnregister | boolean | 组件卸载时是否取消字段注册 | false |
context | object | 传递全局上下文数据 | undefined |
2. 核心返回方法 / 属性
方法 / 属性名 | 类型 | 说明 |
register | (name: string, options?: RegisterOptions) => { onChange; onBlur; ref; name } | 注册原生输入字段 |
handleSubmit | (onSuccess: (data: T) => void, onError?: (errors: FieldErrors) => void) => (e: FormEvent) => void | 表单提交处理器 |
watch | (name?: string | string[], defaultValue?: any) => any | 监听字段值变化 |
setValue | (name: string, value: any, options?: { shouldValidate?: boolean; shouldDirty?: boolean }) => void | 手动设置字段值 |
reset | (values?: Partial<T>, options?: ResetOptions) => void | 重置表单 |
setError | (name: string, error: { message?: string; type?: string }, options?: { shouldFocus?: boolean }) => void | 手动设置字段错误 |
clearErrors | (name?: string | string[]) => void | 清除字段错误 |
getValues | (name?: string | string[], options?: { getDirtyValues?: boolean }) => any | 获取字段值 |
getFieldState | (name: string) => { isDirty: boolean; isTouched: boolean; value: any; error: FieldError } | 获取单个字段的详细状态 |
trigger | (name?: string | string[], options?: { shouldFocus?: boolean }) => Promise<boolean> | 手动触发字段验证 |
formState | FormState | 表单全局状态对象 |
control | Control | 表单控制实例 |
3. register 方法详细配置
RegisterOptions 配置属性：
属性名 | 类型 | 说明 |
required | string | boolean | 必填验证 |
min | number | { value: number, message: string } | 最小值验证 |
max | number | { value: number, message: string } | 最大值验证 |
minLength | number | { value: number, message: string } | 最小长度验证 |
maxLength | number | { value: number, message: string } | 最大长度验证 |
pattern | RegExp | { value: RegExp, message: string } | 正则表达式验证 |
validate | function | object | 自定义验证函数 |
valueAsNumber | boolean | 将输入值转换为数字 |
valueAsDate | boolean | 将输入值转换为日期 |
disabled | boolean | 禁用字段 |
onChange | function | 自定义 onChange 处理函数 |
onBlur | function | 自定义 onBlur 处理函数 |
deps | string[] | 依赖字段 |
register 返回对象：
属性名 | 类型 | 说明 |
name | string | 字段名称 |
ref | React.Ref | 输入元素的引用 |
onChange | function | 变更处理函数 |
onBlur | function | 失焦处理函数 |
min | string | number | 最小值 |
max | string | number | 最大值 |
maxLength | number | 最大长度 |
minLength | number | 最小长度 |
pattern | string | 正则模式 |
required | boolean | 是否必填 |
disabled | boolean | 是否禁用 |
4. formState 详细属性
属性名 | 类型 | 说明 |
errors | object | 所有字段的错误信息 |
isDirty | boolean | 表单是否有字段被修改 |
dirtyFields | object | 被修改的字段对象 |
touchedFields | object | 被触摸过的字段对象 |
isSubmitted | boolean | 表单是否已提交过 |
isSubmitting | boolean | 表单是否正在提交 |
submitCount | number | 表单提交次数 |
isValid | boolean | 表单是否通过验证 |
isValidating | boolean | 表单是否正在验证 |
5. 实战案例：基础登录表单
二、useController：独立字段控制钩子
1. 核心配置属性
属性名 | 类型 | 说明 | 默认值 |
name | string | 字段名称（必填） | - |
control | Control | 从 useForm 获取的 control 实例 | - |
rules | RegisterOptions | 验证规则（同 register 的验证规则） | undefined |
defaultValue | any | 字段默认值 | undefined |
2. 核心返回方法 / 属性
属性名 | 类型 | 说明 |
field | { onChange, onBlur, value, ref, name } | 字段控制对象 |
fieldState | { invalid, isTouched, isDirty, error } | 字段状态 |
formState | FormState | 表单全局状态 |
3. 实战案例：自定义输入组件
三、useWatch：响应式字段监听钩子
1. 核心配置属性
属性名 | 类型 | 说明 | 默认值 |
name | string | string[] | 要监听的字段名或字段名数组 | - |
control | Control | 从 useForm 获取的 control 实例 | - |
defaultValue | any | 字段默认值 | undefined |
2. 核心返回方法 / 属性
返回指定字段的当前值。
3. 实战案例：监听字段值
四、useFormState：表单状态监听钩子
1. 核心配置属性
属性名 | 类型 | 说明 | 默认值 |
control | Control | 从 useForm 获取的 control 实例 | - |
name | string | string[] | 要监听的字段名 | - |
2. 核心返回方法 / 属性
返回表单状态对象，包含以下属性：
属性名 | 类型 | 说明 |
errors | object | 表单错误对象 |
isDirty | boolean | 表单是否有字段被修改 |
dirtyFields | object | 被修改的字段对象 |
touchedFields | object | 被触摸的字段对象 |
isValid | boolean | 表单是否通过验证 |
isSubmitting | boolean | 表单是否正在提交 |
3. 实战案例：监听表单错误状态
五、useFieldArray：动态字段数组管理钩子
1. 核心配置属性
属性名 | 类型 | 说明 | 默认值 |
control | Control | 从 useForm 获取的 control 实例 | - |
name | string | 字段数组名称（必填） | - |
rules | RegisterOptions | 验证规则 | undefined |
keyName | string | 自定义每个字段项的 key 名 | "id" |
2. 核心返回方法 / 属性
属性名 / 方法名 | 类型 | 说明 |
fields | array | 字段数组 |
append | (value: any, options?: { shouldFocus?: boolean }) => void | 在数组末尾添加新项 |
prepend | (value: any, options?: { shouldFocus?: boolean }) => void | 在数组开头添加新项 |
remove | (index?: number | number[]) => void | 删除指定索引的项 |
insert | (index: number, value: any, options?: { shouldFocus?: boolean }) => void | 在指定索引处插入新项 |
swap | (indexA: number, indexB: number) => void | 交换两项位置 |
move | (from: number, to: number) => void | 移动项从 from 到 to |
update | (index: number, value: any) => void | 更新指定索引的项 |
replace | (value: any[]) => void | 替换整个数组 |
3. 实战案例：动态用户列表
这份完整指南涵盖了 React Hook Form 的所有核心钩子及其属性方法，帮助您全面掌握表单开发的各类场景解决方案。