# React Hook 表单 + Zod 验证 **状态**：生产就绪 ✅ **最后更新**：2025-11-20 **依赖项**：无（独立） **最新版本**：react-hook-form@7.66.1、zod@4.1.12、@hookform/resolvers@5.2.2 ** ** ## 快速入门（10 分钟） ### 1\.安装包 npm install react-hook-form@7.66.1 zod@4.1.12 @hookform/resolvers@5.2.2 **为什么选择这些包**： * **react-hook-form** ：高性能、灵活的表单库，只需最少的重新渲染 * **zod** ：带有类型推断的 TypeScript-first 模式验证 * **@hookform/resolvers** ：用于将 Zod（和其他验证器）连接到 React Hook Form 的适配器 ### 2\.创建您的第一个表格从 'react-hook-form' 导入 { useForm } 从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'zod' 导入 { z } // 1. 定义验证模式 const loginSchema = z.object({ email: z.string().email('无效的电子邮件地址'), 密码: z.string().min(8, '密码必须至少8个字符'), }) // 2. 从 schema 推断 TypeScript 类型 type LoginFormData = z.infer 函数登录表单（）{ // 3. 使用zodResolver初始化表单常量{ 注册，处理提交， formState: { 错误, 正在提交 }, } = useForm({ 解析器：zodResolver(loginSchema), 默认值：{ 电子邮件：''，密码: '', }, }) // 4. 处理表单提交 const onSubmit = async (数据: LoginFormData) => { // 这里保证数据有效 console.log('有效数据：', data) // 进行API调用等 } 返回（

电子邮件 {错误.电子邮件 && ( {错误.电子邮件.消息} )}

密码 {错误.密码 && ( {错误.密码.消息} )}

