名称: react-hook-form 描述: 使用 useForm、useWatch、useController 和 useFieldArray 进行客户端表单验证的 React Hook Form 性能优化。此技能应在使用 React Hook Form 库构建客户端受控表单时使用。此技能不涵盖 React 19 服务器操作、useActionState 或服务器端表单处理（请使用 react-19 技能）。
React Hook Form 最佳实践
全面的 React Hook Form 应用程序性能优化指南。包含 8 个类别的 41 条规则，按影响优先级排序，以指导表单开发、自动化重构和代码生成。
何时应用
在以下情况下参考这些指南：
- 使用 React Hook Form 编写新表单
- 配置 useForm 选项（模式、默认值、验证）
- 使用 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- 正确连接 Controller 字段属性以适配 UI 库ctrl-single-usecontroller-per-component- 每个组件使用单个 useControllerctrl-local-state-combination- 将本地状态与 useController 结合以处理仅 UI 状态
4. 验证模式（高）
valid-resolver-caching- 在组件外部定义解析器架构以缓存valid-dynamic-schema-factory- 使用架构工厂进行动态验证valid-error-message-strategy- 通过可选链或 lodash get 访问错误信息valid-inline-vs-resolver- 对于复杂规则，优先使用解析器而非内联验证valid-delay-error- 使用 delayError 来防抖快速错误显示valid-native-validation- 考虑简单表单的原生验证
5. 字段数组（中高）
array-use-field-id-as-key- 在 useFieldArray 映射中使用 field.id 作为键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 Selectinteg-mui-controller-pattern- 使用 Controller 适配 Material-UI 组件integ-value-transform- 在 Controller 级别转换值以进行类型强制转换
8. 高级模式（低）
adv-formprovider-memo- 使用 React.memo 包装 FormProvider 子组件adv-devtools-performance- 在生产环境和性能测试期间禁用 DevToolsadv-testing-wrapper- 创建包含 QueryClient 和 AuthProvider 的测试包装器
如何使用
阅读单独的参考文件以获取详细解释和代码示例：
相关技能
- 对于使用 Zod 解析器进行架构验证，请参阅
zod技能 - 对于 React 19 服务器操作，请参阅
react-19技能 - 对于 UI/UX 表单设计，请参阅
frontend-design技能
完整编译文档
有关所有规则扩展的完整指南：AGENTS.md