react-hook-form 快速上手与验证机制全解析：安装、register 注册、handleSubmit 提交与内置校验规则实战指南

react-hook-form 快速上手与验证机制全解析安装、register 注册、handleSubmit 提交与内置校验规则实战指南【免费下载链接】react-hook-form React Hooks for form state management and validation (Web React Native)项目地址: https://gitcode.com/gh_mirrors/re/react-hook-formReact Hook Formreact-hook-form是一个以 React Hooks 为核心的表单状态管理与校验库官方定位为“Güçlü, esnek ve genişletilebilir, kolay doğrulama özelliğine sahip formlar”强大、灵活、可扩展且具备易用验证能力的表单库。本文以仓库内的土耳其语版 READMEdocs/README.tr-TR.md为骨架逐项展开安装方式、快速上手示例、register/handleSubmit的底层工作原理并结合当前仓库源码V7 系列深入剖析required、pattern、min/max、minLength/maxLength、validate等内置验证规则的执行细节最后给出 Yup/Joi/Superstruct 等 Schema 验证库集成与 UI 组件库Controller的实战方案。读完本文你将能独立搭建一个带完整校验、提交与错误回显的表单并理解其背后的状态管理机制。一、react-hook-form 核心特性速览原 README 开篇即列出该库的设计目标这些特性也是它在众多表单方案中脱颖而出的根本原因特性原文说明Performans ve geliştirici deneyimi gözetilerek yazılmıştır以性能Performance与开发者体验DX为首要目标编写Kontrolsüz form doğrulamasını kabul eder拥抱非受控表单uncontrolled校验减少不必要的重渲染Arayüz Kütüphaneleri ile kolay entegrasyon可轻松与各类 UI 组件库如 Material-UI、Ant Design集成Herhangi bir bağımlılık olmadan ufak boyut无任何第三方运行时依赖包体积小巧Validasyon için HTML standartlarını takip eder校验遵循 HTML 原生表单标准React Native ile uyumludur兼容 React Native一套逻辑跨 Web 与移动端Yup、Joi、Superstruct ya da kişisel validasyonlarınızı destekler支持 Yup、Joi、Superstruct 或自定义校验方案Form Oluşturucu ile formları hızlıca oluşturabilirsiniz可通过可视化 Form Builder 快速生成表单从仓库现状看这些特性均有代码佐证无依赖package.json 中dependencies字段为空全部依赖均为devDependencies仅用于测试与构建peerDependencies只要求react ^16.8.0 || ^17 || ^18 || ^19这正是其“零运行时依赖”的根基。遵循 HTML 校验标准INPUT_VALIDATION_RULES见 src/constants.ts将max、min、maxLength、minLength、pattern、required、validate与原生表单规则一一对应。React Native / 服务端兼容仓库同时维护了 src/index.react-server.ts 等服务端入口并在exports中通过react-server条件导出见 package.json。二、安装一行命令开始使用原 README 给出的安装命令非常简单npm install react-hook-form基于当前仓库的工程实践还可以补充以下几种安装方式# pnpm仓库自身使用 pnpm 管理见 pnpm-lock.yaml pnpm add react-hook-form # yarn yarn add react-hook-form安装前需要注意的环境前提以当前仓库 package.json 为准Node.js 版本engines声明要求node 18.0.0React 版本peerDependencies声明支持react ^16.8.0 || ^17 || ^18 || ^19即 React 16.8 以上Hooks 可用即可当前仓库版本本仓库对应react-hook-form7.88.0使用现代 Rollup 构建产出 ESMdist/index.esm.mjs与 CJSdist/index.cjs.js双格式产物。三、快速开始从官方示例理解三步核心 API原 README 的 Hızlı Başlangıç快速开始示例是理解react-hook-form的最佳入口它完整展示了useForm、register、handleSubmit、errors四个核心概念import React from react; import { useForm } from react-hook-form; function App() { const { register, handleSubmit, errors } useForm(); // initialize 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 ); }这个示例虽短却蕴含了三个关键 API 的完整用法useForm()初始化表单控制实例返回一系列表单方法与状态register注册输入控件可传入验证规则如{ required: true }、{ pattern: /\d/ }handleSubmit(onSubmit)在表单提交时先执行校验校验通过后才调用onSubmit(data)。版本说明重要上述示例是 README 翻译时对应的 V6 时代写法ref{register}、errors直接解构。当前仓库已是 V7 版本官方主 READMEREADME.md推荐的新写法为{...register(firstName)}展开式且errors需从formState中解构。二者功能等价V7 写法如下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 ); }仓库中的完整可运行示例可参考 examples/V7/basic.tsxV7 风格与 examples/V6/basic.tsxV6 风格另有配套的 Playwright 端到端测试 e2e/basic.spec.ts 验证该流程。3.1 register 的底层实现它到底做了什么从源码看register定义在 src/logic/createFormControl.tsconst register: UseFormRegisterTFieldValues (name, options {}) { let field get(_fields, name); // ... 将字段写入 _fields 内部注册表标记 mount set(_fields, name, { ...(field || {}), _f: { ...(field field._f ? field._f : { ref: { name } }), name, mount: true, ...options }, }); _names.mount.add(name); // ... return { // ... name, onChange, onBlur: onChange, ref: (ref) { // ref 回调真实 DOM 挂载后完成字段引用收集 }, }; };从实现可以推断出几个关键机制register(name, options)会把字段名与规则写入内部的_fields注册表并将mount置为true标记字段已挂载返回对象中除name外还有onChange、onBlur两者指向同一个内部onChange处理器以及ref回调函数——这就是 V6 时代ref{register}与 V7 时代{...register(name)}两种写法都能工作的原因ref回调会在真实 DOM 挂载时被 React 调用库在此收集元素引用fieldRef对 radio/checkbox 这类多元素控件还会维护refs数组见 src/logic/createFormControl.ts。3.2 handleSubmit 的完整执行链路handleSubmit的实现位于 src/logic/createFormControl.ts其执行流程是阻止默认行为若事件对象存在先调用e.preventDefault()标记提交中通过_subjects.state.next({ isSubmitting: true })广播状态触发formState.isSubmitting变为true执行校验若配置了resolverSchema 校验调用_runSchema()获取{ errors, values }否则调用executeBuiltInValidation执行内置验证规则处理禁用字段若存在disabled字段从提交值中移除unset(fieldValues, name)分支处理无错误调用onValid(fieldValues, e)若其抛出异常会记录到onValidError有错误调用可选的onInvalid(errors, e)并执行_focusError()将焦点移到第一个出错字段收尾更新广播isSubmitted: true、isSubmitting: false、isSubmitSuccessful无错误且 onValid 未抛错、submitCount 1等状态。对应测试可查看 src/tests/useForm/handleSubmit.test.tsx其中覆盖了异步校验、onInvalid 回调、submitCount 递增等场景。四、内置验证规则深度解析原 README 的快速开始示例中用到了required与pattern两个规则但这只是react-hook-form内置验证能力的冰山一角。全部内置规则定义在 src/constants.tsexport const INPUT_VALIDATION_RULES { max: max, min: min, maxLength: maxLength, minLength: minLength, pattern: pattern, required: required, validate: validate, } as const;而规则的真正执行逻辑集中在 src/logic/validateField.ts它是一个async函数对每个字段按顺序执行各规则的检查。下面逐一解读4.1 required必填校验if (required (!isRadioOrCheckbox (isEmpty || isNullOrUndefined(inputValue))) || ...) { const { value, message } isString(required) ? { value: !!required, message: required } : getValueAndMessage(required); error[name] { type: INPUT_VALIDATION_RULES.required, message, ref: inputRef, ... }; }要点对应 src/logic/validateField.tsrequired可以是布尔值也可以是字符串此时字符串直接作为错误消息例如register(lastname, { required: Soyad zorunludur. })对 checkbox 使用getCheckboxValue(refs).isValid判断是否有勾选项对 radio 使用getRadioValue(refs).isValid判断是否选中错误对象结构为{ type, message, ref }type即规则名如requiredmessage为用户可读消息。4.2 min / max数值与日期范围校验src/logic/validateField.ts 中min/max的处理较为特殊当值可被当作数字比较时!isNaN(inputValue)使用ref.valueAsNumber或inputValue转数字后比较当输入类型为date/time/week时自动转换为Date对象比较time类型还会把“HH:mm”拼接到当天日期后比较支持同时传入自定义消息{ min: { value: 18, message: Yaş en az 18 olmalı } }。4.3 minLength / maxLength长度校验if ((maxLength || minLength) !isEmpty (isString(inputValue) || (isFieldArray Array.isArray(inputValue)))) { const exceedMax !isNullOrUndefined(maxLengthOutput.value) inputValue.length maxLengthOutput.value; const exceedMin !isNullOrUndefined(minLengthOutput.value) inputValue.length minLengthOutput.value; ... }见 src/logic/validateField.ts。注意长度校验仅对字符串生效但在isFieldArray字段数组场景下也支持对数组长度进行校验。4.4 pattern正则模式校验if (pattern !isEmpty isString(inputValue)) { const { value: patternValue, message } getValueAndMessage(pattern); if (isRegex(patternValue) !inputValue.match(patternValue)) { error[name] { type: INPUT_VALIDATION_RULES.pattern, message, ref, ... }; } }见 src/logic/validateField.ts。快速开始中的{ pattern: /\d/ }即校验“age 字段必须是数字”。4.5 validate自定义校验函数同步 / 异步 / 多规则validate是最灵活的规则支持三种形态见 src/logic/validateField.ts// ① 单函数返回 true 通过返回字符串则视为错误消息 input {...register(username, { validate: (value) value ! admin || Bu kullanıcı adı kullanılamaz, })} / // ② 异步校验返回 Promise input {...register(email, { validate: async (value) (await checkEmailExists(value)) || Email zaten kayıtlı, })} / // ③ 对象形式多个独立校验器错误 type 为对象键名 input {...register(password, { validate: { hasNumber: (v) /\d/.test(v) || En az bir rakam içermeli, hasUpper: (v) /[A-Z]/.test(v) || En az bir büyük harf içermeli, }, })} /从源码可以确认validate支持同步函数与异步函数await validate(inputValue, formValues)也支持对象形式的多个校验器每次校验都会收到当前字段值与整个表单的值formValues便于做跨字段关联校验。4.6 校验触发时机与 criteriaModereact-hook-form支持灵活的校验触发时机定义在 src/constants.tsexport const VALIDATION_MODE { onBlur: onBlur, onChange: onChange, onSubmit: onSubmit, onTouched: onTouched, all: all, } as const;可通过useForm({ mode: onChange })指定首次校验时机通过reValidateMode指定再次校验时机。默认值见 src/logic/createFormControl.tsmode默认onSubmitreValidateMode默认onChange。此外若希望同一字段的全部失败规则都被记录而非只记第一条可开启criteriaMode: all此时validateField会通过appendErrors见 src/logic/appendErrors.ts把多条错误追加到error[name].types中。4.7 表单状态DEFAULT_FORM_STATEuseForm返回的formState初始结构定义于 src/logic/createFormControl.tsexport const DEFAULT_FORM_STATE { submitCount: 0, isDirty: false, isReady: false, isValidating: false, isSubmitted: false, isSubmitting: false, isSubmitSuccessful: false, isValid: false, touchedFields: {}, dirtyFields: {}, validatingFields: {}, };这些状态在 src/useForm.ts 中被初始化并通过订阅机制control._subscribe在字段变化、提交、校验时更新。仓库app/src/formState.tsx与 e2e/formState.spec.ts 提供了formState各字段的完整演示与验证。五、Schema 校验与 UI 库集成原 README 明确提到支持 Yup、Joi、Superstruct 以及自定义校验方案。在当前仓库中这类第三方校验库通过resolver机制接入import { useForm } from react-hook-form; // 以 yup 为例需配合 hookform/resolvers 使用 const schema yup.object({ firstName: yup.string().required(), age: yup.number().positive().integer(), }); const { register, handleSubmit, formState: { errors } } useForm({ resolver: yupResolver(schema), });从源码看resolver的调用链路为handleSubmit→_runSchema()→_options.resolver(formValues, context, getResolverOptions(...))见 src/logic/createFormControl.ts返回{ errors, values }后写入_formState.errors。仓库示例可参考examples/V7/validationSchema.tsxV7 版 Schema 校验examples/V6/validationSchema.tsxV6 版类型定义见 src/types/resolvers.tsUI 组件库集成对于 Material-UI、Ant Design 这类不暴露原生 ref 的受控组件需使用Controller。其实现非常精简src/controller.tsxexport const Controller TFieldValues, TName, TTransformedValues( props: ControllerPropsTFieldValues, TName, TTransformedValues, ) props.render(useControllerTFieldValues, TName, TTransformedValues(props));即Controller本质是useController的 render-prop 封装通过render函数把{ field, fieldState }交给你的自定义组件import { Controller, useForm } from react-hook-form; function App() { const { control, handleSubmit } useForm(); return ( form onSubmit{handleSubmit((data) console.log(data))} Controller control{control} namefirstName render{({ field }) MyInput value{field.value} onChange{field.onChange} /} / input typesubmit / /form ); }对应测试位于 src/tests/controller.test.tsxuseController实现见 src/useController.ts。六、动态字段列表useFieldArray对于动态增删的表单列表如“添加用户”可配合useFieldArray。仓库示例 examples/V7/useFieldArraySimpleExample.tsx 给出了最小可运行版本import React from react; import { useForm, useFieldArray } from react-hook-form; export default function UseFieldArraySimpleExample() { const { register, control, handleSubmit } useForm({ defaultValues: { users: [{ name: }] }, }); const { fields, append } useFieldArray({ control, name: users }); const onSubmit (data) console.log(data); return ( form onSubmit{handleSubmit(onSubmit)} {fields.map((field, index) ( input key{field.id} {...register(users.${index}.name)} placeholder{User ${index 1}} / ))} button typebutton onClick{() append({ name: })} Add User /button input typesubmit / /form ); }useFieldArray提供fields、append、prepend、insert、remove、swap、move、update、replace等操作每个操作在 src/tests/useFieldArray/ 下均有独立测试文件append.test.tsx、remove.test.tsx、swap.test.tsx等覆盖。七、React Native 与其他运行环境原 README 承诺“React Native ile uyumludur”与 React Native 兼容。从仓库结构看核心逻辑src/logic/ 与 src/utils/全部为纯 TypeScript 实现与 DOM 解耦仅有少量环境判断如 src/utils/isWeb.ts区分 Web / 非 Web 环境useIsomorphicLayoutEffectsrc/useIsomorphicLayoutEffect.ts针对服务端渲染SSR做了useLayoutEffect回退处理仓库还维护了 React Server 组件入口 src/index.react-server.ts并在 package.json 中通过条件导出react-server支持。因此在 Web 之外同样的useForm/ControllerAPI 也适用于 React Native 与服务端渲染场景。八、在仓库中继续深入示例、测试与文档如果你想在本仓库中亲手验证上述所有内容官方准备了完备的示例、Demo 与测试可运行示例examples/V7/ 与 examples/V6/ 目录下覆盖 basic、conditionalFields、customValidation、defaultValues、dirtyTouchedSubmitted、fieldArrayMinLength、formProvider、nestedFields、validationOnFieldBlur、validationOnFieldChange、validationSchema 等场景交互式 Demo 应用app/src/ 是 Vite 构建的演示项目包含basic.tsx、basicSchemaValidation.tsx、controller.tsx、useFieldArray.tsx、useWatch.tsx、setValue.tsx等 40 个独立场景页面对应 e2e/ 下的 Playwright 端到端测试如 e2e/basic.spec.ts、e2e/useFieldArray.spec.ts可用pnpm e2e运行单元测试src/tests/ 中按useForm、useFieldArray、logic、utils分类组织了数百个测试用例是理解各 API 行为边界的权威资料类型测试src/typetest/ 以tsd风格验证 TypeScript 类型推导form.test-d.ts、fieldArray.test-d.ts、watch.test-d.ts等多语言文档除本文依据的土耳其语版 docs/README.tr-TR.md 外仓库还提供简体中文 docs/README.zh-CN.md、繁体中文 docs/README.zh-TW.md、日文 docs/README.ja-JP.md、韩文 docs/README.ko-KR.md 等十余种语言版本以及 V6 时代文档 docs/README.V6.md 和 V7 中文文档 docs/README.V7.zh-CN.md 可供对照阅读。结语从npm install react-hook-form到register注册控件、handleSubmit提交表单再到required、pattern、validate等内置规则与 Yup/Controller/useFieldArray 的扩展生态react-hook-form以极小的 API 面覆盖了表单开发的绝大多数场景。本文依据 docs/README.tr-TR.md 的骨架逐层深入 src/useForm.ts、src/logic/createFormControl.ts、src/logic/validateField.ts 等核心源码希望你在阅读后不仅能“会用它”更能“理解它为什么这样设计”——这也是该库始终强调性能与开发者体验的初衷。【免费下载链接】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），仅供参考