React Hook Formreact-hook-form快速上手指南基于 Hooks 的表单状态管理与验证Web React Native【免费下载链接】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.pt-BR.md葡萄牙语版官方 README为骨架结合仓库源码与测试深入展开讲解 React Hook Form 的核心功能、安装方式与快速上手用法。读完本文你将掌握如何用useForm的register、handleSubmit、errors完成非受控表单的注册与验证了解其验证规则的底层实现并能在 Web 与 React Native 项目中直接落地。一、认识 React Hook FormReact Hook Form 是 React 生态中一个基于 Hooks 的表单状态管理与验证库本仓库 package.json 描述为Performant, flexible and extensible forms library for React Hooks。它的设计初衷是用最少的代码、最小的包体积完成表单注册、取值、验证与提交。官方葡萄牙语文档 docs/README.pt-BR.md 将其核心能力概括为以下特性以性能与开发者体验为优先Construído com performance e experiência do desenvolvedor em mente——尽量减少不必要的组件重渲染非受控表单验证Validação de formulários incontrolados——核心 API 走非受控路径输入值由 DOM 自行持有表单库只负责读取与验证改善受控表单性能Melhore o desempenho do formulário controlado——当需要受控组件如与 UI 库集成时通过Controller提供更高效的桥接体积小、零依赖Baixo custo sem nenhuma dependência遵循 HTML 标准验证规范Segue as normas padrões de validação HTML——required、min、max、minLength、maxLength、pattern等规则均对应原生表单语义兼容 React NativeCompatível com React Native支持 [Yup]、[Joi]、[Superstruct] 或自定义验证方案Suporta Yup, Joi, Superstruct ou personalizado原生支持浏览器内置验证Suporte nativo a validação do navegador可搭配 Form Builder 快速构建Possibilita construção rápida com form builder。从当前仓库源码看这些特性均可在 src 目录下得到印证核心 Hook 实现在 src/useForm.ts 与 src/logic/createFormControl.ts验证规则实现在 src/logic/validateField.ts可复用的工具函数位于 src/utils。二、安装官方文档给出的安装方式为 npm$ npm install react-hook-form仓库内同时提供了pnpm工作区pnpm-workspace.yaml因此也可以使用pnpm add react-hook-form。以本仓库开发环境为例运行pnpm install后通过pnpm start即可启动示例应用见 package.json 的start脚本先构建 ESM 产物再进入 app 目录启动 Vite 开发服务器。几点安装相关的实际约束来自 package.jsonReact 版本peerDependencies声明为react: ^16.8.0 || ^17 || ^18 || ^19即要求 React 16.8Hooks 特性引入版本及以上Node 版本engines声明node 18.0.0包导出通过exports字段区分importESMdist/index.esm.mjs、requireCJSdist/index.cjs.js与react-serverdist/react-server.esm.mjs三种入口源码入口为 src/index.ts。三、快速上手useForm三件套官方文档给出了一个极简的快速开始示例docs/README.pt-BR.md 的Começo rápido一节下面先原样展示再逐行解读import React from react; import { useForm } from react-hook-form; function App() { const { register, handleSubmit, errors } useForm(); // initialise the hook const onSubmit (data) { console.log(data); }; return ( form onSubmit{handleSubmit(onSubmit)} input namefirstname ref{register} / {/* register an input */} input namelastname ref{register({ required: true })} / {errors.lastname Last name is required.} input nameage ref{register({ pattern: /\d/ })} / {errors.age Please enter number for age.} input typesubmit / /form ); }这个例子虽然来自旧版 APIerrors直接解构、ref{register}写法但它完整呈现了 React Hook Form 的三步核心用法register注册字段把输入框的ref交给register该字段即被纳入表单管理提交时可被读取、可被验证handleSubmit包裹提交逻辑所有字段验证通过后才调用onSubmit(data)验证失败则不会提交errors读取错误以字段名为键条件渲染错误提示。3.1 当前版本V7的等价写法当前仓库已是 v7 版本package.json 中版本号为7.88.0官方英文 READMEREADME.md与 V7 版本文档docs/README.V7.zh-CN.md、docs/README.V7.ja-JP.md给出了新版写法差异有两点errors移动到了formState下formState: { errors }register从“接收 ref”改为“展开到输入框”{...register(firstName)}。等价代码为import { useForm } from react-hook-form; function App() { const { register, handleSubmit, formState: { errors }, } useForm(); return ( form onSubmit{handleSubmit((data) console.log(data))} 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 ); }本仓库 app/src/basic.tsx 中的示例页面就是这种写法的完整演示它注册了firstNamerequired、lastNamerequiredmaxLength: 5、min数字最小值 10、max数字最大值 20、minDate/maxDate日期范围、minLength、pattern: /\d/、radio、checkbox、多选select、自定义validate等多种规则并展示了嵌套字段nestItem.nest1与数组字段arrayItem.0.test1的注册方式——字段名使用点号路径即可映射到嵌套数据结构。3.2useForm返回的核心成员以当前仓库 src/useForm.ts 的实现为准useForm的返回值由 src/logic/createFormControl.ts 中的createFormControl创建主要成员包括成员作用register注册受管字段接收字段名与验证规则handleSubmit包装提交回调验证通过才触发onSubmitformState.errors字段错误对象键为字段名formState其他成员isDirty、isValid、isSubmitting、touchedFields等表单状态watch/getValues/setValue读取与写入字段值reset重置表单含resetOptionstrigger手动触发字段验证setError/clearErrors手动设置/清除错误setFocus聚焦指定字段control用于Controller、useWatch、useFormState等高级 API3.3handleSubmit的第二个参数handleSubmit除了接收成功回调还接收验证失败时的回调。以 app/src/basic.tsx 为例const [onInvalidCalledTimes, setOnInvalidCalledTimes] useState(0); const onInvalid () setOnInvalidCalledTimes((prevCount) prevCount 1); form onSubmit{handleSubmit((data) { setData(data); }, onInvalid)} onInvalid会在字段验证不通过时被调用这在需要统计校验失败、打点埋点或展示全局错误时非常实用。对应的端到端测试见 e2e/basic.spec.ts。四、验证规则详解结合源码官方文档提到 React Hook FormSegue as normas padrões de validação HTML遵循 HTML 标准验证规范。这些规则的底层实现集中在 src/logic/validateField.ts规则常量定义在 src/constants.tsexport const INPUT_VALIDATION_RULES { max: max, min: min, maxLength: maxLength, minLength: minLength, pattern: pattern, required: required, validate: validate, } as const;各规则的核心行为均可从 validateField.ts 源码验证required值为true或字符串消息。对普通输入框判空空字符串、undefined、null均视为空对复选框要求至少勾选一项通过getCheckboxValue判断对单选框要求有选中项通过getRadioValue判断布尔值字段要求为true。若required传字符串该字符串会作为错误消息见isString(required)分支min/max针对数字与日期。源码中优先使用inputRef.valueAsNumber转数字比较非数字场景typedate、typetime、typeweek则按日期/时间语义比较见 validateField.ts 第 132–190 行的分支逻辑minLength/maxLength对字符串计算inputValue.length比较对useFieldArray场景还可作用于数组长度pattern接收正则表达式对字符串执行inputValue.match(patternValue)判断是否匹配validate接收函数或对象。函数形式签名是(value, formValues) boolean | string | Promise...返回true通过、字符串作为错误消息、false或undefined表示失败由 getValidateError 转为错误对象形式可同时声明多条规则每条以键名为type。验证函数支持异步源码中await validate(inputValue, formValues)可用于远程校验。4.1 错误消息与criteriaMode: all默认情况下字段验证命中第一条失败规则即返回if (!validateAllFieldCriteria) { return error; }。若想收集某个字段的全部失败规则如同时违反required与pattern可在useForm中开启useForm({ criteriaMode: all, })此时errors[fieldName].types会以规则名为键记录所有失败信息。该行为由 src/logic/createFormControl.ts 中的_options.criteriaMode VALIDATION_MODE.all判定并通过appendErrorssrc/logic/appendErrors.ts累积多条错误。4.2 原生浏览器验证shouldUseNativeValidation开启该选项后库会调用输入框的setCustomValidity与reportValidity把验证消息交给浏览器原生 UI 展示见 validateField.ts 中的setCustomValidity内部实现useForm({ shouldUseNativeValidation: true, })注意reportValidity属于浏览器环境 API因此该选项仅在 Web 端生效React Native 中不会使用。4.3 验证时机mode与reValidateMode官方文档强调表单库“以性能优先”其中关键设计就是验证时机可配置。useForm支持两个选项默认值见 createFormControl.ts 第 111–112 行取值常量见 src/constants.ts 的VALIDATION_MODEmode首次验证触发时机默认onSubmit可选onBlur、onChange、onTouched、allreValidateMode再次验证的时机默认onChange即提交失败后用户一修改字段就重新校验。示例对应 app/src/basic.tsx 通过路由参数切换验证模式useForm({ mode: onBlur, // 首次验证在字段失焦时触发 reValidateMode: onChange, // 之后每次变更都重新验证 })这两个选项对应的验证行为在源码中由_validationModeBeforeSubmit/_validationModeAfterSubmit两组模式位控制见 createFormControl.ts 第 201–202 行。五、在真实项目中实践5.1 本仓库的示例应用本仓库提供了一个完整的 Vite React 演示应用app 目录每个 app/src 下的.tsx文件对应一个独立表单场景例如app/src/basic.tsx基础验证规则全覆盖app/src/controller.tsxController桥接受控组件app/src/useFieldArray.tsx动态字段数组app/src/useWatch.tsx 与 app/src/watch.tsx订阅字段值变化app/src/setValue.tsx / app/src/reset.tsx / app/src/setFocus.tsx命令式更新与重置app/src/basicSchemaValidation.tsx基于 SchemaResolver的验证。每个场景都配有对应的 Playwright 端到端测试e2e 目录如 e2e/basic.spec.ts、e2e/useFieldArray.spec.ts是学习各 API 实际行为的绝佳参照。5.2 经典示例合集仓库 examples 目录下按 V6 / V7 两个版本整理了大量可直接复用的示例例如examples/V7/basic.tsxV7 快速开始examples/V7/basicValidation.tsx基础验证examples/V7/conditionalFields.tsx条件字段examples/V7/customInput.tsx自定义输入组件examples/V7/fieldArrayMinLength.tsx字段数组长度限制examples/V7/validationSchema.tsx外部 Schema 验证。每个示例都短小完整可直接复制进自己的项目对照修改。5.3 与 Schema 验证库Yup / Joi / Superstruct 等集成官方文档明确列出对Yup、Joi、Superstruct 或自定义验证器的支持Suporta Yup, Joi, Superstruct ou personalizado。当前版本的集成方式是通过Resolver机制在useForm中传入resolver选项把 Schema 解析结果翻译成 React Hook Form 的错误结构。import { yupResolver } from hookform/resolvers/yup; import * as yup from yup; const schema yup.object({ name: yup.string().required(Name is required), age: yup.number().min(18).required(), }); useForm({ resolver: yupResolver(schema), });仓库中相关示例见 examples/V7/validationSchema.tsxResolver 的类型定义位于 src/types/resolvers.ts。需要注意Resolver 属于独立的hookform/resolvers生态包本仓库核心包本身不捆绑任何 Schema 库这也与“零依赖”的特性一致。5.4 React Native 场景官方文档声明Compatível com React Native兼容 React Native。实现上的关键差异是React Native 环境没有浏览器 DOM因此原生验证shouldUseNativeValidation与依赖ref.value/reportValidity的能力不可用应使用register的onChange/onBlur回调或Controller进行受控桥接。本仓库的源码与文档docs/README.V7.zh-CN.md也体现了这一点核心逻辑通过isWebsrc/utils/isWeb.ts等工具区分运行环境。六、性能与体积官方文档强调库的特点之一是Baixo custo sem nenhuma dependência体积小、无依赖并*Construído com performance*以性能为构建目标。结合本仓库可验证的事实包括零运行时依赖本仓库 package.json 的dependencies字段为空所有依赖均为devDependencies仅用于构建、测试与类型检查运行时产物不携带第三方包非受控架构通过ref直接读取 DOM 值避免输入框每次击键都触发组件级 re-renderformState使用 Proxy 按需订阅实现见 src/logic/getProxyFormState.ts 与 src/logic/shouldRenderFormState.ts只有被订阅的字段状态变化才触发渲染包体积监控仓库通过bundlewatch对构建产物做体积阈值监控package.json 中bundlewatch配置为dist/index.cjs.js上限 15 kB把体积控制作为发布门禁的一部分。这些机制共同支撑了“性能优先”的定位。仓库还提供了性能相关测试 src/tests/performance.test.tsx 供深入参考。七、更多资源与社区官方文档docs/README.pt-BR.md末尾列出了以下资源入口其中与当前仓库直接对应的部分如下资源说明仓库内对应位置Como iniciar如何开始官方入门教程README.md 快速开始部分API 文档各 API 的完整说明reports/api-extractor.api.md由 API Extractor 生成Exemplos示例可复用的代码示例examples 目录Demonstração演示在线演示本仓库的 app 演示应用FAQA常见问题官方 FAQ—另外本文主题文档还翻译了多语言 README包括简中 docs/README.zh-CN.md、繁中 docs/README.zh-TW.md、日文 docs/README.ja-JP.md、法文 docs/README.fr-FR.md 等非英语读者可对照阅读。八、小结围绕官方葡萄牙语文档 docs/README.pt-BR.md 的核心内容本文覆盖了安装npm install react-hook-form及 React ≥ 16.8、Node ≥ 18 的前置要求快速上手registerhandleSubmiterrors三步用法并给出 V7 版本的等价写法验证规则required、min/max、minLength/maxLength、pattern、validate的行为与源码实现src/logic/validateField.ts高级配置criteriaMode: all、shouldUseNativeValidation、mode/reValidateMode生态集成Resolver 对接 Yup / Joi / SuperstructReact Native 兼容性性能定位零依赖、非受控架构与按需订阅的源码证据。如果你正在为 React 项目挑选表单方案可以直接参照本仓库 examples/V7/basic.tsx 起步再按需查阅 src 源码与 e2e 测试理解底层行为。React Hook Form 的核心哲学始终如一用最少的代码把表单的状态、验证与提交管好。【免费下载链接】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），仅供参考