<按钮类型=“提交”禁用= {isSubmitting}> {正在提交？ '正在登录...' : '登录'} ） } **关键**： * 始终设置`defaultValues`以防止“不受控制到受控制”警告 * 使用 `zodResolver(schema)` 连接 Zod 验证 * 使用“z.infer”键入表单以实现完整的类型安全 * 在客户端和服务器上进行验证（永远不要单独信任客户端验证） ### 3\.添加服务器端验证 // 服务器/api/login.ts 从 'zod' 导入 { z } // 服务器上的相同架构 const loginSchema = z.object({ email: z.string().email('无效的电子邮件地址'), 密码: z.string().min(8, '密码必须至少8个字符'), }) 导出异步函数loginHandler(req: Request) { 尝试{ // 解析并验证请求体 const data = loginSchema.parse(await req.json()) // 数据是类型安全且经过验证的 // 继续验证逻辑返回 { 成功：真 } } 捕获（错误）{ if (z.ZodError 错误实例) { // 返回验证错误给客户端返回 { 成功： false，错误： error.flatten().fieldErrors } } 抛出错误 } } **为什么要进行服务器验证**： * 可以绕过客户端验证（inspect element、Postman、curl） * 服务器验证是您的安全层 * 相同的 Zod 模式 = 单一事实来源 * 前端和后端的类型安全 ** ** ## 核心概念 ### useForm 钩子解剖常量{ register, // 注册输入字段 handleSubmit, // 包装 onSubmit 处理程序 watch, // 观察字段值 formState, // 表单状态（错误、isValid、isDirty 等） setValue, // 以编程方式设置字段值 getValues, // 获取当前表单值 Reset, // 将表单重置为默认值 trigger, // 手动触发验证 control, // Controller/useController 的控制对象 } = useForm({ 解析器: zodResolver(schema), // 验证解析器 mode: 'onSubmit', // 何时验证 (onSubmit, onChange, onBlur, all) defaultValues: {}, // 初始值（受控输入必需） }) **使用表单选项**：选项 |描述 |默认 ---|---|--- `解析器` |验证解析器（例如 zodResolver）|未定义 `模式` |何时验证 ('onSubmit', 'onChange', 'onBlur', 'all') | '提交' `重新验证模式` |错误后何时重新验证 | 'onChange' `默认值` |初始表单值 | {} `应该取消注册` |卸载时取消注册输入 |假的 `标准模式` |返回所有错误或仅返回第一个错误 | '第一个错误' **表单验证模式**： * `onSubmit` \- 提交时验证（最佳性能，响应较差） * `onChange` \- 验证每个更改（实时反馈，更多重新渲染） * `onBlur` \- 当字段失去焦点时进行验证（良好的平衡） * `all` \- 验证提交、模糊和更改（响应速度最快，成本最高） ### Zod 模式定义从 'zod' 导入 { z } // 基元 const stringSchema = z.string() const numberSchema = z.number() const booleanSchema = z.boolean() const dateSchema = z.date() // 带验证 const emailSchema = z.string().email('无效的电子邮件') const AgeSchema = z.number().min(18, '必须年满 18 岁').max(120, '年龄无效') const usernameSchema = z.string().min(3).max(20).regex(/^[a-zA-Z0-9_]+$/) // 对象 const userSchema = z.object({ 名称： z.string(), 电子邮件：z.string().email(), 年龄：z.number().int().positive(), }) // 数组 const tagSchema = z.array(z.string()) const usersSchema = z.array(userSchema) // 可选且可为空 const optionField = z.string().Optional() // 字符串 |未定义 const nullableField = z.string().nullable() // 字符串 |空 const nullishField = z.string().nullish() // 字符串 |空 |未定义 // 默认值 const withDefault = z.string().default('默认值') // 工会 const statusSchema = z.union([ z.literal('活动'), z.literal('不活动'), z.literal('待处理'), ]） // 文字的简写 const statusEnum = z.enum(['活动', '非活动', '待处理']) // 嵌套对象 const 地址架构 = z.object({ 街道：z.string(), 城市: z.string(), 邮政编码: z.string().regex(/^\d{5}$/), }) const profileSchema = z.object({ 名称： z.string(), address: addressSchema, // 嵌套对象 }) // 自定义错误信息 const 密码架构 = z.string() .min(8, { message: '密码必须至少为 8 个字符' }) .regex(/[A-Z]/, { message: '密码必须包含大写字母' }) .regex(/[0-9]/, { message: '密码必须包含数字' }) **类型推断**： const userSchema = z.object({ 名称： z.string(), 年龄：z.number(), }) // 自动推断 TypeScript 类型 type User = z.infer // 结果：{ 名称：字符串；年龄：数字 } ### Zod 改进（自定义验证） // 简单细化 const passwordConfirmSchema = z.object({ 密码：z.string().min(8), 确认密码：z.string(), }).refine((data) => data.password === data.confirmPassword, { 消息：“密码不匹配”， path: ['confirmPassword'], // 确认密码字段将出现错误 }) // 多次细化 const signupSchema = z.object({ 用户名：z.string(), 电子邮件：z.string().email(), 年龄：z.number(), }) .refine((data) => data.username !== data.email.split('@')[0], { message: '用户名不能是您的电子邮件前缀', 路径: ['用户名'], }) .refine((数据) => data.age >= 18, { message: '必须年满 18 岁', 路径：['年龄']， }) // 异步细化（用于 API 检查） const usernameSchema = z.string().refine(async (用户名) => { // 通过 API 检查用户名是否可用 const response = wait fetch(`/api/check-username?username=${username}`) const { 可用 } = 等待响应.json() 可退货 }, { message: '用户名已被占用', }) ### Zod 变换（数据操作） // 将字符串转换为数字 const AgeSchema = z.string().transform((val) => parseInt(val, 10)) // 转换为大写 const uppercaseSchema = z.string().transform((val) => val.toUpperCase()) // 将日期字符串转换为Date对象 const dateSchema = z.string().transform((val) => new Date(val)) // 修剪空白 const trimmedSchema = z.string().transform((val) => val.trim()) // 复杂变换 const userInputSchema = z.object({ 电子邮件： z.string().email().transform((val) => val.toLowerCase()), 标签： z.string().transform((val) => val.split(',').map(tag => tag.trim())), }) // 链式变换和细化 const PositiveNumberSchema = z.string() .transform((val) => parseFloat(val)) .refine((val) => !isNaN(val), { message: '必须是数字' }) .refine((val) => val > 0, { message: '必须为正数' }) ### zodResolver 集成从 '@hookform/resolvers/zod' 导入 { zodResolver } const form = useForm({ 解析器：zodResolver（架构）， }) **zodResolver 的作用**： 1. 采用您的 Zod 模式 2.将其转换为React Hook Form可以理解的格式 3.提供在表单提交时运行的验证功能 4. 将 Zod 错误映射到 React Hook Form 错误格式 5. 通过 TypeScript 推理保持类型安全 **zodResolver 选项**：从 '@hookform/resolvers/zod' 导入 { zodResolver } // 带选项常量形式 = useForm({ 解析器：zodResolver（模式，{ async: false, // 使用异步验证 raw: false, // 返回原始 Zod 错误 }), }) ** ** ## 表单注册模式 ### 模式 1：简单输入注册函数 BasicForm() { const { 注册，handleSubmit } = useForm({ 解析器：zodResolver（架构）， }) 返回（ {/* 将寄存器结果传播到输入*/} <输入{...注册('电子邮件')} /> <输入{...注册('密码')} /> {/* 使用自定义道具 */} <输入 {...注册('用户名')} 占位符=“输入用户名” 类名=“输入” /> ） } **`register()` 返回什么**： { onChange: (e) => 无效, onBlur: (e) => 无效, 参考：（实例）=>无效，名称：字符串， } ### 模式 2：控制器（用于自定义组件）当输入不公开“ref”时使用“Controller”（例如自定义组件、React Select、日期选择器等）：从'react-hook-form'导入{控制器} 函数 FormWithCustomInput() { const { 控制，handleSubmit } = useForm({ 解析器：zodResolver（架构）， }) 返回（ <控制器名称=“类别” 控制={控制} 渲染={({字段})=>( <自定义选择 {...field} // 值、onChange、onBlur、ref 选项={类别选项} /> )} /> {/* 拥有更多控制权 */} <控制器姓名=“出生日期” 控制={控制} 渲染={({ 字段, 字段状态 }) => (

