react-hook-form Zod schema校验完全教程一次定义类型安全与表单校验兼得【免费下载链接】react-hook-form React Hooks for form state management and validation (Web React Native)项目地址: https://gitcode.com/gh_mirrors/re/react-hook-formreact-hook-form是一个轻量、高性能的 React 表单状态管理与校验库支持 Web 与 React Native。把它和Zod schema校验结合起来就能做到一次定义两处受益Zod 负责运行时校验表单数据z.infer()负责编译期推导 TypeScript 类型表单字段类型从此告别手写。本文将带你从零搭建快速掌握这套组合的核心用法。为什么选择 Zod schema校验而不是逐字段注册规则传统的表单校验方式是在每个输入框上挂required、min、pattern等规则。字段一多规则就散落在 JSX 里而且字段类型要靠手写的 interface 维护改一处漏一处。schema校验的思路是把规则集中到一个**模式对象schema**里对比项逐字段注册Zod schema校验规则位置分散在每个输入框集中在一个 schema 文件字段类型手写 interface易漂移z.infer()自动推导跨字段联动二选一、条件必填难以表达.refine()原生支持服务端复用无法复用同一个 schema 可直接校验请求体react-hook-form 官方就内置了对 Zod 的支持通过 Resolver 机制 把任意校验库接进来。其核心就是一个Resolver函数输入表单值返回{ values, errors }——这正是 schema校验库的天然输出格式。安装与准备react-hook-form 接入 Zod 的最快方式需要安装三个依赖表单库react-hook-form、类型校验库zod以及官方提供的桥接包hookform/resolvers它负责把 Zod 的校验结果转换成 react-hook-form 认识的错误结构npm install react-hook-form zod hookform/resolvers 仓库内的演示应用 app/package.json 中也依赖了hookform/resolvers官方示例默认用 Yup/Joi 演示见 app/src/basicSchemaValidation.tsx、app/src/customSchemaValidation.tsx换成 Zod 只需把yupResolver替换成zodResolver其余写法完全一致。三步完成 Zod schema 配置定义、推导、注入第一步用 Zod 定义表单 schemaimport { z } from zod; const SignupSchema z.object({ firstName: z.string().min(2, 姓名至少2个字符).required(姓名必填), age: z.number().positive().int().refine((n) n 150, 年龄超出范围), email: z.string().email(邮箱格式不正确), }); type SignupForm z.infertypeof SignupSchema; // 类型自动推导注意z.infertypeof SignupSchema表单的字段名、类型、必填性全部由 schema 推导不再需要手写 interface。以后改 schema表单类型自动跟着变。第二步把 zodResolver 注入 useFormimport { useForm } from react-hook-form; import { zodResolver } from hookform/resolvers/zod; const { register, handleSubmit, formState: { errors } } useFormSignupForm({ resolver: zodResolver(SignupSchema), defaultValues: { firstName: , age: undefined, email: }, });useFormSignupForm()加上泛型后register(firstName)写错字段名、errors.email拼错 keyTypeScript 都会直接报错——这就是类型安全的来源。第三步绑定输入框并展示错误form onSubmit{handleSubmit((data) console.log(data))} input {...register(firstName)} placeholder姓名 / {errors.firstName p{errors.firstName.message}/p} input typenumber {...register(age)} placeholder年龄 / {errors.age p{errors.age.message}/p} input typeemail {...register(email)} placeholder邮箱 / {errors.email p{errors.email.message}/p} button提交/button /formerrors对象中每个字段的message就是你在 Zod 里写的中文提示会原样展示给用户。官方示例里对错误结构的定义见 src/types/errors.ts。校验时机怎么选mode 参数实战mode决定 schema校验在什么时机触发直接决定用户体验mode触发时机适用场景onSubmit默认只在提交时快速表单少打扰用户onBlur字段失焦时推荐默认值平衡体验与及时报错onChange每次输入时需要即时反馈如密码强度useFormSignupForm({ resolver: zodResolver(SignupSchema), mode: onBlur, }); 常见搭配姓名、邮箱用onBlur而二选一必填这类联动规则配合criteriaMode使用避免用户还没填完就报错。进阶技巧setValue 时手动触发校验有时你需要在提交按钮前用setValue程序化地填入某个字段比如从远程接口回填。配合 schema校验必须带上shouldValidate: true否则新值不会立即过 Zod 校验setValue(email, userexample.com, { shouldValidate: true });仓库里的演示 app/src/setValueWithSchema.tsx 展示了完整的写法。常见问题清单数字字段校验不通过输入框的value永远是字符串Zod 的z.number()会校验失败。用z.coerce.number()自动转换或在 schema 里写z.string().transform(Number)。defaultValues 会影响校验吗会。如果defaultValues里给了默认值该字段初始就被视为已填Zod 的required不会报初始错误——这是预期行为不是 bug。能用其他库替代 Zod 吗可以。react-hook-form 通过 Resolver 抽象 支持 Yup、Joi、AJV 等配置方式完全相同。官方中文文档见 docs/README.V7.zh-CN.md。提交时 data 的类型是什么就是z.infer推导出来的对象且已经是转换后的值比如z.coerce之后的 number可直接发给后端。总结一次定义两处受益Zod schema集中描述规则z.infer()推导类型zodResolver一行注入useForm——三步完成接入编译期类型安全 运行时 schema校验字段变更零漂移同一个 schema 还能复用到接口请求体校验前后端共用一份契约。更多可运行示例可以浏览仓库的演示应用 app/src/基于 Vite React 19和 examples/V7/ 目录下的经典用法。clone 仓库后即可在本地体验全部案例。【免费下载链接】react-hook-form React Hooks for form state management and validation (Web React Native)项目地址: https://gitcode.com/gh_mirrors/re/react-hook-form创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考