ng-zorro-antd 表单自动提示（nzAutoTips）：基于多语言 Validators 的校验错误提示自动化方案

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文围绕 ng-zorro-antd 表单组件的「自动提示」Auto tips能力展开讲解如何通过自定义Validators与nzAutoTips配置让校验错误提示自动生成避免为每个表单项手写nzErrorTip。读完本文你将掌握nzAutoTips的完整数据结构、Validators Input 全局配置的优先级规则、基于当前语言环境zh-cn、en等的多语言提示查找机制以及如何用nzDisableAutoTips在表单级或控件级禁用自动提示。为什么需要自动提示在 ng-zorro-antd 表单中传统做法是每个nz-form-control通过nzErrorTip手写错误文案例如请输入密码、密码不一致。当一个表单包含大量字段、且需要支持中英文多语言时这种手写方式会产生大量重复代码且容易遗漏。自动提示功能的核心思想是把错误文案与校验规则绑定在一起让校验器Validators自己携带提示信息表单控件只负责展示。正如 auto-tips.md 中所说让提示变得更简单——你只需要预先自定义Validators并提供nzAutoTips剩余的工作交给表单组件。优先级规则谁说了算根据 auto-tips.md 的定义自动提示的优先级如下ValidatorsnzAutoTips校验器自身携带的错误提示如自定义 Validator 返回的多语言错误对象优先于nzAutoTips配置通过Input设置nzAutoTipsnz-form-control上直接绑定的nzAutoTips优先于全局配置通过全局配置设置nzAutoTips在NzConfig中针对form模块配置的nzAutoTips作为兜底默认值。此外你可以使用nzDisableAutoTips在任意层级禁用该功能。从源码看优先级的具体实现优先级并非文档中的抽象描述而是实打实编码在 form-control.component.ts 的updateAutoErrorTip()方法中。对控件上的每个校验错误key它按如下顺序取第一个非空值autoErrorTip errors[key]?.[this.localeId] ?? // 1. Validator 返回的多语言错误对象 this.nzAutoTips?.[this.localeId]?.[key] ?? // 2a. nz-form-control 的 Input当前语言 this.nzAutoTips.default?.[key] ?? // 2b. nz-form-control 的 Inputdefault 兜底 this.nzFormDirective?.nzAutoTips?.[this.localeId]?.[key] ?? // 3a. 表单级 Input当前语言 this.nzFormDirective?.nzAutoTips.default?.[key]; // 3b. 表单级 Inputdefault 兜底可见ValidatorsnzAutoTips的本质是校验器返回的错误对象中只要对应key的语言条目存在就直接采用否则才降级去nzAutoTips先控件、后表单里按语言查找。三处配置的位置配置位置写法作用范围自定义 Validators校验器返回{ key: { zh-cn: ..., en: ... } }形式的错误对象单个字段nz-form-control的[nzAutoTips]模板中直接绑定单个表单项form nz-form [nzAutoTips]...含全局配置绑定在NzFormDirective上整个表单 / 全局默认表单级属性定义在 form.directive.tsInput() WithConfig() nzAutoTips: Recordstring, Recordstring, string {}; Input({ transform: booleanAttribute }) nzDisableAutoTips false;其中WithConfig()装饰器正是全局配置兜底的来源当模板上没有显式绑定nzAutoTips时会回退到NzConfigService中form模块的全局配置。对应地index.zh-CN.md 的全局配置表中记录了[nzAutoTips]配置nz-form-control的[nzAutoTips]的默认值类型Recordstring, Recordstring, string默认{}[nzDisableAutoTips]配置nz-form-control的[nzDisableAutoTips]的默认值类型boolean默认false。nzAutoTips 的数据结构两级 RecordnzAutoTips的类型是Recordstring, Recordstring, string共两层第一层 key语言环境。使用当前语言环境的标识zh-cn、en等作为 key另有特殊 keydefault作为兜底第二层 key校验错误类型。对应 Angular 表单校验错误的 key如required、email、minlength、maxlength或自定义校验器的错误 keyvalue提示文案字符串。示例来自 auto-tips.tsautoTips: Recordstring, Recordstring, string { zh-cn: { required: 必填项 }, en: { required: Input is required }, default: { email: 邮箱格式不正确/The input is not valid email } };语言查找的兜底逻辑根据 auto-tips.md 的说明使用当前语言环境zh-cn、en...作为nzAutoTips的 key 去查找提示如果没找到会再用default查找一次。对应到源码 form-control.component.ts每个层级控件级、表单级的查找顺序都是[localeId]→default。当前语言环境来自NzI18nService在构造函数中通过订阅localeChange动态更新localeId见 form-control.component.ts因此切换语言时提示文案会自动更新无需手动刷新。该兜底机制在测试 form-control.spec.ts 中也有体现emailAutoTips只声明了zh-cn与en的email文案而把required放在default下——这样无论当前语言是中文还是英文未填邮箱时都能显示default中的文案。自定义 Validators让校验器自带多语言文案要实现自动提示关键是让校验器返回携带多语言文案的错误对象。参考 demo 中的 auto-tips.ts自定义校验器的返回结构为export type MyErrorsOptions { zh-cn: string; en: string } Recordstring, NzSafeAny; export type MyValidationErrors Recordstring, MyErrorsOptions;即错误对象的每个 key 对应一种校验错误value 是一个按语言映射文案的对象。例如export class MyValidators extends Validators { static override minLength(minLength: number): ValidatorFn { return (control: AbstractControl): MyValidationErrors | null { if (Validators.minLength(minLength)(control) null) { return null; } return { minlength: { zh-cn: 最小长度为 ${minLength}, en: MinLength is ${minLength} } }; }; } static mobile(control: AbstractControl): MyValidationErrors | null { const value control.value; if (isEmptyInputValue(value)) { return null; } return isMobile(value) ? null : { mobile: { zh-cn: 手机号码格式不正确, en: Mobile phone number is not valid } }; } }当校验失败时errors中会出现minlength、mobile等 key而updateAutoErrorTip()会读取errors[key][localeId]——这正是优先级中ValidatorsnzAutoTips的含义。即使nzAutoTips里也配置了同名 key校验器自带文案仍然优先。需要说明的是Angular 内置Validators返回的错误对象如{ required: true }不含多语言文案所以自动提示依赖预先自定义 Validators。这要求你把内置校验器包一层让返回值带上{ zh-cn: ..., en: ... }结构。完整示例一个自动提示表单以下完整示例来自 auto-tips.ts演示了用户名异步校验、手机号、邮箱、密码、确认密码五个字段的自动提示用法模板部分form nz-form [nzAutoTips]autoTips [formGroup]validateForm (ngSubmit)submitForm() nz-form-item nz-form-label [nzSpan]7 nzRequiredUsername/nz-form-label nz-form-control [nzSpan]12 nzValidatingTipValidating... input nz-input formControlNameusername placeholderasync validate try to write JasonWood / /nz-form-control /nz-form-item nz-form-item nz-form-label [nzSpan]7 nzRequiredMobile/nz-form-label nz-form-control [nzSpan]12 input nz-input formControlNamemobile placeholdermobile / /nz-form-control /nz-form-item nz-form-item nz-form-label [nzSpan]7 nzRequiredE-mail/nz-form-label nz-form-control [nzSpan]12 input nz-input formControlNameemail placeholderemail typeemail / /nz-form-control /nz-form-item nz-form-item nz-form-label [nzSpan]7 nzRequiredPassword/nz-form-label nz-form-control [nzSpan]12 nzDisableAutoTips nzErrorTipPlease input your password! input nz-input typepassword formControlNamepassword / /nz-form-control /nz-form-item nz-form-item nz-form-label [nzSpan]7 nzRequiredConfirm Password/nz-form-label nz-form-control [nzSpan]12 nzDisableAutoTips [nzErrorTip]passwordErrorTpl input nz-input typepassword formControlNameconfirm placeholderconfirm your password / ng-template #passwordErrorTpl let-control if (control.errors?.[required]) { Please confirm your password! } if (control.errors?.[confirm]) { Password is inconsistent! } /ng-template /nz-form-control /nz-form-item nz-form-item nz-form-control [nzOffset]7 [nzSpan]12 button nz-button nzTypeprimarySubmit/button /nz-form-control /nz-form-item /form组件逻辑部分validateForm this.fb.group({ username: this.fb.control( , [MyValidators.required, MyValidators.maxLength(12), MyValidators.minLength(6)], [this.usernameAsyncValidator] ), mobile: this.fb.control(, [MyValidators.required, MyValidators.mobile]), email: this.fb.control(, [MyValidators.required, MyValidators.email]), password: this.fb.control(, [MyValidators.required]), confirm: this.fb.control(, [this.confirmValidator]) }); // current locale is key of the nzAutoTips // if it is not found, it will be searched again with default autoTips: Recordstring, Recordstring, string { zh-cn: { required: 必填项 }, en: { required: Input is required }, default: { email: 邮箱格式不正确/The input is not valid email } };异步校验器也能携带多语言文案用户名异步校验器见 auto-tips.ts在延迟 1 秒后判断当输入JasonWood时返回duplicated错误其文案同样按语言组织usernameAsyncValidator(control: AbstractControl): ObservableValidationErrors | null { return new Observable((observer: ObserverMyValidationErrors | null) { setTimeout(() { if (control.value JasonWood) { observer.next({ duplicated: { zh-cn: 用户名已存在, en: The username is redundant! } }); } else { observer.next(null); } observer.complete(); }, 1000); }); }确认密码的联动校验demo 通过监听 password 的valueChanges联动触发 confirm 的重新校验见 auto-tips.tsngOnInit(): void { this.validateForm.controls.password.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(() { this.validateForm.controls.confirm.updateValueAndValidity(); }); }同时confirmValidator见 auto-tips.ts会返回{ required: true }或{ confirm: true }配合模板中的nzErrorTip模板按错误类型渲染不同文案。nzDisableAutoTips按需关闭自动提示nzDisableAutoTips用于关闭自动提示可作用于两个层级控件级nz-form-control nzDisableAutoTips表单级form nz-form [nzDisableAutoTips]true。控件级属性定义在 form-control.component.ts其取值优先级实现于 form-control.component.tsprivate get disableAutoTips(): boolean { return this.nzDisableAutoTips ! undefined ? toBoolean(this.nzDisableAutoTips) : !!this.nzFormDirective?.nzDisableAutoTips; }即控件上显式设置了nzDisableAutoTips时以控件为准否则继承表单级nzDisableAutoTips。这与 demo 中Password / Confirm Password 两个字段禁用自动提示、其余字段启用的用法一致——禁用后这两个字段回退到nzErrorTip或自定义模板显示文案。在展示逻辑上form-control.component.ts错误状态下提示的最终取值是return (!this.disableAutoTips this.autoErrorTip) || this.nzErrorTip || null;自动提示与手写nzErrorTip可以并存启用自动提示时优先显示自动文案一旦禁用自动提示nzErrorTip立即接管。全局配置让整个应用的自动提示默认生效nzAutoTips与nzDisableAutoTips都支持通过全局配置NzConfigService设置默认值见 index.zh-CN.md 与 form.directive.ts 的WithConfig()。典型用法import { NzConfig, NZ_CONFIG } from ng-zorro-antd/core/config; const ngZorroConfig: NzConfig { form: { nzAutoTips: { zh-cn: { required: 必填项, email: 邮箱格式不正确 }, en: { required: Input is required, email: The input is not valid email } }, nzDisableAutoTips: false } }; providers: [{ provide: NZ_CONFIG, useValue: ngZorroConfig }]全局配置作为最低优先级存在只要表单或控件上显式绑定了nzAutoTips就以显式绑定为准。这样既能保证开箱即用的多语言提示又允许特定表单局部覆盖。测试验证自动提示的三种行为仓库在 form-control.spec.ts 中为自动提示提供了系统性的测试用例可以从测试断言中确认核心行为默认行为将各控件markAsDirty()并updateValueAndValidity()后.ant-form-item-explain中显示nzAutoTips对应文案如必填项当校验器自带文案时如最小长度为 6、手机号码格式不正确优先显示校验器文案——这正是ValidatorsnzAutoTips的运行时验证i18n 行为调用NzI18nService.setLocale(en_US)切换语言后提示自动切换为英文Input is required、MinLength is 6等验证了以当前语言环境为 key 查找的机制nzDisableAutoTips 行为控件级置true后显示nzErrorTip文案Please input your password!表单级置true后表单内所有字段的自动提示被关闭。测试组件见 form-control.spec.ts同时覆盖了表单级nzAutoTips 控件级覆盖[nzAutoTips] 控件级nzDisableAutoTips的混合场景可作为实际开发中组合使用的参考。小结与使用建议自动提示把错误文案从模板搬进校验器与配置用一套Recordstring, Recordstring, string同时解决多语言与重复代码问题。实践要点自定义 Validators 优先让校验器返回{ key: { zh-cn: ..., en: ... } }结构可得到最高优先级的错误提示用好两级配置表单级[nzAutoTips]覆盖大部分字段控件级[nzAutoTips]处理个别特例如 form-control.spec.ts 中 email 的default兜底文案全局配置兜底在NzConfig中配置form.nzAutoTips实现全应用统一的多语言提示默认值按需禁用需要自定义复杂文案如确认密码不一致、模板渲染的字段用nzDisableAutoTipsnzErrorTip含TemplateRef形式精确控制。相关参考完整演示见 auto-tips.ts组件 API 说明见 index.zh-CN.md表单指令实现见 form.directive.ts控件实现见 form-control.component.ts。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Splatt3R实战教程使用Gradio演示快速生成3D场景Splatt3R实战教程使用Gradio演示快速生成3D场景 想要从普通照片快速生成逼真的3D场景吗Splatt3R正是您需要的工具这是一个革命性的零样本ngx-admin 表单验证国际化多语言错误提示ngx admin 表单验证国际化多语言错误提示 在全球化应用开发中表单验证的多语言支持是提升用户体验的关键环节。ngx admin作为基于Angular和前端UI组件开源知识库管理系统怎么选科亿知识库(KYKMS)避坑实战指南开源知识库管理系统怎么选科亿知识库 KYKMS 避坑实战指南 上周三下午三点客户在群里问了一句很轻巧的话去年 6 月那版方案里数据同步接口的鉴权方式是知识管理企业应用大模型RAG本地部署搜索引擎知识图谱工作流自动化上一篇探索JSON的利器JSONUI下一篇推荐开源项目Nitrite 数据库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考