用途
react-hook-form-zod 是一个用于在 React 中构建类型安全表单的技能，将 React Hook Form 的表单状态管理与 Zod 的 schema 校验结合使用。资料说明其适用场景包括：表单 schema 定义、字段数组（field arrays）、多步表单，以及处理校验错误。
主要能力
- 使用 Zod 定义校验 schema，并通过 @hookform/resolvers 提供的 zodResolver 接入 React Hook Form。
- 通过 z.infer<typeof schema> 从 schema 推导 TypeScript 类型，实现表单类型安全。
- 支持嵌套对象、数组、可选与可空字段等 schema 结构。
- 支持动态字段（useFieldArray）、异步校验、多步表单、shadcn/ui 集成、服务端校验等模式。
- 提供校验模式选择：onSubmit、onChange、onBlur、all。
- 提供性能优化与无障碍相关指引。
使用方式
资料给出的安装命令：
bun add react-hook-form@7.84.0 zod@4.3.6 @hookform/resolvers@5.2.2
基本流程：
- 用 Zod 定义 schema，例如：
const loginSchema = z.object({ email: z.email({ error: 'Invalid email address' }), password: z.string().min(8, 'Password must be at least 8 characters'), })
- 用 z.infer 推导类型：
type LoginFormData = z.infer<typeof loginSchema>
- 初始化表单并接入 zodResolver：
const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<LoginFormData>({ resolver: zodResolver(loginSchema), defaultValues: { email: '', password: '' }, })
-
用 handleSubmit 包裹提交处理函数，在 onSubmit 中处理已校验的数据。
-
服务端使用同一份 schema 再次校验，例如通过 loginSchema.parse(await req.json())，并用 z.flattenError(error).fieldErrors 返回字段错误。
关键规则
资料强调的必做事项：始终设置 defaultValues；使用 zodResolver 连接校验；用 z.infer 推导类型；客户端与服务端都要校验；原生输入使用 .register()；自定义组件使用 Controller；错误信息使用 role="alert" 保证无障碍；提交后使用 reset() 重置表单。
资料强调的禁止事项：不要跳过 defaultValues；不要只做客户端校验；不要直接修改表单值（应使用 setValue()）；不要忽略无障碍；isSubmitting 时不要忘记禁用提交按钮以防重复提交。
常见模式
- 基础表单：register + handleSubmit + errors 展示。
- 动态字段：useFieldArray 的 fields、append、remove，name 必须与 schema 字段名完全一致。
- 异步校验：在 Zod 中使用 refine 配合异步函数（如检查用户名是否可用）。
- 多步表单：用 mode: 'onBlur' 在进入下一步前校验当前步骤。
- shadcn/ui 集成：使用 Form、FormField、FormItem、FormLabel、FormControl、FormMessage 等组件。
附带资源
模板（templates/）：basic-form.tsx、advanced-form.tsx、shadcn-form.tsx、multi-step-form.tsx、dynamic-fields.tsx、async-validation.tsx、server-validation.tsx、custom-error-display.tsx、package.json。
参考文档（references/）：top-errors.md、rhf-api-reference.md、zod-schemas-guide.md、shadcn-integration.md、error-handling.md、performance-optimization.md、accessibility.md、links-to-official-docs.md。
适用场景
需要在 React 中构建带类型安全校验的表单，尤其是涉及复杂 schema、动态字段、多步流程、异步校验或与 shadcn/ui 等组件库集成的场景。
限制与注意事项
资料未提供该技能的收费、价格、平台支持范围或效果承诺等信息。资料列出的依赖版本为 react-hook-form@7.84.0、zod@4.3.6、@hookform/resolvers@5.2.2；可选依赖包括 @radix-ui/react-label 与 class-variance-authority（用于 shadcn/ui 集成）。资料提到 Zod v4 类型推导问题（来源标注为 GitHub Issue #13109），必要时需显式标注 useForm 类型。