<日期选择器所选={字段.值} onChange={field.onChange} onBlur={field.onBlur} /> {fieldState.error && ( {fieldState.error.message} )}

)} /> ） } **何时使用控制器**： * ✅ 第三方UI库（React Select、Material-UI、Ant Design等） * ✅ 不暴露 ref 的自定义组件 * ✅ 不使用 onChange 的组件（例如带有自定义处理程序的复选框） * ✅ 需要对现场行为进行细粒度的控制 **何时不使用控制器**： * ❌ 标准 HTML 输入（使用 `register` 代替 - 它更简单、更快） * ❌ 当性能至关重要时（控制器增加最小的开销） ### 模式 3：useController（可重用控制输入）从 'react-hook-form' 导入 { useController } // 可重用的自定义输入组件函数 CustomInput({ 名称, 控件, 标签 }) { 常量{ 场, 字段状态：{错误}， } = useController({ 名字，控制, 默认值：''， }) 返回（

<标签>{标签} <输入{...字段} /> {错误&& {error.message}}

） } // 用法函数 MyForm() { const { 控制，handleSubmit } = useForm({ 解析器：zodResolver（架构）， }) 返回（） } ** ** ## 错误处理 ### 显示错误函数 FormWithErrors() { const { 注册、handleSubmit、formState: { 错误 } } = useForm({ 解析器：zodResolver（架构）， }) 返回（

<输入{...注册('电子邮件')} aria-invalid={errors.email ? '真'：'假'} /> {/* 简单的错误显示 */} {errors.email && {errors.email.message}} {/* 可访问的错误显示 */} {错误.电子邮件 && ( {错误.电子邮件.消息} )} {/* 图标错误 */} {错误.电子邮件 && (

<错误图标/> {errors.email.message}

)}

