TanStack Form 自定义错误类型完全指南从字符串到对象掌握任意错误值与类型安全【免费下载链接】form Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/formTanStack Form 是一套 Headless、高性能且类型安全的表单状态管理库覆盖 TS/JS、React、Vue、Angular、Solid 与 Lit 六大框架。在字段与表单校验中错误值的类型是完全自由的字符串只是最常见的形式你还可以返回数字、布尔值、对象、数组甚至任意自定义结构。本文将围绕 docs/framework/react/guides/custom-errors.md 这篇官方指南系统讲解各类错误值的使用方式、disableErrorFlat的底层机制以及errorMap与errors的类型安全保证并结合 form-core 源码与测试用例如 types.ts、FormApi.ts、FieldApi.spec.ts验证其实现细节。读完本文你将掌握校验器返回任意类型错误值 按来源onChange / onBlur / onSubmit分别读取错误 获得编译期完整类型推断这一整套实战能力。一、错误值的通用规则truthy 即错误TanStack Form 对校验器返回值遵循一条简洁且统一的规则任何 truthy 值都被视为错误并会将对应的字段或表单标记为invalid任何 falsy 值false、undefined、null、0、空字符串等表示没有错误字段或表单保持valid。这条规则决定了校验函数的标准写法——满足条件时返回错误值否则返回undefined。由于undefined是 falsy你甚至不需要显式返回null或false这让校验器的收尾语句保持整洁统一。从源码看这一规则体现在错误收集的过滤逻辑中。在 FormApi.ts 中聚合字段错误时使用fieldErrors Object.values(currBaseMeta.errorMap ?? {}).filter( (val) val ! undefined, )即从errorMap的各个来源键中取出所有非undefined的值作为字段当前的错误列表随后再判断字段是否有效const isFieldValid !isNonEmptyArray(fieldErrors)FormApi.ts。所以返回undefined即无错误、返回任意非undefined值即产生错误是整个错误模型的地基。二、字符串错误最常见也最直观字符串错误最易读、最易展示也是日常开发中使用频率最高的形式。2.1 字段级字符串校验form.Field nameusername validators{{ onChange: ({ value }) value.length 3 ? Username must be at least 3 characters : undefined, }} /当value.length 3时校验器返回字符串错误字段进入invalid状态否则返回undefined视为无错误。2.2 表单级校验同时影响多个字段当校验逻辑涉及多个字段例如用户名太短邮箱格式不正确需要同时反馈时可以使用表单级validators并通过fields映射把错误分发到具体字段const form useForm({ defaultValues: { username: , email: , }, validators: { onChange: ({ value }) { return { fields: { username: value.username.length 3 ? Username too short : undefined, email: !value.email.includes() ? Invalid email : undefined, }, } }, }, })这种一个校验函数、多个字段同时出结果的模式适合表达跨字段的联动约束如确认密码、依赖其他字段的取值区间等。在 FieldApi.spec.ts 中可以看到类似的断言表单级onChange校验会同时把errorMap.onChange写入每个子字段并在字段值变化后清除对应错误。2.3 在 UI 中渲染字符串错误字符串错误可以直接放进field.state.meta.errors数组中渲染{ field.state.meta.errors.map((error, i) ( div key{i} classNameerror {error} /div )) }field.state.meta.errors是当前字段所有错误来源聚合后的扁平数组具体聚合机制见下文第四节逐条map即可完整展示。三、非字符串错误值数字、布尔、对象与数组字符串之外TanStack Form 允许校验器返回任意类型。下面逐一给出官方指南中的用法与 UI 展示方式。3.1 数字错误表示数量、阈值或缺口数字错误很适合表达还差多少这类语义。例如年龄校验返回18 - value恰好表示距合格还差几岁form.Field nameage validators{{ onChange: ({ value }) (value 18 ? 18 - value : undefined), }} /在 UI 中TypeScript 会根据校验器推断出errors[0]是数字直接参与文案拼接// TypeScript knows the error is a number based on your validator div classNameerror You need {field.state.meta.errors[0]} more years to be eligible /div注意数字0是 falsy因此这条规则天然规避了已满足条件但误报错误的问题。3.2 布尔错误简单的状态标记当错误本身无需携带文案只需要是否出错这一信号时可以直接返回trueform.Field nameaccepted validators{{ onChange: ({ value }) (!value ? true : undefined), }} /展示时以true作为渲染条件{ field.state.meta.errors[0] true ( div classNameerrorYou must accept the terms/div ) }3.3 对象错误携带结构化信息的富错误返回对象可以在一条错误里携带消息、严重级别、错误码等多个维度便于 UI 分层展示、日志上报或国际化映射form.Field nameemail validators{{ onChange: ({ value }) { if (!value.includes()) { return { message: Invalid email format, severity: error, code: 1001, } } return undefined }, }} /渲染时先通过typeof判断错误是否为对象再按需取用各属性{ typeof field.state.meta.errors[0] object ( div className{error ${field.state.meta.errors[0].severity}} {field.state.meta.errors[0].message} small (Code: {field.state.meta.errors[0].code})/small /div ) }如上例所示渲染出的消息、错误码以及样式如通过severity切换的 CSS class完全取决于你要展示的特定错误事件。3.4 数组错误单个字段的多条错误当一个字段同时违反多条约束时可以在校验器中收集多个错误并一次性返回form.Field namepassword validators{{ onChange: ({ value }) { const errors [] if (value.length 8) errors.push(Password too short) if (!/[A-Z]/.test(value)) errors.push(Missing uppercase letter) if (!/[0-9]/.test(value)) errors.push(Missing number) return errors.length ? errors : undefined }, }} /UI 中以Array.isArray判断并逐条渲染为列表{ Array.isArray(field.state.meta.errors) ( ul classNameerror-list {field.state.meta.errors.map((err, i) ( li key{i}{err}/li ))} /ul ) }四、disableErrorFlat保留错误来源按需读取默认情况下TanStack Form 会把来自所有校验源onChange、onBlur、onSubmit、onMount等的错误拍平成一个errors数组而disableErrorFlat选项则保留错误按来源组织的结构让你能分别读取每一类错误。4.1 配置示例form.Field nameemail disableErrorFlat validators{{ onChange: ({ value }) !value.includes() ? Invalid email format : undefined, onBlur: ({ value }) !value.endsWith(.com) ? Only .com domains allowed : undefined, onSubmit: ({ value }) (value.length 5 ? Email too short : undefined), }} /开启后不同来源的错误被分别保存在field.state.meta.errorMap的对应键下{ field.state.meta.errorMap.onChange ( div classNamereal-time-error{field.state.meta.errorMap.onChange}/div ) } { field.state.meta.errorMap.onBlur ( div classNameblur-feedback{field.state.meta.errorMap.onBlur}/div ) } { field.state.meta.errorMap.onSubmit ( div classNamesubmit-error{field.state.meta.errorMap.onSubmit}/div ) }4.2 底层实现flat(1)的开关disableErrorFlat的实现位于 FormApi.ts在聚合fieldMeta时先通过Object.values(currBaseMeta.errorMap ?? {}).filter((val) val ! undefined)收集所有来源的错误随后if (!fieldInstance || !fieldInstance.options.disableErrorFlat) { fieldErrors fieldErrors.flat(1) }默认未开启disableErrorFlat对错误列表执行flat(1)拍平一层得到合并后的errors数组开启后跳过flat(1)errors数组保持原始嵌套结构。选项的类型定义与文档注释也在源码中给出types.ts/** * Disable the flat(1) operation on field.errors. This is useful if you want to keep the error structure as is. Not suggested for most use-cases. */ disableErrorFlat?: boolean官方注释明确指出该选项对大多数用例并不推荐。也就是说除非你需要保持错误结构原样例如依赖多层嵌套的数组错误否则保持默认的扁平化行为即可。4.3 测试验证FieldApi.spec.ts 中有专门的用例验证该行为当字段以disableErrorFlat: true挂载且表单级onChange校验返回[[Error level 1, Error level 2]]这样的嵌套数组时断言结果expect(field.state.meta.errors).toEqual([ [[Error level 1, Error level 2]], ])即嵌套层级被完整保留、未被拍平直接验证了disableErrorFlat关闭flat(1)的源码逻辑。4.4 典型应用场景按来源拆分错误的能力在以下场景非常有用对不同来源的错误做不同的 UI 处理例如实时输入错误用行内红色文字、失焦错误用气泡提示、提交错误用醒目横幅错误优先级排序例如让提交错误比实时错误展示得更突出渐进式错误披露progressive disclosure先只显示onSubmit错误用户开始输入后切换到onChange错误减少认知负担。五、errors与errorMap的类型安全TanStack Form 的强类型体现在错误处理上errorMap的每个键都精确地具有对应校验器的返回值类型而errors数组则包含所有校验器可能返回的错误值的联合类型。5.1 联合类型驱动的分支渲染form.Field namepassword validators{{ onChange: ({ value }) { // This returns a string or undefined return value.length 8 ? Too short : undefined }, onBlur: ({ value }) { // This returns an object or undefined if (!/[A-Z]/.test(value)) { return { message: Missing uppercase, level: warning } } return undefined }, }} children{(field) { // TypeScript knows that errors[0] can be string | { message: string, level: string } | undefined const error field.state.meta.errors[0] // Type-safe error handling if (typeof error string) { return div classNamestring-error{error}/div } else if (error typeof error object) { return div className{error.level}{error.message}/div } return null }} /由于errors的元素类型是string | { message: string; level: string } | undefined的联合类型通过typeof收窄后分支内的error.message、error.level都能获得完整补全与类型检查。5.2errorMap的逐键精确类型配合disableErrorFlaterrorMap的每个来源键都会精确映射到对应校验器的返回类型// With disableErrorFlat form.Field nameemail disableErrorFlat validators{{ onChange: ({ value }): string | undefined !value.includes() ? Invalid email : undefined, onBlur: ({ value }): { code: number, message: string } | undefined !value.endsWith(.com) ? { code: 100, message: Wrong domain } : undefined }} children{(field) { // TypeScript knows the exact type of each error source const onChangeError: string | undefined field.state.meta.errorMap.onChange; const onBlurError: { code: number, message: string } | undefined field.state.meta.errorMap.onBlur; return (/* ... */); }} /5.3 源码中的类型定义errorMap的类型映射在 types.ts 中定义export type ValidationErrorMap TOnMountReturn unknown, TOnChangeReturn unknown, TOnChangeAsyncReturn unknown, TOnBlurReturn unknown, TOnBlurAsyncReturn unknown, TOnSubmitReturn unknown, TOnSubmitAsyncReturn unknown, ... { onMount?: TOnMountReturn onChange?: TOnChangeReturn | TOnChangeAsyncReturn onBlur?: TOnBlurReturn | TOnBlurAsyncReturn onSubmit?: TOnSubmitReturn | TOnSubmitAsyncReturn onDynamic?: TOnDynamicReturn | TOnDynamicAsyncReturn onServer?: TOnServerReturn }每个来源键onChange、onBlur、onSubmit、onMount、onDynamic、onServer都通过UnwrapFieldValidateOrFn/UnwrapFieldAsyncValidateOrFn工具类型绑定到对应校验器含同步与异步版本的返回值上因此你声明的返回类型会一路流动到meta.errorMap与meta.errors上见 types.ts 中FieldLikeMetaBase对errorMap的定义。此外源码还维护了一个内部的errorSourceMapValidationErrorMapSource见 types.ts用于追踪错误来自同步校验还是异步校验。测试用例也验证了这一行为在 FieldApi.spec.ts 中直接断言field.state.meta.errorMap.onChange精确等于校验器返回的Required字符串而 FieldApi.spec.ts 则验证了setFieldMeta等操作会精确写入、覆盖并保留errorMap中的不同键onChange与onBlur互不影响。5.4 编译期兜底带来的可靠性这种类型安全把错误值的问题从运行时提前到了编译期若某个来源的校验器返回类型发生变化errorMap与errors的类型会同步变化所有使用点会在编译时报错而不是等用户触发校验后才在运行时崩溃分支收窄后error.level、error.message等属性访问都有 IDE 补全与类型检查兜底降低手误概率对协作团队而言校验器返回值本身就是一份错误契约文档数据结构一目了然。六、实践建议与小结综合官方指南与源码实现可以沉淀出以下可直接落地的实践建议优先使用字符串错误简单、易展示、零学习成本覆盖绝大多数场景需要结构化信息时使用对象把消息、错误码、严重级别一起返回UI 与日志都能直接消费多约束校验用数组一次收集多条错误配合errors数组逐条渲染体验优于只报第一条默认保持扁平化仅在确有需要时开启disableErrorFlat源码注释明确提示它不推荐用于大多数用例只有在需要按来源实时 / 失焦 / 提交分别处理或保留嵌套结构时才启用善用类型推断为校验器显式标注返回类型让errorMap与errors的类型精确流动把错误处理的安全边界前移到编译期。TanStack Form 的任意类型错误值设计配合errorMap按来源组织与disableErrorFlat的扁平化开关构成了一个灵活而严谨的错误处理体系既有运行时的高度自由truthy 即错误又有编译期的强类型保障。理解了这层设计你就能根据业务需要自由构造适合自己团队的错误契约写出更健壮、更易维护的表单校验代码。【免费下载链接】form Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/form创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考