react-hook-form 快速入门基于 React Hooks 的表单状态管理与验证实战指南【免费下载链接】react-hook-form React Hooks for form state management and validation (Web React Native)项目地址: https://gitcode.com/gh_mirrors/re/react-hook-form本文基于 docs/README.ar-AR.mdreact-hook-form 阿拉伯语社区维护版 README的核心内容展开面向需要快速上手表单状态管理、原生表单验证与 schema 校验集成的 React 开发者。读完本文你将掌握useForm的最小可用流程register/handleSubmit/errors、全部内置验证规则及其类型定义并了解如何对接 Yup、Zod 等第三方校验器同时结合仓库源码与端到端测试理解验证模式的底层行为。一、核心特性一览react-hook-form 是一个以 React Hooks 为基石的表单状态管理与验证库原文档将其设计目标概括为三点性能performance、用户体验UX与开发体验DX。围绕这三大目标其核心特性包括拥抱原生 HTML 表单验证required、pattern、min、max等规则直接映射浏览器原生校验语义并允许通过配置启用/禁用原生校验提示与 UI 组件库开箱即用集成通过Controller/useController包装任意受控组件使其接入统一的表单状态管理体积小、零运行时依赖package.json中只有devDependencies与peerDependencies没有任何运行时dependencies且 bundlewatch 配置 将打包产物dist/index.cjs.js的目标体积约束在 15.0 kB 以内该配置为压缩产物上限具体数值随构建方式略有差异丰富的第三方校验器支持原生支持 Yup、Zod、AJV、Superstruct、Joi、Vest、class-validator、io-ts、nope 以及自定义校验 resolver。从源码角度看以上能力统一由 src/useForm.ts 暴露的useFormhook 提供——它内部通过createFormControl见 src/logic/createFormControl.ts创建表单控制实例并基于订阅机制实现状态分发与按需渲染这也是其性能设计的关键详见下文“源码视角”一节。仓库对外导出的全部 API 集中在 src/index.ts涵盖useForm、useFieldArray、useWatch、useFormContext、Controller、ErrorMessage等。二、安装原文档给出的安装命令为npm install react-hook-form当前仓库package.json中版本为7.88.0见 package.json并声明了模块入口main指向 CJS 产物、module指向 ESM 产物同时通过exports字段为import/require/react-server环境分别提供对应产物package.json。需要关注的两个环境前提React 版本peerDependencies声明为react: ^16.8.0 || ^17 || ^18 || ^19package.json即要求 React 16.8Hooks 引入版本兼容 React 17/18/19Node 版本engines声明node 18.0.0package.json使用现代工具链时需满足该版本要求。如果使用 pnpm 或 yarn命令对应替换为pnpm add react-hook-form或yarn add react-hook-form即可。三、快速开始最小可用示例原文档提供了一段可直接运行的快速入门示例这是理解 react-hook-form 核心用法的关键代码下面完整复现并逐行解读import React from react; import { useForm } from react-hook-form; function App() { const { register, handleSubmit, formState: { errors }, } useForm(); const onSubmit (data) console.log(data); return ( form onSubmit{handleSubmit(onSubmit)} input {...register(firstName)} / input {...register(lastName, { required: true })} / {errors.lastName pLast name is required./p} input {...register(age, { pattern: /\d/ })} / {errors.age pPlease enter a number for age./p} input typesubmit / /form ); }这段代码展示了四个核心概念useForm()创建表单控制实例返回register、handleSubmit与formState。从源码看useForm内部通过React.useRef缓存表单控制实例保证重渲染时复用同一控制对象src/useForm.ts。register(name, options?)注册字段。name支持点路径如user.firstName与数组索引如items[0].name嵌套结构第二个参数传入验证规则对象。handleSubmit(onSubmit)绑定到form的onSubmit。它会先执行全表单验证通过后才调用传入的onSubmit(data)回调回调参数为规范化后的表单数据验证失败时则不会触发提交回调。formState.errors按字段名存储验证错误的对象errors.lastName在对应字段校验失败时存在可直接驱动 UI 渲染错误提示。仓库中的完整可运行版本见 app/src/basic.tsx它覆盖了嵌套字段nestItem.nest1、数组字段arrayItem.0.test1、单选、复选、下拉框与多选框等几乎全部原生控件类型V7 目录下另有更精简的入门示例 examples/V7/basic.tsx。3.1 register 验证选项的完整类型register的第二个参数在类型层面定义为RegisterOptions见 src/types/validator.ts完整选项如下选项类型说明requiredMessage \| ValidationRuleboolean必填校验可传布尔值或{ value, message }自定义错误消息minValidationRulenumber \| string最小值/最小日期字符串日期同样适用maxValidationRulenumber \| string最大值/最大日期minLengthValidationRulenumber最小长度maxLengthValidationRulenumber最大长度patternValidationRuleRegExp正则匹配validateValidate \| Recordstring, Validate自定义校验函数支持异步与返回 Promise或为多个校验规则命名valueFieldPathValue预设字段值setValueAs(value: any) any值转换函数在存储前对原始输入做格式化shouldUnregisterboolean字段卸载时是否注销onChange/onBlur(event) void事件钩子disabledboolean禁用字段depsFieldPath \| FieldPath[]依赖字段依赖变化时触发本字段重新验证valueAsNumberboolean将输入转换为number类型存储valueAsDateboolean将输入转换为Date类型存储其中ValidationRuleT既接受原始值如required: true、min: 10也接受{ value, message }对象形式用于自定义错误消息src/types/validator.ts。3.2 验证规则的执行顺序内置规则的执行顺序由 src/constants.ts 中的INPUT_VALIDATION_RULES常量确定max → min → maxLength → minLength → pattern → required → validate。即先校验数值/长度边界类规则再校验必填与正则最后执行自定义validate函数——validate永远拥有最终决定权。四、内置验证规则详解与示例原文档快速示例中仅用到required与pattern而仓库 app/src/basic.tsx 提供了全部规则的实战写法以下逐一展开// 必填 最大长度字符串数字混用 input {...register(lastName, { required: true, maxLength: 5 })} / // 数值范围typenumber input typenumber {...register(min, { min: 10 })} / input typenumber {...register(max, { max: 20 })} / // 日期范围typedate字符串比较 input typedate {...register(minDate, { min: 2019-08-01 })} / input typedate {...register(maxDate, { max: 2019-08-01 })} / // 长度校验 input {...register(minLength, { minLength: 2 })} / // 正则校验 input {...register(pattern, { pattern: /\d/ })} / // 自定义校验返回 false 表示不通过返回字符串可作为错误消息 input {...register(validate, { validate: (value) value test, })} /4.1 单选框、复选框与多选框同一name注册多个 radio 即构成单选组checkbox 可单独注册值为true/false也可多个同name注册形成数组值select multiple则收集选中项为数组// 单选组 input typeradio {...register(radio, { required: true })} value1 / input typeradio {...register(radio)} value2 / // 复选数组 input typecheckbox value1 {...register(checkboxArray, { required: true })} / input typecheckbox value2 {...register(checkboxArray, { required: true })} / // 多选下拉 select multiple {...register(multiple, { required: true })} option valueoptionAoptionA/option option valueoptionBoptionB/option /select上述控件在提交时会由内部逻辑getRadioValue.ts、getCheckboxValue.ts分别聚合为单一值或数组最终提交的数据结构与 e2e 测试中的断言一致见 e2e/basic.spec.tsradio: 1、checkboxArray: [3]、multiple: [optionA, optionB]。4.2 嵌套字段与数组字段register的name天然支持路径表达式input {...register(nestItem.nest1, { required: true })} / {errors.nestItem?.nest1 pnest 1 error/p} input {...register(arrayItem.0.test1, { required: true })} / {errors.arrayItem?.[0]?.test1 parray item 1 error/p}错误对象同样按路径嵌套读取时需使用可选链避免深层路径访问报错。字段值类型定义在 src/types/fields.ts其路径类型基于 src/types/path 实现可在 TypeScript 下获得完整的字段名类型提示。五、接入第三方 Schema 校验器原文档明确列出对Yup、Zod、AJV、Superstruct、Joi、Vest、class-validator、io-ts、nope等校验库的支持以及“自定义构建”custom resolver的能力。其接入方式统一通过useForm的resolver配置项import { useForm } from react-hook-form; import { zodResolver } from hookform/resolvers/zod; import { z } from zod; const schema z.object({ firstName: z.string().min(1, First name is required), age: z.coerce.number().min(18), }); function App() { const { register, handleSubmit, formState: { errors }, } useForm({ resolver: zodResolver(schema), }); return ( form onSubmit{handleSubmit((data) console.log(data))} input {...register(firstName)} / {errors.firstName p{errors.firstName.message}/p} input typenumber {...register(age)} / {errors.age p{errors.age.message}/p} input typesubmit / /form ); }resolver的底层协议定义在 src/types/resolvers.ts一个 resolver 接收values、context与options含criteriaMode、names、fields等返回{ values, errors }或 Promise 形式的结果。schema 校验得到的错误消息会通过 schemaErrorLookup.ts 映射回各字段的errors对象与内置规则产出的错误形态完全一致。仓库根目录的package.json的devDependencies中可见zod: ^3.25.76package.json可用于本地验证该流程完整 schema 校验示例见 examples/V7/validationSchema.tsx 与 app/src/basicSchemaValidation.tsx。六、验证触发模式mode / reValidateMode原文档未显式展开验证模式但这是快速入门后必知的核心配置。useForm支持通过mode配置首次验证触发时机可选值定义在 src/constants.tsmode行为onSubmit默认仅在提交时验证onBlur字段失焦时验证onChange字段值变化时验证onTouched字段首次交互聚焦后失焦后验证allblur 与 change 都验证此外reValidateMode可配置错误后的重新验证时机默认为onChange。这些模式的行为在 e2e/basic.spec.ts 中有完整的 Playwright 端到端测试佐证onSubmit 模式e2e/basic.spec.ts提交空表单后全部必填字段错误同时出现且首个错误字段nestItem.nest1自动获得焦点onTouched 模式e2e/basic.spec.ts字段仅在“聚焦又失焦”后才显示错误单纯输入内容不触发校验onBlur 模式e2e/basic.spec.ts失焦即校验onChange 模式e2e/basic.spec.ts输入过程中实时校验。验证模式对性能的影响选择onChange/all意味着每次输入都触发校验计算重渲染更频繁而默认的onSubmit将校验集中在提交时刻配合 react-hook-form 的订阅式状态分发表单控制层按需推送状态见 src/logic/createFormControl.ts 与 shouldRenderFormState.ts能最大限度减少不必要的组件重渲染。e2e 测试中通过#renderCount断言渲染次数也印证了这一特性e2e/basic.spec.ts。七、源码视角useForm 与验证流程为了深入理解“为什么快”可以顺着两条关键链路阅读源码表单控制层useForm在首次渲染时通过createFormControl创建控制实例src/useForm.ts实例内部维护字段注册表_fields、表单状态_formState与订阅者_subjects。useForm通过useIsomorphicLayoutEffect订阅状态变更仅当被订阅的formState片段变化时才触发重渲染src/useForm.ts。字段验证层每次提交或触发校验时validateField.ts 按顺序执行min/max/minLength/maxLength/pattern/required/validate规则appendErrorssrc/logic/appendErrors.ts负责在criteriaMode开启时收集全部失败规则getValidateErrorsrc/logic/getValidateError.ts将自定义校验函数返回的字符串/布尔值规范化为错误对象。仓库提供了全面的测试覆盖单元测试位于 src/tests/logic含 validateField.test.tsx、getValidationModes.test.ts 等useForm行为测试位于 src/tests/useForm端到端测试位于 e2e。阅读这些测试是深入理解各 API 行为最快的方式。八、更多进阶资源原文档顶部提供了“开始使用 / API / 示例 / 演示 / 表单构建器 / 常见问题”等导航入口对应官方文档站本仓库内可直接查阅的补充资料包括基础示例app/src/basic.tsx、examples/V7/basic.tsxSchema 校验app/src/basicSchemaValidation.tsx、app/src/customSchemaValidation.tsx字段数组app/src/useFieldArray.tsx、examples/V7/FieldArray.tsx状态订阅app/src/useFormState.tsx、app/src/useWatch.tsxController 集成app/src/controller.tsx、examples/V7/customInput.tsx表单重置app/src/reset.tsx、examples/V7/resetForm.tsxAPI 类型报告reports/api-extractor.api.md本文所有代码示例均可直接复制运行需配合 React 16.8 环境更详细的 API 说明可进一步阅读 src/types 下的类型定义或对照 src/tests中的测试用例理解各 API 的边界行为。【免费下载链接】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），仅供参考