react-hook-form

React Hook Form 最佳实践

涵盖 React Hook Form 的 8 个类别、41 条规则，按影响程度排序，帮助指导表单开发、自动重构和代码生成。

适用场景

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

按优先级划分的规则类别

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

快速参考

1. 表单配置（CRITICAL）

• 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. 字段订阅（CRITICAL）

• 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. 受控组件（HIGH）

• 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. 验证模式（HIGH）

• 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. 字段数组（MEDIUM-HIGH）

• 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 技能
• 进行 UI/UX 表单设计，请参阅 frontend-design 技能

完整编译文档

如需查看包含所有展开规则的完整指南，请参阅 ${CLAUDE_SKILL_DIR}/AGENTS.md（需要深入参考规则时加载）。