react-hook-form

React Hook Form 最佳实践

React Hook Form 应用的全面性能优化指南。包含 8 个类别中的 41 条规则，并按影响程度排序，为表单开发、自动重构和代码生成提供指导。

适用场景

在以下情况下参考这些指南：

• 使用 React Hook Form 编写新表单
• 配置 useForm 选项（mode、defaultValues、验证）
• 使用 watch/useWatch 订阅表单值
• 集成受控 UI 组件（MUI、shadcn、Ant Design）
• 使用 useFieldArray 管理动态字段数组
• 检查表单是否存在性能问题

按优先级划分的规则类别

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

快速参考

1. 表单配置（严重）

• formcfg-validation-mode - 使用 onSubmit 模式以获得最佳性能
• formcfg-revalidate-mode - 将 reValidateMode 设为 onBlur，以提升提交后的性能
• formcfg-default-values - 始终提供 defaultValues 来初始化表单
• formcfg-async-default-values - 使用异步 defaultValues 获取服务端数据
• formcfg-should-unregister - 启用 shouldUnregister，提高动态表单的内存效率
• formcfg-useeffect-dependency - 避免在 useEffect 依赖项中使用 useForm 返回的对象

2. 字段订阅（严重）

• sub-usewatch-over-watch - 使用 useWatch 替代 watch，以隔离重新渲染
• sub-watch-specific-fields - 监听特定字段，而非整个表单
• sub-usewatch-with-getvalues - 将 useWatch 与 getValues 结合使用，确保时序安全
• sub-deep-subscription - 在组件树中靠近数据使用位置的深层进行订阅
• sub-avoid-watch-in-render - 避免在渲染过程中调用 watch() 来读取一次性数据
• sub-usewatch-default-value - 为 useWatch 提供 defaultValue，确保首次渲染时有值
• sub-useformcontext-sparingly - 在深层嵌套中谨慎使用 useFormContext

3. 受控组件（高）

• ctrl-usecontroller-isolation - 使用 useController 隔离重新渲染
• ctrl-avoid-double-registration - 避免使用 useController 时重复注册
• ctrl-controller-field-props - 为 UI 库正确连接 Controller 的 field 属性
• ctrl-single-usecontroller-per-component - 每个组件仅使用一个 useController
• ctrl-local-state-combination - 将本地状态与 useController 结合，用于仅供 UI 使用的状态

4. 验证模式（高）

• valid-resolver-caching - 在组件外定义 schema，以便缓存 resolver
• valid-dynamic-schema-factory - 使用 schema 工厂实现动态验证
• valid-error-message-strategy - 通过可选链或 lodash get 访问错误
• valid-inline-vs-resolver - 对复杂规则优先使用 resolver，而非内联验证
• valid-delay-error - 使用 delayError 对快速连续显示的错误进行防抖
• valid-native-validation - 对简单表单考虑使用原生验证

5. 字段数组（中高）

• array-use-field-id-as-key - 在 useFieldArray 映射中使用 field.id 作为 key
• array-complete-default-objects - 为字段数组操作提供完整的默认对象
• array-separate-crud-operations - 将连续的字段数组操作分开执行
• array-unique-fieldarray-per-name - 每个字段名只使用一个 useFieldArray 实例
• array-virtualization-formprovider - 在虚拟化字段数组中使用 FormProvider

6. 状态管理（中）

• formstate-destructure-formstate - 在渲染前解构 formState 属性
• formstate-useformstate-isolation - 使用 useFormState 订阅隔离的状态
• formstate-getfieldstate-for-single-field - 使用 getFieldState 访问单个字段的状态
• formstate-subscribe-to-specific-fields - 在 useFormState 中订阅特定字段名称
• formstate-avoid-isvalid-with-onsubmit - 在 onSubmit 模式下，避免使用 isValid 控制按钮状态

7. 集成模式（中）

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

8. 高级模式（低）

• adv-formprovider-memo - 使用 React.memo 包装 FormProvider 的子组件
• adv-devtools-performance - 在生产环境和性能测试期间禁用 DevTools
• adv-testing-wrapper - 使用 QueryClient 和 AuthProvider 创建测试包装器

使用方法

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

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

相关技能

• 关于使用 Zod resolver 进行架构验证，请参阅 zod 技能
• 关于 React 19 服务端操作，请参阅 react-19 技能
• 关于 UI/UX 表单设计，请参阅 frontend-design 技能

完整编译文档

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