） } ### 错误对象结构 // 错误对象结构 { 电子邮件：{ 类型：'无效字符串'， message: '无效的电子邮件地址', }, 密码：{ 类型：'太小'， message: '密码必须至少为 8 个字符', }, // 嵌套错误地址：{ 街道：{ 类型：'无效类型'， message: '预期的字符串，收到未定义', }, }, } ### 表单级验证错误 const 架构 = z.object({ 密码：z.string().min(8), 确认密码：z.string(), }).refine((data) => data.password === data.confirmPassword, { 消息：“密码不匹配”， path: ['confirmPassword'], // 将错误附加到confirmPassword字段 }) // 没有路径 - 创建根错误 .refine((数据) => 一些条件, { message: '表单验证失败', }) // 访问根错误 const { formState: { 错误 } } = useForm() error.root?.message // 根级错误 ### 服务器错误集成函数 FormWithServerErrors() { const { 注册，handleSubmit，setError，formState：{ 错误 } } = useForm({ 解析器：zodResolver（架构）， }) const onSubmit = 异步（数据）=> { 尝试{ const 响应 = 等待 fetch('/api/submit', { 方法：'POST'，正文：JSON.stringify（数据）， }) 如果（！response.ok）{ const { 错误：serverErrors } = 等待response.json() // 将服务器错误映射到表单字段 Object.entries(serverErrors).forEach(([字段, 消息]) => { 设置错误（字段，{ 类型：'服务器'，留言， }) }) 返回 } // 成功！ } 捕获（错误）{ // 一般错误 setError('根', { 类型：'服务器'，消息：'发生错误。请再试一次。', }) } } 返回（ {errors.root &&

{errors.root.message}

} {/* ... */} ） } ** ** ## 高级模式 ### 动态表单字段 (useFieldArray) 从 'react-hook-form' 导入 { useForm, useFieldArray } 从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'zod' 导入 { z } const contactSchema = z.object({ 联系人： z.array( z. 对象({ name: z.string().min(1, '名称为必填项'), email: z.string().email('无效的电子邮件'), }) ).min(1, '至少需要一个联系人'), }) type ContactFormData = z.infer 函数ContactListForm() { const { 注册、控制、handleSubmit、formState: { 错误 } } = useForm({ 解析器：zodResolver(contactSchema), 默认值：{ 联系人：[{姓名：''，电子邮件：''}]， }, }) const { 字段、追加、删除 } = useFieldArray({ 控制, 名称：'联系人'， }) 返回（ {fields.map((字段，索引) => (

{/* 重要提示：使用 field.id，而不是索引 */} <输入 {...注册(`联系人。${index}.name` as const)} 占位符=“名称” /> {errors.contacts?.[index]?.name && ( {errors.contacts[index].name.message} )} <输入 {...注册(`联系人。${index}.email` as const)} 占位符=“电子邮件” /> {错误.联系人？.[索引]？.电子邮件 && ( {errors.contacts[index].email.message} )}

))} <按钮类型=“按钮” onClick={() => 附加({ 姓名: '', 电子邮件: '' })} > 添加联系人） } **使用FieldArray API**： * `fields` \- 具有唯一 ID 的字段项数组 * `append(value)` \- 添加新项目到末尾 * `prepend(value)` \- 将新项目添加到开头 * `insert(index, value)` \- 在索引处插入项目 * `remove(index)` \- 删除索引处的项目 * `update(index, value)` \- 更新索引处的项目 * `replace(values)` \- 替换整个数组 ### 异步验证与去抖动从 'react-hook-form' 导入 { useForm } 从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'zod' 导入 { z } import { useDebouncedCallback } from 'use-debounce' // npm install use-debounce const usernameSchema = z.string().min(3).refine(async (用户名) => { const response = wait fetch(`/api/check-username?username=${username}`) const { 可用 } = 等待响应.json() 可退货 }, { message: '用户名已被占用', }) 函数 AsyncValidationForm() { const { 注册、handleSubmit、触发器、formState: { 错误、isValidating } } = useForm({ 解析器：zodResolver(z.object({ 用户名: usernameSchema })), mode: 'onChange', // 验证每个更改 }) // 反跳验证以避免过多的 API 调用 const debouncedValidation = useDebouncedCallback(() => { 触发器('用户名') }, 500) // 用户停止输入后等待 500 毫秒返回（ <输入 {...注册('用户名')} onChange={(e) => { 注册（'用户名'）.onChange（e）去抖验证() }} /> {isValidating && 正在检查可用性...} {errors.username && {errors.username.message}} ） } ### 多步骤表单（向导）从 'react' 导入 { useState } 从 'react-hook-form' 导入 { useForm } 从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'zod' 导入 { z } // 步骤模式 const step1Schema = z.object({ name: z.string().min(1, '名称为必填项'), email: z.string().email('无效的电子邮件'), }) const step2Schema = z.object({ 地址: z.string().min(1, '地址为必填项'), 城市: z.string().min(1, '城市为必填项'), }) const step3Schema = z.object({ cardNumber: z.string().regex(/^\d{16}$/, '卡号无效'), cvv: z.string().regex(/^\d{3,4}$/, 'CVV 无效'), }) // 用于最终验证的组合模式 const fullSchema = step1Schema.merge(step2Schema).merge(step3Schema) type FormData = z.infer 函数 MultiStepForm() { const [步骤，设置步骤] = useState(1) const { 注册、handleSubmit、触发器、formState: { 错误 } } = useForm({ 解析器：zodResolver(fullSchema), 模式：'onChange'， }) const nextStep = async () => { 让 fieldsToValidate: (FormData 的键)[] = [] 如果（步骤=== 1）{ fieldsToValidate = ['姓名', '电子邮件'] } 否则如果（步骤 === 2）{ fieldsToValidate = ['地址', '城市'] } // 验证当前步骤字段 const isValid = 等待触发器(fieldsToValidate) 如果（有效）{ 设置步长（步长+1） } } const prevStep = () => setStep(步骤 - 1) const onSubmit = (数据: FormData) => { console.log('最终数据：', data) } 返回（ {/* 进度指示器 */}

