react-hook-form

社区总结的 React Hook Form 最佳实践

React Hook Form 应用的全面性能优化指南。包含 7 个类别中的 35 条规则，每条规则都指出了一种默认情况下容易出错的决策。已针对 react-hook-form 7.82.0 验证。

适用场景

在以下场景中参考这些指南：

• 使用 React Hook Form 编写新表单
• 配置 useForm 选项（mode、defaultValues、验证）
• 使用 watch / useWatch / subscribe 订阅表单值
• 集成受控 UI 组件（MUI、shadcn、Ant Design）
• 使用 useFieldArray 管理动态字段数组
• 处理异步提交、服务端错误和提交生命周期状态
• 检查表单是否存在性能问题

不适用场景

• React 19 Server Actions / useActionState —— 请改用 react-19 技能
• 深度嵌套且完全类型安全的表单 —— 对于包含复杂嵌套架构的表单，TanStack Form 可能更合适；本技能假定你已选择 RHF
• 单输入或简单表单 —— 使用非受控的 <form> + FormData 通常比引入任何库更简单

按优先级划分的规则类别

优先级	类别	影响	前缀
1	表单配置	CRITICAL	formcfg-
2	字段订阅	CRITICAL	sub-
3	受控组件	HIGH	ctrl-
4	验证模式	HIGH	valid-
5	状态管理	MEDIUM-HIGH	formstate-
6	字段数组	MEDIUM-HIGH	array-
7	集成模式	MEDIUM	integ-

快速参考

1. 表单配置（CRITICAL）

• formcfg-default-values - 始终为表单初始化提供 defaultValues
• formcfg-useeffect-dependency - 依赖 formState 的各个切片，而非 formState 本身
• formcfg-validation-mode - 除默认的 onSubmit 外，使用任何 mode 都应说明理由
• formcfg-revalidate-mode - 除非验证开销很大，否则保留默认的 reValidateMode
• formcfg-should-unregister - 除非必须从提交数据中移除隐藏字段，否则保持 shouldUnregister 关闭
• formcfg-transformed-values-generic - 当 resolver 会转换值时，传入 useForm 的第三个泛型参数
• formcfg-async-default-values - 使用异步 defaultValues 获取服务端数据
• formcfg-disabled-prop - 使用 HTML disabled 属性实现视觉禁用，不要使用 register 的 disabled 选项
• formcfg-values-prop - 使用 values 属性让表单与服务端数据保持同步

2. 字段订阅（CRITICAL）

• sub-avoid-watch-in-render - 对于一次性读取，避免在渲染中调用 watch()
• sub-memo-cannot-beat-context - 在 FormProvider 下，React.memo 无法阻止由 Context 驱动的重新渲染
• sub-subscribe-outside-react - 使用 subscribe() 在 React 生命周期之外响应表单更改
• sub-render-prop-components - 使用 render-prop 组件，无需子组件即可隔离重新渲染
• sub-useformcontext-sparingly - 在深层嵌套场景中谨慎使用 useFormContext
• sub-usewatch-over-watch - 使用 useWatch 而非 watch 来隔离重新渲染
• sub-watch-specific-fields - 监听特定字段，而非整个表单

3. 受控组件（HIGH）

• ctrl-usecontroller-isolation - 将受控输入隔离在专用子组件中
• ctrl-controller-field-props - 正确连接 UI 库的 Controller 字段属性

4. 验证模式（HIGH）

• valid-resolver-caching - 在渲染路径之外构建一次验证架构
• valid-valueasnumber-empty-nan - 处理空输入时 valueAsNumber 产生的 NaN 值
• valid-server-errors - 通过 setError('root.serverError', ...) 显示服务端错误
• valid-delay-error - 使用 delayError 对快速出现的错误提示进行防抖

5. 状态管理（中高）

• formstate-avoid-isvalid-with-onsubmit - 在 onSubmit 模式下，避免使用 isValid 控制按钮状态
• formstate-destructure-formstate - 在渲染期间读取所依赖的每个 formState 属性
• formstate-reset-default-values - 保存成功后，使用 resetDefaultValues 重新设定默认值
• formstate-handlesubmit-oninvalid - 使用 handleSubmit 的第二个参数处理被拒绝的提交
• formstate-useformstate-isolation - 使用 useFormState 隔离状态订阅
• formstate-async-submit-lifecycle - 将异步提交处理程序包装在 try/catch 中，并在 isSubmitSuccessful 时重置

6. 字段数组（中高）

• array-separate-crud-operations - 分开执行连续的字段数组操作
• array-use-field-id-as-key - 在 useFieldArray 映射中将 field.id 用作 Key
• array-unique-fieldarray-per-name - 每个字段名称只使用一个 useFieldArray 实例
• array-disabled-silently-noops - useFieldArray 的 disabled 选项会让所有变更操作静默无效

7. 集成模式（中）

• integ-value-transform - 在 Controller 层转换值以进行类型强制转换
• integ-shadcn-form-import - 确认 shadcn Form 组件的导入来源
• integ-shadcn-select-wiring - 使用 onValueChange 而非展开属性来连接 shadcn Select

使用方法

阅读单独的参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板
• 参考文件：references/{prefix}-{slug}.md

相关技能

• 使用 Zod resolver 进行架构验证，请参阅 zod 技能
• 使用 React 19 Server Actions，请参阅 react-19 技能
• 进行 UI/UX 表单设计，请参阅 frontend-design 技能

完整编译文档

包含所有展开规则的完整指南：AGENTS.md