react-hook-form

React Hook Form 最佳实践

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

适用场景

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

• 使用 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 - 根据用户体验和验证成本选择验证模式
• formcfg-revalidate-mode - 谨慎选择提交后的重新验证模式
• formcfg-default-values - 始终提供 defaultValues 来初始化表单
• formcfg-async-default-values - 使用异步 defaultValues 加载服务端数据
• formcfg-should-unregister - 根据提交语义选择 shouldUnregister
• formcfg-useeffect-dependency - 避免将 useForm 返回对象用作 useEffect 依赖项

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 - 在有助于隔离时拆分受控字段
• ctrl-local-state-combination - 将本地状态与 useController 结合，用于仅 UI 状态

4. 验证模式（高）

• valid-resolver-caching - 在组件外定义 schema，以启用 resolver 缓存
• valid-dynamic-schema-factory - 使用 schema 工厂实现动态验证
• valid-error-message-strategy - 使用 ErrorMessage（7.88+）或可选链渲染字段错误
• valid-trigger-should-touch - 触发验证时将字段标记为已触碰（7.87+）
• valid-inline-vs-resolver - 复杂规则优先使用 resolver，而不是内联验证
• valid-delay-error - 使用 delayError 对快速出现的错误提示进行防抖
• valid-native-validation - 对简单表单考虑使用原生验证
• valid-form-level-validate - 使用表单级 validate 选项验证跨字段规则（7.72+）

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 和 getErrors 读取单个字段
• formstate-subscribe-to-specific-fields - 在 useFormState 中订阅特定字段名称
• formstate-avoid-isvalid-with-onsubmit - 使提交门控与验证模式保持一致

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 层转换值以进行类型强制转换
• integ-typed-submit-server-action - 使用带类型的 handleSubmit 结果或 Server Action 提交（7.84+）

8. 高级模式（低）

• adv-formprovider-memo - 仅在性能分析后对 FormProvider 子组件进行记忆化
• adv-devtools-performance - 在生产环境和性能测试期间禁用 DevTools
• adv-testing-wrapper - 创建包含 QueryClient 和 AuthProvider 的测试包装器
• adv-opaque-types - 在 OpaqueTypes 中注册值类（7.87+）

使用方法

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect                        # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill react-hook-form  # deprecated APIs → rule IDs

对于上面与任务匹配的每条规则，以及每个 scan 命中项，请阅读 references/<rule-id>.md，了解其重要性以及错误与正确的代码示例。

相关技能

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