第 {step} 步（共 3 步）

{/* 步骤 1 */} {步骤 === 1 && (

个人信息

{errors.name && {errors.name.message}} {errors.email && {errors.email.message}}

)} {/* 步骤 2 */} {步骤 === 2 && (

地址

{errors.address && {errors.address.message}} {errors.city && {errors.city.message}}

)} {/* 步骤 3 */} {步骤=== 3 && (

付款

{errors.cardNumber && {errors.cardNumber.message}} <输入{...register('cvv')}占位符=“CVV”/> {errors.cvv && {errors.cvv.message}}

)} {/* 导航 */}

{步骤 > 1 && ( <按钮类型=“按钮”onClick={prevStep}> 上一页 )} {步骤<3？（ <按钮类型=“按钮”onClick={nextStep}> 下一步 ) : ( )}

） } ### 条件验证从 'zod' 导入 { z } // 带有条件验证的模式 const formSchema = z.discriminatedUnion('accountType', [ z. 对象({ accountType: z.literal('个人'), 名称：z.string().min(1), }), z. 对象({ accountType: z.literal('business'), 公司名称：z.string().min(1), taxId: z.string().regex(/^\d{9}$/), }), ]） // 替代方案：使用精炼 const 条件模式 = z.object({ hasDiscount: z.boolean(), 折扣代码：z.string().可选()， }).refine((数据) => { // 如果hasDiscount为true，则需要discountCode if (data.hasDiscount && !data.discountCode) { 返回错误 } 返回真 }, { message: '启用折扣时需要折扣码', 路径: ['折扣代码'], }) ** ** ## shadcn/ui 集成 ### 使用表单组件（旧版）从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'react-hook-form' 导入 { useForm } 从 'zod' 导入 { z } 导入{ 形式，表单控件，表格描述，表单字段，表单项，表单标签，表单消息，来自 '@/components/ui/form' 从'@/components/ui/input'导入{输入} const formSchema = z.object({ 用户名: z.string().min(2, '用户名必须至少为 2 个字符'), email: z.string().email('无效的电子邮件地址'), }) 函数 ProfileForm() { const form = useForm>({ 解析器：zodResolver(formSchema), 默认值：{ 用户名: '', 电子邮件：''， }, }) 返回（ <表格{...表格}> <表单域控制={form.control} 名称=“用户名” 渲染={({字段})=>( <表单项> 用户名 <表单控件> <输入占位符=“shadcn”{...字段} /> <表单描述> 这是您的公开显示名称。 <表单消息/> )} /> <表单域控制={form.control} 姓名=“电子邮件” 渲染={({字段})=>( <表单项> 电子邮件 <表单控件> <输入类型=“电子邮件”占位符=“email@example.com”{...字段} /> <表单消息/> )} /> ） } **注意**：shadcn/ui 声明“我们不再积极开发 Form 组件。”他们建议使用 Field 组件进行新的实现。 ### 使用 Field 组件（推荐）检查 shadcn/ui 文档以获取最新的 Field 组件 API，因为它是主动维护的方法。 ** ** ## 性能优化 ### 表单模式策略 // 最佳性能 - 仅在提交时验证常量形式 = useForm({ 模式：'onSubmit'，解析器：zodResolver（架构）， }) // 良好的平衡 - 验证模糊常量形式 = useForm({ 模式：'onBlur'，解析器：zodResolver（架构）， }) // 实时反馈 - 验证每个更改常量形式 = useForm({ 模式：'onChange'，解析器：zodResolver（架构）， }) // 最大验证 - 所有事件常量形式 = useForm({ 模式：“全部”，解析器：zodResolver（架构）， }) ### 受控输入与非受控输入 // 不受控制（更好的性能）-使用寄存器 <输入{...注册('电子邮件')} /> // 受控（更多控制）-使用Controller <控制器姓名=“电子邮件” 控制={控制} 渲染={({ 字段}) => <输入{...字段} />} /> **建议**：对标准输入使用“register”，仅在必要时使用“Controller”（第三方组件、自定义行为）。 ### 与控制器隔离 // 不好：当任何字段更改时整个表单都会重新呈现函数 BadForm() { const { 观察 } = useForm() const value = watch() // 监视所有字段返回

