react-hook-form

用途

本技能提供 React Hook Form 应用的性能优化指南，面向使用 React Hook Form 7 编写、审查或重构表单的场景。它包含 45 条规则，分布在 8 个类别中，按影响程度排序，可用于指导表单开发、自动化重构和代码生成。

适用时机

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

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

规则类别（按优先级）

优先级	类别	影响	前缀
1	Form Configuration	CRITICAL	formcfg-
2	Field Subscription	CRITICAL	sub-
3	Controlled Components	HIGH	ctrl-
4	Validation Patterns	HIGH	valid-
5	Field Arrays	MEDIUM-HIGH	array-
6	State Management	MEDIUM	formstate-
7	Integration Patterns	MEDIUM	integ-
8	Advanced Patterns	LOW	adv-

快速参考

1. 表单配置（CRITICAL）

formcfg-validation-mode - 根据 UX 与校验成本选择校验模式
formcfg-revalidate-mode - 有意识地选择提交后重新校验模式
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 字段属性
ctrl-single-usecontroller-per-component - 当隔离有帮助时拆分受控字段
ctrl-local-state-combination - 结合本地状态与 useController 处理纯 UI 状态

4. 校验模式（HIGH）

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. 字段数组（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. 状态管理（MEDIUM）

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. 集成模式（MEDIUM）

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. 高级模式（LOW）

adv-formprovider-memo - 仅在性能分析后对 FormProvider 子元素进行 memo 化
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

针对上述每条与任务匹配的规则以及每个扫描命中项，阅读 references/<rule-id>.md：了解其重要性，以及错误与正确代码的对比。

技能介绍

用途