{JSON.stringify(values)}

} // 好：仅在特定字段更改时重新渲染函数 GoodForm() { const { 观察 } = useForm() const email = watch('email') // 仅监视电子邮件字段返回

{电子邮件}

} ### 应该取消注册标志常量形式 = useForm({ 解析器：zodResolver（架构）， shouldUnregister: true, // 卸载时移除字段数据 }) **何时使用**： * ✅ 多步骤表单，其中步骤具有不同的字段 * ✅ 不应持续存在的条件字段 * ✅ 想要在组件卸载时清除数据 **何时不使用**： * ❌ 希望在切换可见性时保留表单数据 * ❌ 在表单部分（选项卡、手风琴）之间导航 ** ** ## 辅助功能最佳实践 ### ARIA 属性函数 AccessibleForm() { const { 注册，handleSubmit，formState：{ 错误 } } = useForm({ 解析器：zodResolver（架构）， }) 返回（

电子邮件 <输入 id=“电子邮件” {...注册('电子邮件')} aria-invalid={错误.电子邮件？ '真'：'假'} aria-描述的 = {错误.电子邮件？ “电子邮件错误”：未定义} /> {错误.电子邮件 && ( {错误.电子邮件.消息} )}

） } ### 错误公告从 'react' 导入 { useEffect } 函数 FormWithAnnouncements() { const { formState: { 错误, isSubscribed } } = useForm() // 向屏幕阅读器宣布错误使用效果（（）=> { if (isSubmited && Object.keys(errors).length > 0) { const errorCount = Object.keys(errors).length const notification = `表单提交失败，${errorCount} 错误${errorCount > 1 ? 's'：''}` // 创建公告直播区域 const liveRegion = document.createElement('div') liveRegion.setAttribute('角色', '警报') liveRegion.setAttribute('aria-live', '断言') liveRegion.textContent = 公告 document.body.appendChild(liveRegion) 设置超时（（）=> { document.body.removeChild(liveRegion) }, 1000) } }, [错误, 已提交]) 返回（ <表格> {/* ... */} ） } ### 焦点管理从 'react' 导入 { useRef, useEffect } 函数 FormWithFocus() { const { handleSubmit, formState: { 错误 } } = useForm() const firstErrorRef = useRef(null) // 将第一个错误字段集中在验证失败上使用效果（（）=> { if (Object.keys(errors).length > 0) { firstErrorRef.current?.focus() } }，[错误]）返回（ <输入 {...注册('电子邮件')} ref={错误.电子邮件？第一个错误引用：未定义} /> ） } ** ** ## 关键规则 ### 总是这样做 ✅ **设置defaultValues**以防止“不受控制到受控制”警告常量形式 = useForm({ defaultValues: { email: '', password: '' }, // 始终设置默认值 }) ✅ **使用 zodResolver** 进行 Zod 集成常量形式 = useForm({ resolver: zodResolver(schema), // Zod 验证所需 }) ✅ **使用 z.infer 输入表单** type FormData = z.infer // 自动类型推断 ✅ **在客户端和服务器上验证** // 客户端 const form = useForm({ 解析器: zodResolver(schema) }) // 服务器 const data = schema.parse(await req.json()) // 相同的模式 ✅ **使用formState.errors进行错误显示** {errors.email && {errors.email.message}} ✅ **添加 ARIA 属性以实现可访问性** <输入 {...注册('电子邮件')} aria-invalid={错误.电子邮件？ '真'：'假'} aria-描述的=“电子邮件错误” /> ✅ **使用 field.id 作为 useFieldArray 键** {fields.map((field) =>

{/* ... */}

)} ✅ **反跳异步验证** const debouncedValidation = useDebouncedCallback(() => 触发器('用户名'), 500) ### 永远不要这样做 ❌ **跳过服务器端验证**（安全漏洞！） // 不好：仅客户端验证 const form = useForm({ 解析器: zodResolver(schema) }) // API端点没有验证 // 好：在客户端和服务器上验证 const form = useForm({ 解析器: zodResolver(schema) }) // API: schema.parse(data) 也在服务器上 ❌ **使用 Zod v4 而不检查类型推断** // 问题 #13109：Zod v4 具有类型推断更改 // 升级时仔细测试你的类型 ❌ **忘记在控制器中展开 {...field}** // 不好 <控制器渲染={({ field }) => <输入值={field.value} />} /> // 好 } /> ❌ **直接改变表单值** // 不好常量值 = getValues() value.email = 'new@email.com' // 直接突变 // 好 setValue('email', 'new@email.com') // 使用 setValue ❌ **使用内联验证而不去抖动** // 不好：每次击键时都进行验证 const form = useForm({ mode: 'onChange' }) // 好：反跳异步验证 const debouncedTrigger = useDebouncedCallback(() => 触发器(), 500) ❌ **混合受控和非受控输入** // 不好：混合模式 // 好：选择一种模式 // 不受控制 // 或 } /> // 受控 ❌ **在 useFieldArray 中使用索引作为键** // 不好 {fields.map((字段，索引) =>

{/* ... */}

)} // 好 {fields.map((field) =>

{/* ... */}

)} ❌ **忘记所有字段的默认值** // 不好：缺少默认值会导致警告常量形式 = useForm({ 解析器：zodResolver（架构）， }) // 好：为所有字段设置默认值常量形式 = useForm({ 解析器：zodResolver（架构）， defaultValues: { 电子邮件: '', 密码: '', 记住: false }, }) ** ** ## 已知问题预防此技能可防止 **12** 已记录的问题： ### 问题 #1：Zod v4 类型推断错误 **错误**：类型推断在 Zod v4 中无法正常工作 **来源**：[GitHub Issue #13109]()（2025 年 11 月 1 日关闭） **为什么会发生**：Zod v4 更改了类型的推断方式 **预防**：使用正确的类型模式：`type FormData = z.infer` **注意**：在react-hook-form v7.66.x+中解决。升级到最新版本可以避免此问题。 ### 问题#2：不受控制到受控制的警告 **错误**：“组件正在将不受控制的输入更改为受控制”**来源**：React文档**为什么会发生**：不设置defaultValues会导致未定义->值转换**预防**：始终为所有字段设置defaultValues ### 问题 #3：嵌套对象验证错误 **错误**：嵌套字段的错误无法正确显示 **来源**：常见的 React Hook 表单问题 **为什么会发生**：错误地访问嵌套错误 **预防**：使用可选链接：`errors.address?.street?.message` ### 问题 #4：数组字段重新渲染 **错误**：表单使用数组字段过度重新渲染 **来源**：性能问题 **为什么会发生**：不使用 field.id 作为键 **预防**：在 useFieldArray 映射中使用 `key={field.id}` ### 问题 #5：异步验证竞争条件 **错误**：多个验证请求导致结果冲突 **来源**：常见的异步模式问题 **为什么会发生**：没有去抖动或请求取消 **预防**：去抖动验证并取消挂起的请求 ### 问题#6：服务器错误映射 **错误**：服务器验证错误未映射到表单字段 **来源**：集成问题 **为什么会发生**：服务器错误格式与 React Hook 表单格式不匹配 **预防**：使用 setError() 将服务器错误映射到字段 ### 问题 #7：未应用默认值 **错误**：表单字段不显示默认值 **来源**：常见错误 **为什么会发生**：表单初始化后设置默认值 **预防**：在 useForm 选项中设置默认值，而不是 useState ### 问题#8：控制器字段未更新 **错误**：值更改时自定义组件不会更新 **来源**：常见控制器问题 **为什么会发生**：不在渲染函数中传播 {...field} **预防**：始终将 {...field} 传播到自定义组件 ### 问题 #9：useFieldArray 关键警告 **错误**：React关于列表中重复键的警告**来源**：React列表渲染**为什么会发生**：使用数组索引作为键而不是field.id **预防**：使用field.id：`key = {field.id}` ### 问题#10：模式细化错误路径 **错误** ：自定义验证错误出现在错误的字段 **来源** ：Zod 细化行为 **为什么会发生** ：未在细化选项中指定路径 **预防** ：添加路径选项： `refine(..., { message: '...', path: ['fieldName'] })` ### 问题 #11：转换与预处理的混淆 **错误**：数据转换没有按预期工作 **来源**：Zod API 混乱 **为什么会发生**：对用例使用错误的方法 **预防**：使用转换进行输出转换，使用预处理进行输入转换 ### 问题 #12：多个解析器冲突 **错误**：表单验证不适用于多个解析器 **来源**：配置错误 **为什么会发生**：尝试使用多个验证库 **预防**：使用单个解析器 (zodResolver)，如果需要，请组合架构 ** ** ## 模板请参阅“templates/”目录以获取工作示例： 1. **basic-form.tsx** \- 简单的登录/注册表单 2. **advanced-form.tsx** \- 嵌套对象、数组、条件字段 3. **shadcn-form.tsx** \- shadcn/ui Form组件集成 4. **server-validation.ts** \- 具有相同模式的服务器端验证 5. **async-validation.tsx** \- 具有去抖动功能的异步验证 6. **dynamic-fields.tsx** \- useFieldArray 用于添加/删除项目 7. **multi-step-form.tsx** \- 具有每步验证的向导 8. **custom-error-display.tsx** \- 自定义错误格式 9. **package.json** \- 完整的依赖关系 ** ** ## 参考文献请参阅“references/”目录以获取深入的文档： 1. **zod-schemas-guide.md** \- 全面的 Zod 架构模式 2. **rhf-api-reference.md** \- 完整的 React Hook Form API 3. **error-handling.md** \- 错误消息、格式、可访问性 4. **accessibility.md** \- WCAG 合规性、ARIA 属性 5. **performance-optimization.md** \- 表单模式、验证策略 6. **shadcn-integration.md** \- shadcn/ui 表单与字段组件 7. **top-errors.md** \- 12个常见错误及解决方案 8. **links-to-official-docs.md** \- 有组织的文档链接 ** ** ## 官方文档 * **React Hook 表单** : * **佐德**： * **@hookform/resolvers** : * **shadcn/ui 表单** : ** ** **许可证**：麻省理工学院 **最后验证**：2025-11-20 **维护者**：Jeremy Dawes ([jeremy@jezweb.net]())

React Hook 表单 Zod

包含技能