Angular 表单验证完全指南模板驱动与响应式表单的校验体系与自定义验证器实战【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular在 Angular 中表单验证是保障数据质量与用户体验的核心能力。无论你使用模板驱动表单还是响应式表单Angular 都提供了一套属性/函数声明校验规则 → 值变化自动触发 → 状态对象存储结果 → 模板按状态渲染提示的完整闭环。本文以 angular 仓库中adev/src/content/examples/form-validation的演员表单Actor Form示例为主线系统讲解内置验证器、自定义同步验证器、跨字段验证、异步验证器如校验角色是否已被占用以及验证器的运行时动态管理并深入到packages/forms的源码实现帮助你掌握既能防错又能优雅提示错误的完整方案。模板驱动表单中的输入验证模板驱动表单的验证方式与原生 HTML 表单验证一脉相承你只需在元素上添加与 HTML 原生约束验证一致的验证属性如required、minlengthAngular 便通过指令把这些属性与框架中的验证器函数一一对应起来见 validators.ts 中RequiredValidator、MinLengthValidator等指令的注册方式。每次表单控件的值发生变化时Angular 都会执行验证并产生两类结果之一一组验证错误ValidationErrors对象对应控件的INVALID状态null对应控件的VALID状态。在模板中你可以通过把ngModel导出到局部模板变量来检查控件状态。下面这个示例把NgModel导出为名为name的变量源码见 actor-form-template.component.htmlinput typetext idname namename classform-control required minlength4 appForbiddenNamebob [(ngModel)]actor.name #namengModel / if (name.invalid (name.dirty || name.touched)) { div classalert if (name.hasError(required)) { divName is required./div } if (name.hasError(minlength)) { divName must be at least 4 characters long./div } if (name.hasError(forbiddenName)) { divName cannot be Bob./div } /div }上述示例展示了几个关键特性input元素携带了 HTML 验证属性required与minlength同时携带了一个自定义验证指令appForbiddenName对应forbiddenName验证器。#namengModel把NgModel导出为局部变量name。NgModel镜像了其底层FormControl实例的许多属性因此可在模板中使用它检查诸如valid、dirty之类的控件状态。控件属性的完整列表可参见 AbstractControl 定义。最外层的if仅在name无效且控件处于dirty或touched状态时才显示一组嵌套的错误消息。内层每个if针对一种可能的验证错误展示自定义消息required、minlength与forbiddenName各有一条。重要实践提示为避免验证器在用户有机会编辑表单之前就显示错误应始终在控件上检查dirty或touched状态。Angular 的状态流转规则是当用户修改了所关注字段的值时控件被标记为dirty脏当用户让表单控件失去焦点blur时控件被标记为touched已触碰。在模板驱动表单的组件类中只需在imports中引入对应的验证指令即可激活上述机制见 actor-form-template.component.ts它导入了FormsModule、ForbiddenValidatorDirective、UnambiguousRoleValidatorDirective与UniqueRoleValidatorDirective。响应式表单中的输入验证在响应式表单中唯一事实来源source of truth是组件类。你不再通过模板属性添加验证器而是直接在组件类的表单控件模型上添加验证器函数Angular 会在控件值变化时调用这些函数响应式表单整体机制可参见ReactiveFormsModule及 validators.ts。验证器函数的两种类型验证器类型细节同步验证器Sync validators同步函数接收控件实例后立即返回一组验证错误或null。在实例化FormControl时作为第二个参数传入。异步验证器Async validators异步函数接收控件实例后返回一个 Promise 或 Observable稍后发出emit一组验证错误或null。在实例化FormControl时作为第三个参数传入。出于性能考虑Angular只有全部同步验证器通过后才会运行异步验证器并且每个异步验证器都必须完成之后才会设置错误状态。内置验证器函数你可以编写自己的验证器函数也可以直接使用 Angular 内置的验证器。模板驱动表单中以属性形式出现的内置验证器如required、minlength全部能以函数形式从Validators类中取得内置验证器集合定义于 validators.ts。把演员表单改造成响应式表单后同样的内置验证器这次以函数形式出现见 actor-form-reactive.component.1.tsactorForm new FormGroup({ name: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), // -- 传入自定义验证器的方式 ]), role: new FormControl(this.actor.role), skill: new FormControl(this.actor.skill, Validators.required), }); get name() { return this.actorForm.get(name); } get skill() { return this.actorForm.get(skill); }此例中name控件设置了两个内置验证器——Validators.required与Validators.minLength(4)——以及一个自定义验证器forbiddenNameValidator。它们都是同步验证器因此作为第二个参数传入注意把多个验证函数放进一个数组即可同时支持多个验证器。该示例还添加了几个 getter 方法。在响应式表单中你随时可以通过父级 group 的get方法访问任意表单控件但有时在组件类里定义 getter 作为模板的快捷方式会更为方便。再看name输入的模板见 actor-form-reactive.component.htmlinput typetext idname classform-control formControlNamename required / if (name.invalid (name.dirty || name.touched)) { div classalert alert-danger if (name.hasError(required)) { divName is required./div } if (name.hasError(minlength)) { divName must be at least 4 characters long./div } if (name.hasError(forbiddenName)) { divName cannot be Bob./div } /div }这个表单与模板驱动版本的区别在于它不再导出任何指令而是使用组件类中定义的namegetter。请注意required属性仍然保留在模板中——它虽然对验证不是必需的但为了**可访问性accessibility**应当保留。定义自定义验证器内置验证器并不总能精确匹配你的业务场景因此有时需要创建自定义验证器。以forbiddenNameValidator函数为例见 forbidden-name.directive.ts/** An actors name cant match the given regular expression */ export function forbiddenNameValidator(nameRe: RegExp): ValidatorFn { return (control: AbstractControl): ValidationErrors | null { const forbidden nameRe.test(control.value); return forbidden ? {forbiddenName: {value: control.value}} : null; }; }这个函数是一个工厂factory它接收一个用于检测某种禁止名称的正则表达式并返回一个验证器函数。在本示例中禁止名是 bob因此该验证器会拒绝任何包含 bob 的演员名字换一个场景它也可以拒绝 alice 或其他被配置正则匹配到的任何名字。forbiddenNameValidator工厂返回配置好的验证器函数该函数接收一个 Angular 控件对象并返回null——当控件值有效时一个验证错误对象——否则。错误对象通常带有一个属性其属性名即验证键forbiddenName其值则是任意字典可把值例如这里的{value}插入到错误消息中。自定义异步验证器与同步版本相似但必须改为返回一个稍后发出null或验证错误对象的 Promise 或 observable。对于 observable 情形该 observable必须完成complete此时表单会采用其最后发出的值作为验证结果。向响应式表单添加自定义验证器在响应式表单中只需把函数直接传给FormControl即可见 actor-form-reactive.component.1.tsname: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), // -- 把自定义验证器以函数形式传入数组 ]),向模板驱动表单添加自定义验证器在模板驱动表单中需要在模板里添加一个指令由指令包装验证器函数。对应的ForbiddenValidatorDirective就是forbiddenNameValidator的包装器。Angular 之所以能识别该指令在验证流程中的角色是因为指令通过NG_VALIDATORS提供者provider注册了自己——NG_VALIDATORS是一个预定义、可扩展的验证器集合Directive({ selector: [appForbiddenName], providers: [ { provide: NG_VALIDATORS, useExisting: forwardRef(() ForbiddenValidatorDirective), multi: true, }, ], }) export class ForbiddenValidatorDirective implements Validator { readonly forbiddenName inputstring(, {alias: appForbiddenName}); validate(control: AbstractControl): ValidationErrors | null { return this.forbiddenName() ? forbiddenNameValidator(new RegExp(this.forbiddenName(), i))(control) : null; } }指令类实现了Validator接口从而能便捷地与 Angular 表单集成该文件同时展示了模板驱动版本如何用新式的input()信号读取属性值再按需把forbiddenName编译为正则并调用工厂函数。NG_VALIDATORS的注册与扩展机制定义在 packages/forms/src/directives/validators.ts。指令就绪后只需把它的选择器appForbiddenName添加到任意输入元素上即可激活它input ... appForbiddenNamebob [(ngModel)]actor.name #namengModel /提示关键陷阱注意自定义验证指令是用useExisting而非useClass实例化的。注册的验证器必须是ForbiddenValidatorDirective 的这个实例——即表单里forbiddenName属性被绑定为 bob 的那个实例。若把useExisting换成useClass你注册的是一个全新的类实例它并没有forbiddenName值验证逻辑也就无法按预期工作。控件状态 CSS 类Angular 会自动把许多控件状态镜像为表单控件元素上的 CSS 类你可以利用这些类按表单状态为控件设置样式。目前支持以下类.ng-valid.ng-invalid.ng-pending.ng-pristine.ng-dirty.ng-untouched.ng-touched.ng-submitted仅作用于外层form元素在演员表单示例中使用.ng-valid与.ng-invalid类为每个表单控件的边框着色见 forms.css.ng-valid[required], .ng-valid.required { border-left: 5px solid #42A948; /* green */ } .ng-invalid:not(form) { border-left: 5px solid #a94442; /* red */ }这样一来通过.ng-valid的字段显示绿色左边框未通过的字段.ng-invalid显示红色左边框用户无需任何提示文字即可一眼看出问题字段。注意示例中还特别排除了form元素本身避免把红色边框渲染到整个表单容器上。跨字段验证Cross-field Validation跨字段验证器是一种自定义验证器它比较表单中不同字段的值并决定是否把它们组合起来接受或拒绝。典型场景包括表单提供互斥选项用户可选 A 或 B但不能同时选或某个字段依赖另一个字段只有选了 A 才允许选 B。下面的跨字段验证示例演示了如何做到两点基于两个兄弟控件sibling controls的值校验响应式或模板驱动表单的输入在用户与表单交互之后且验证失败时显示一条描述性错误消息。示例业务规则演员的名字不能与所扮演的角色名相同否则角色产生歧义以此确保演员没有在自己的角色里复用名字。验证器通过检查演员的 name 与 role 是否一致来实现。响应式表单的跨字段验证表单结构如下const actorForm new FormGroup({ name: new FormControl(), role: new FormControl(), skill: new FormControl(), });注意name和role是兄弟控件。要在一个自定义验证器里同时评估这两个控件就必须在它们的共同祖先控件——FormGroup——上执行验证然后通过查询FormGroup取得子控件以比较它们的值。给FormGroup添加验证器的方式是在创建时作为第二个参数传入const actorForm new FormGroup( { name: new FormControl(), role: new FormControl(), skill: new FormControl(), }, {validators: unambiguousRoleValidator}, );验证器代码如下见 unambiguous-role.directive.ts/** An actors name cant match the actors role */ export const unambiguousRoleValidator: ValidatorFn ( control: AbstractControl, ): ValidationErrors | null { const name control.get(name); const role control.get(role); return name role name.value role.value ? {unambiguousRole: true} : null; };unambiguousRoleValidator实现了ValidatorFn接口接收一个 Angular 控件对象作为参数若表单有效返回null否则返回ValidationErrors。验证器通过调用FormGroup的get方法取得子控件再比较name与role的值值不相同→ 角色无歧义两个控件都有效返回null值相同→ 演员的角色有歧义返回错误对象将表单标记为无效。为了更好的用户体验模板会在表单无效时显示合适的错误消息见 actor-form-reactive.component.htmlif (actorForm.hasError(unambiguousRole) (actorForm.touched || actorForm.dirty)) { div classcross-validation-error-message alert alert-danger Name cannot match role or audiences will be confused. /div }这个if仅在FormGroup携带unambiguousRoleValidator返回的跨字段验证错误、且用户已经与该表单完成交互touched或dirty时才显示错误。模板驱动表单的跨字段验证对模板驱动表单需要创建一个指令来包装验证器函数并通过NG_VALIDATORS令牌把该指令作为验证器提供出去Directive({ selector: [appUnambiguousRole], providers: [ { provide: NG_VALIDATORS, useExisting: forwardRef(() UnambiguousRoleValidatorDirective), multi: true, }, ], }) export class UnambiguousRoleValidatorDirective implements Validator { validate(control: AbstractControl): ValidationErrors | null { return unambiguousRoleValidator(control); } }然后把新指令添加到 HTML 模板中。由于验证器必须注册在表单的最高层级下列模板把指令放在form标签上form #actorFormngForm appUnambiguousRole ... /form当表单无效时显示错误消息见 actor-form-template.component.htmlif (actorForm.hasError(unambiguousRole) (actorForm.touched || actorForm.dirty)) { div classcross-validation-error-message alertName cannot match role./div }这条提示逻辑在模板驱动与响应式表单中是完全相同的。创建异步验证器异步验证器实现AsyncValidatorFn与AsyncValidator接口。它们与同步版本非常相似区别在于validate()函数必须返回 Promise 或 observable返回的 observable 必须是**有限finite**的即必须在某个时刻完成。要把无限 observable 转换为有限版本可通过first、last、take、takeUntil之类的过滤操作符进行 pipe。异步验证发生在同步验证之后且只有同步验证成功时才会执行。这一检查让表单在更基础的验证已判定输入无效时可以避免触发代价高昂的异步验证流程例如 HTTP 请求。异步验证开始后表单控件进入pending待定状态。可检查控件的pending属性并据此为持续中的验证操作提供视觉反馈。一种常见 UI 模式是在异步验证进行时显示 spinner如下所示模板驱动表单input [(ngModel)]name #modelngModel appSomeAsyncValidator / if (model.pending) { app-spinner / }实现自定义异步验证器在下面这个示例中异步验证器保证演员不会接到一个已被占用的角色。新演员不断试镜、老演员不断退休因此可用角色列表无法提前获取要校验潜在的角色输入验证器必须发起一次异步操作去查询当前所有已确定演员的中央数据库。下面创建了实现AsyncValidator接口的验证器类UniqueRoleValidator见 role.directive.tsInjectable({providedIn: root}) export class UniqueRoleValidator implements AsyncValidator { private readonly actorsService inject(ActorsService); validate(control: AbstractControl): ObservableValidationErrors | null { return this.actorsService.isRoleTaken(control.value).pipe( map((isTaken) (isTaken ? {uniqueRole: true} : null)), catchError(() of(null)), ); } }actorsService属性以ActorsService令牌的实例初始化其接口定义为interface ActorsService { isRoleTaken: (role: string) Observableboolean; }在真实应用中ActorsService负责向演员数据库发起 HTTP 请求来检查角色是否可用。从验证器的角度看服务的具体实现并不重要因此示例可以直接面向ActorsService接口编码。配套的 actors.service.ts 提供了一个带 400ms 延迟的模拟实现内置ROLES [Hamlet, Ophelia, Romeo, Juliet]供演示。验证开始后UniqueRoleValidator用当前控件值委托调用ActorsService.isRoleTaken()。此时控件被标记为pending并一直保持该状态直到validate()方法返回的 observable 链完成。isRoleTaken()分发 HTTP 请求检查角色是否可用并返回Observablebooleanvalidate()通过map操作符把响应转换为验证结果然后和任何验证器一样有效返回null无效返回ValidationErrors。该验证器还用catchError操作符处理潜在错误——这里把isRoleTaken()的失败视为验证通过因为验证请求失败并不代表角色一定无效你当然也可以改用不同的错误处理方式直接返回ValidationError对象。一段时间后 observable 链完成、异步验证结束pending标志被置为false表单的有效性随之更新。向响应式表单添加异步验证器首先把验证器注入为组件类的一个属性见 actor-form-reactive.component.2.tsroleValidator inject(UniqueRoleValidator);然后把验证器函数直接传给FormControl以应用它。下面的示例把UniqueRoleValidator的validate函数应用到roleControl上通过asyncValidators选项传入并绑定到注入进ActorFormReactiveComponent的那个UniqueRoleValidator实例ngOnInit(): void { const roleControl new FormControl(, { asyncValidators: [this.roleValidator.validate.bind(this.roleValidator)], updateOn: blur, }); roleControl.setValue(this.actor.role); this.actorForm new FormGroup({ name: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), ]), role: roleControl, skill: new FormControl(this.actor.skill, Validators.required), }); }asyncValidators的值可以是单个异步验证器函数也可以是函数数组。关于FormControl选项的更多细节可参考AbstractControlOptionsAPI。向模板驱动表单添加异步验证器模板驱动表单中需要创建一个新指令并在其上注册NG_ASYNC_VALIDATORS提供者。下例中指令注入含有真实验证逻辑的UniqueRoleValidator类并在 Angular 触发验证时于validate函数内调用它见 role.directive.tsDirective({ selector: [appUniqueRole], providers: [ { provide: NG_ASYNC_VALIDATORS, useExisting: forwardRef(() UniqueRoleValidatorDirective), multi: true, }, ], }) export class UniqueRoleValidatorDirective implements AsyncValidator { private readonly validator inject(UniqueRoleValidator); validate(control: AbstractControl): ObservableValidationErrors | null { return this.validator.validate(control); } }然后与同步验证器一样把指令的选择器加到输入元素上即可激活它见 actor-form-template.component.html 中的 role 输入区input typetext idrole namerole #rolengModel [(ngModel)]actor.role [ngModelOptions]{updateOn: blur} appUniqueRole / if (role.pending) { divValidating.../div } if (role.invalid) { div classalert role-errors if (role.hasError(uniqueRole)) { divRole is already taken./div } /div }该模板片段同时示范了模板驱动表单中对异步验证的两个关键反馈通过role.pending显示正在校验以及通过role.hasError(uniqueRole)展示该角色已被占用。异步验证器的性能优化默认情况下每次表单值变化后所有验证器都会运行。同步验证器通常不会对应用性能造成可感知的影响而异步验证器通常会发起某种 HTTP 请求来校验控件——每次按键都触发一次 HTTP 请求会给后端 API 带来压力应尽量避免。可以通过把updateOn属性从默认的change改为submit或blur来推迟更新表单有效性模板驱动表单在模板中设置该属性input [(ngModel)]name [ngModelOptions]{updateOn: blur} /响应式表单在FormControl实例中设置new FormControl(, {updateOn: blur});在 actors 示例中响应式与模板驱动两个版本都把角色字段的更新时机设为blur从而避免每次按键都触发isRoleTaken的异步查询模拟服务仍自带 400ms 延迟以便肉眼观察 pending 状态。在响应式表单中动态管理验证器在复杂响应式表单中你可能需要根据用户输入或应用状态新增、移除或修改验证器。AbstractControl定义于 packages/forms/src/model/abstract_model.ts为此提供了多个方法无需重建表单控件即可在运行时管理验证器。添加与移除验证器addValidators与removeValidators方法允许你在初始化之后修改控件的验证器集合。例如根据用户选择的国家动态决定邮编字段是否必填、是否需匹配美国邮编格式onCountryChange(country: string) { const postalCodeControl this.profileForm.get(postalCode); if (country US) { // 为美国邮编添加验证器 postalCodeControl.addValidators([Validators.required, Validators.pattern(/^\d{5}$/)]); } else { // 非美国时移除验证器 postalCodeControl.removeValidators([Validators.required]); } postalCodeControl.updateValueAndValidity(); }整体替换或清空验证器使用setValidators替换控件上的全部现有同步验证器或用clearValidators移除所有验证器。例如根据一个严格模式开关切换姓名字段的校验强度toggleStrictNameValidation(isStrict: boolean) { const nameControl this.profileForm.get(name); if (enable) { // 设置严格验证规则 nameControl.setValidators([ Validators.required, Validators.minLength(3), Validators.pattern(/^[a-zA-Z]$/), ]); } else { // 清空所有验证器 nameControl.clearValidators(); } nameControl.updateValueAndValidity(); }同样的模式也适用于异步验证器对应方法为addAsyncValidators、removeAsyncValidators、setAsyncValidators与clearAsyncValidators。触发验证更新修改验证器之后应调用updateValueAndValidity重新计算控件的验证状态。该方法接收选项参数以控制更新行为// 更新控件并通知父级 control.updateValueAndValidity(); // 只更新控件自身不通知父级、不发出事件 control.updateValueAndValidity({onlySelf: true, emitEvent: false});从源码abstract_model.ts 中updateValueAndValidity的实现可以看到它除了执行校验器外还会负责把新的状态同步到_status字段、更新_updateTreeValidity链并默认向父级传播因此任何对验证器集合的运行时改动都需要这一调用来让状态树保持一致。与原生 HTML 表单验证的协同默认情况下Angular 通过给外层form添加novalidate属性来禁用原生 HTML 表单验证浏览器的约束验证 UI 不会弹出并改用指令把这些属性与框架内的验证器函数匹配起来。如果你希望配合Angular 验证一起使用原生验证可以通过ngNativeValidate指令重新启用它。此时两种机制会叠加例如先借助浏览器的原生约束如typeemail、pattern拦截明显非法输入再让 Angular 的验证体系接管状态展示与自定义业务规则。小结Angular 的表单验证体系可以用一条主线概括声明式规则 状态驱动 UI。模板驱动表单用 HTML 属性加NG_VALIDATORS/NG_ASYNC_VALIDATORS指令注册规则响应式表单用Validators函数与FormControl构造参数声明规则控件值一旦变化同步验证先行、异步验证随后错误对象写入控件的errors状态则反映在VALID/INVALID/PENDING与dirty/touched等标志及自动生成的 CSS 类上。跨字段验证把校验提升到FormGroup层级处理字段间约束异步验证器配合updateOn优化网络开销而addValidators/setValidators等方法则为复杂业务场景提供了运行时的动态验证能力。掌握这一套体系后无论表单多复杂你都能用统一、可维护的方式保证输入质量并给出恰到好处的错误提示。想亲自验证这些能力可直接运行 angular 仓库中的form-validation文档示例位于 adev/src/content/examples/form-validation对照响应式与模板驱动两个版本的演员表单观察同步校验、跨字段校验与异步校验各自的真实行为。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Angular 表单验证完全指南模板驱动与响应式表单的校验体系与自定义验证器实战【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular在 Angular 中表单验证是保障数据质量与用户体验的核心能力。无论你使用模板驱动表单还是响应式表单Angular 都提供了一套属性/函数声明校验规则 → 值变化自动触发 → 状态对象存储结果 → 模板按状态渲染提示的完整闭环。本文以 angular 仓库中adev/src/content/examples/form-validation的演员表单Actor Form示例为主线系统讲解内置验证器、自定义同步验证器、跨字段验证、异步验证器如校验角色是否已被占用以及验证器的运行时动态管理并深入到packages/forms的源码实现帮助你掌握既能防错又能优雅提示错误的完整方案。模板驱动表单中的输入验证模板驱动表单的验证方式与原生 HTML 表单验证一脉相承你只需在元素上添加与 HTML 原生约束验证一致的验证属性如required、minlengthAngular 便通过指令把这些属性与框架中的验证器函数一一对应起来见 validators.ts 中RequiredValidator、MinLengthValidator等指令的注册方式。每次表单控件的值发生变化时Angular 都会执行验证并产生两类结果之一一组验证错误ValidationErrors对象对应控件的INVALID状态null对应控件的VALID状态。在模板中你可以通过把ngModel导出到局部模板变量来检查控件状态。下面这个示例把NgModel导出为名为name的变量源码见 actor-form-template.component.htmlinput typetext idname namename classform-control required minlength4 appForbiddenNamebob [(ngModel)]actor.name #namengModel / if (name.invalid (name.dirty || name.touched)) { div classalert if (name.hasError(required)) { divName is required./div } if (name.hasError(minlength)) { divName must be at least 4 characters long./div } if (name.hasError(forbiddenName)) { divName cannot be Bob./div } /div }上述示例展示了几个关键特性input元素携带了 HTML 验证属性required与minlength同时携带了一个自定义验证指令appForbiddenName对应forbiddenName验证器。#namengModel把NgModel导出为局部变量name。NgModel镜像了其底层FormControl实例的许多属性因此可在模板中使用它检查诸如valid、dirty之类的控件状态。控件属性的完整列表可参见 AbstractControl 定义。最外层的if仅在name无效且控件处于dirty或touched状态时才显示一组嵌套的错误消息。内层每个if针对一种可能的验证错误展示自定义消息required、minlength与forbiddenName各有一条。重要实践提示为避免验证器在用户有机会编辑表单之前就显示错误应始终在控件上检查dirty或touched状态。Angular 的状态流转规则是当用户修改了所关注字段的值时控件被标记为dirty脏当用户让表单控件失去焦点blur时控件被标记为touched已触碰。在模板驱动表单的组件类中只需在imports中引入对应的验证指令即可激活上述机制见 actor-form-template.component.ts它导入了FormsModule、ForbiddenValidatorDirective、UnambiguousRoleValidatorDirective与UniqueRoleValidatorDirective。响应式表单中的输入验证在响应式表单中唯一事实来源source of truth是组件类。你不再通过模板属性添加验证器而是直接在组件类的表单控件模型上添加验证器函数Angular 会在控件值变化时调用这些函数响应式表单整体机制可参见ReactiveFormsModule及 validators.ts。验证器函数的两种类型验证器类型细节同步验证器Sync validators同步函数接收控件实例后立即返回一组验证错误或null。在实例化FormControl时作为第二个参数传入。异步验证器Async validators异步函数接收控件实例后返回一个 Promise 或 Observable稍后发出emit一组验证错误或null。在实例化FormControl时作为第三个参数传入。出于性能考虑Angular只有全部同步验证器通过后才会运行异步验证器并且每个异步验证器都必须完成之后才会设置错误状态。内置验证器函数你可以编写自己的验证器函数也可以直接使用 Angular 内置的验证器。模板驱动表单中以属性形式出现的内置验证器如required、minlength全部能以函数形式从Validators类中取得内置验证器集合定义于 validators.ts。把演员表单改造成响应式表单后同样的内置验证器这次以函数形式出现见 actor-form-reactive.component.1.tsactorForm new FormGroup({ name: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), // -- 传入自定义验证器的方式 ]), role: new FormControl(this.actor.role), skill: new FormControl(this.actor.skill, Validators.required), }); get name() { return this.actorForm.get(name); } get skill() { return this.actorForm.get(skill); }此例中name控件设置了两个内置验证器——Validators.required与Validators.minLength(4)——以及一个自定义验证器forbiddenNameValidator。它们都是同步验证器因此作为第二个参数传入注意把多个验证函数放进一个数组即可同时支持多个验证器。该示例还添加了几个 getter 方法。在响应式表单中你随时可以通过父级 group 的get方法访问任意表单控件但有时在组件类里定义 getter 作为模板的快捷方式会更为方便。再看name输入的模板见 actor-form-reactive.component.htmlinput typetext idname classform-control formControlNamename required / if (name.invalid (name.dirty || name.touched)) { div classalert alert-danger if (name.hasError(required)) { divName is required./div } if (name.hasError(minlength)) { divName must be at least 4 characters long./div } if (name.hasError(forbiddenName)) { divName cannot be Bob./div } /div }这个表单与模板驱动版本的区别在于它不再导出任何指令而是使用组件类中定义的namegetter。请注意required属性仍然保留在模板中——它虽然对验证不是必需的但为了**可访问性accessibility**应当保留。定义自定义验证器内置验证器并不总能精确匹配你的业务场景因此有时需要创建自定义验证器。以forbiddenNameValidator函数为例见 forbidden-name.directive.ts/** An actors name cant match the given regular expression */ export function forbiddenNameValidator(nameRe: RegExp): ValidatorFn { return (control: AbstractControl): ValidationErrors | null { const forbidden nameRe.test(control.value); return forbidden ? {forbiddenName: {value: control.value}} : null; }; }这个函数是一个工厂factory它接收一个用于检测某种禁止名称的正则表达式并返回一个验证器函数。在本示例中禁止名是 bob因此该验证器会拒绝任何包含 bob 的演员名字换一个场景它也可以拒绝 alice 或其他被配置正则匹配到的任何名字。forbiddenNameValidator工厂返回配置好的验证器函数该函数接收一个 Angular 控件对象并返回null——当控件值有效时一个验证错误对象——否则。错误对象通常带有一个属性其属性名即验证键forbiddenName其值则是任意字典可把值例如这里的{value}插入到错误消息中。自定义异步验证器与同步版本相似但必须改为返回一个稍后发出null或验证错误对象的 Promise 或 observable。对于 observable 情形该 observable必须完成complete此时表单会采用其最后发出的值作为验证结果。向响应式表单添加自定义验证器在响应式表单中只需把函数直接传给FormControl即可见 actor-form-reactive.component.1.tsname: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), // -- 把自定义验证器以函数形式传入数组 ]),向模板驱动表单添加自定义验证器在模板驱动表单中需要在模板里添加一个指令由指令包装验证器函数。对应的ForbiddenValidatorDirective就是forbiddenNameValidator的包装器。Angular 之所以能识别该指令在验证流程中的角色是因为指令通过NG_VALIDATORS提供者provider注册了自己——NG_VALIDATORS是一个预定义、可扩展的验证器集合Directive({ selector: [appForbiddenName], providers: [ { provide: NG_VALIDATORS, useExisting: forwardRef(() ForbiddenValidatorDirective), multi: true, }, ], }) export class ForbiddenValidatorDirective implements Validator { readonly forbiddenName inputstring(, {alias: appForbiddenName}); validate(control: AbstractControl): ValidationErrors | null { return this.forbiddenName() ? forbiddenNameValidator(new RegExp(this.forbiddenName(), i))(control) : null; } }指令类实现了Validator接口从而能便捷地与 Angular 表单集成该文件同时展示了模板驱动版本如何用新式的input()信号读取属性值再按需把forbiddenName编译为正则并调用工厂函数。NG_VALIDATORS的注册与扩展机制定义在 packages/forms/src/directives/validators.ts。指令就绪后只需把它的选择器appForbiddenName添加到任意输入元素上即可激活它input ... appForbiddenNamebob [(ngModel)]actor.name #namengModel /提示关键陷阱注意自定义验证指令是用useExisting而非useClass实例化的。注册的验证器必须是ForbiddenValidatorDirective 的这个实例——即表单里forbiddenName属性被绑定为 bob 的那个实例。若把useExisting换成useClass你注册的是一个全新的类实例它并没有forbiddenName值验证逻辑也就无法按预期工作。控件状态 CSS 类Angular 会自动把许多控件状态镜像为表单控件元素上的 CSS 类你可以利用这些类按表单状态为控件设置样式。目前支持以下类.ng-valid.ng-invalid.ng-pending.ng-pristine.ng-dirty.ng-untouched.ng-touched.ng-submitted仅作用于外层form元素在演员表单示例中使用.ng-valid与.ng-invalid类为每个表单控件的边框着色见 forms.css.ng-valid[required], .ng-valid.required { border-left: 5px solid #42A948; /* green */ } .ng-invalid:not(form) { border-left: 5px solid #a94442; /* red */ }这样一来通过.ng-valid的字段显示绿色左边框未通过的字段.ng-invalid显示红色左边框用户无需任何提示文字即可一眼看出问题字段。注意示例中还特别排除了form元素本身避免把红色边框渲染到整个表单容器上。跨字段验证Cross-field Validation跨字段验证器是一种自定义验证器它比较表单中不同字段的值并决定是否把它们组合起来接受或拒绝。典型场景包括表单提供互斥选项用户可选 A 或 B但不能同时选或某个字段依赖另一个字段只有选了 A 才允许选 B。下面的跨字段验证示例演示了如何做到两点基于两个兄弟控件sibling controls的值校验响应式或模板驱动表单的输入在用户与表单交互之后且验证失败时显示一条描述性错误消息。示例业务规则演员的名字不能与所扮演的角色名相同否则角色产生歧义以此确保演员没有在自己的角色里复用名字。验证器通过检查演员的 name 与 role 是否一致来实现。响应式表单的跨字段验证表单结构如下const actorForm new FormGroup({ name: new FormControl(), role: new FormControl(), skill: new FormControl(), });注意name和role是兄弟控件。要在一个自定义验证器里同时评估这两个控件就必须在它们的共同祖先控件——FormGroup——上执行验证然后通过查询FormGroup取得子控件以比较它们的值。给FormGroup添加验证器的方式是在创建时作为第二个参数传入const actorForm new FormGroup( { name: new FormControl(), role: new FormControl(), skill: new FormControl(), }, {validators: unambiguousRoleValidator}, );验证器代码如下见 unambiguous-role.directive.ts/** An actors name cant match the actors role */ export const unambiguousRoleValidator: ValidatorFn ( control: AbstractControl, ): ValidationErrors | null { const name control.get(name); const role control.get(role); return name role name.value role.value ? {unambiguousRole: true} : null; };unambiguousRoleValidator实现了ValidatorFn接口接收一个 Angular 控件对象作为参数若表单有效返回null否则返回ValidationErrors。验证器通过调用FormGroup的get方法取得子控件再比较name与role的值值不相同→ 角色无歧义两个控件都有效返回null值相同→ 演员的角色有歧义返回错误对象将表单标记为无效。为了更好的用户体验模板会在表单无效时显示合适的错误消息见 actor-form-reactive.component.htmlif (actorForm.hasError(unambiguousRole) (actorForm.touched || actorForm.dirty)) { div classcross-validation-error-message alert alert-danger Name cannot match role or audiences will be confused. /div }这个if仅在FormGroup携带unambiguousRoleValidator返回的跨字段验证错误、且用户已经与该表单完成交互touched或dirty时才显示错误。模板驱动表单的跨字段验证对模板驱动表单需要创建一个指令来包装验证器函数并通过NG_VALIDATORS令牌把该指令作为验证器提供出去Directive({ selector: [appUnambiguousRole], providers: [ { provide: NG_VALIDATORS, useExisting: forwardRef(() UnambiguousRoleValidatorDirective), multi: true, }, ], }) export class UnambiguousRoleValidatorDirective implements Validator { validate(control: AbstractControl): ValidationErrors | null { return unambiguousRoleValidator(control); } }然后把新指令添加到 HTML 模板中。由于验证器必须注册在表单的最高层级下列模板把指令放在form标签上form #actorFormngForm appUnambiguousRole ... /form当表单无效时显示错误消息见 actor-form-template.component.htmlif (actorForm.hasError(unambiguousRole) (actorForm.touched || actorForm.dirty)) { div classcross-validation-error-message alertName cannot match role./div }这条提示逻辑在模板驱动与响应式表单中是完全相同的。创建异步验证器异步验证器实现AsyncValidatorFn与AsyncValidator接口。它们与同步版本非常相似区别在于validate()函数必须返回 Promise 或 observable返回的 observable 必须是**有限finite**的即必须在某个时刻完成。要把无限 observable 转换为有限版本可通过first、last、take、takeUntil之类的过滤操作符进行 pipe。异步验证发生在同步验证之后且只有同步验证成功时才会执行。这一检查让表单在更基础的验证已判定输入无效时可以避免触发代价高昂的异步验证流程例如 HTTP 请求。异步验证开始后表单控件进入pending待定状态。可检查控件的pending属性并据此为持续中的验证操作提供视觉反馈。一种常见 UI 模式是在异步验证进行时显示 spinner如下所示模板驱动表单input [(ngModel)]name #modelngModel appSomeAsyncValidator / if (model.pending) { app-spinner / }实现自定义异步验证器在下面这个示例中异步验证器保证演员不会接到一个已被占用的角色。新演员不断试镜、老演员不断退休因此可用角色列表无法提前获取要校验潜在的角色输入验证器必须发起一次异步操作去查询当前所有已确定演员的中央数据库。下面创建了实现AsyncValidator接口的验证器类UniqueRoleValidator见 role.directive.tsInjectable({providedIn: root}) export class UniqueRoleValidator implements AsyncValidator { private readonly actorsService inject(ActorsService); validate(control: AbstractControl): ObservableValidationErrors | null { return this.actorsService.isRoleTaken(control.value).pipe( map((isTaken) (isTaken ? {uniqueRole: true} : null)), catchError(() of(null)), ); } }actorsService属性以ActorsService令牌的实例初始化其接口定义为interface ActorsService { isRoleTaken: (role: string) Observableboolean; }在真实应用中ActorsService负责向演员数据库发起 HTTP 请求来检查角色是否可用。从验证器的角度看服务的具体实现并不重要因此示例可以直接面向ActorsService接口编码。配套的 actors.service.ts 提供了一个带 400ms 延迟的模拟实现内置ROLES [Hamlet, Ophelia, Romeo, Juliet]供演示。验证开始后UniqueRoleValidator用当前控件值委托调用ActorsService.isRoleTaken()。此时控件被标记为pending并一直保持该状态直到validate()方法返回的 observable 链完成。isRoleTaken()分发 HTTP 请求检查角色是否可用并返回Observablebooleanvalidate()通过map操作符把响应转换为验证结果然后和任何验证器一样有效返回null无效返回ValidationErrors。该验证器还用catchError操作符处理潜在错误——这里把isRoleTaken()的失败视为验证通过因为验证请求失败并不代表角色一定无效你当然也可以改用不同的错误处理方式直接返回ValidationError对象。一段时间后 observable 链完成、异步验证结束pending标志被置为false表单的有效性随之更新。向响应式表单添加异步验证器首先把验证器注入为组件类的一个属性见 actor-form-reactive.component.2.tsroleValidator inject(UniqueRoleValidator);然后把验证器函数直接传给FormControl以应用它。下面的示例把UniqueRoleValidator的validate函数应用到roleControl上通过asyncValidators选项传入并绑定到注入进ActorFormReactiveComponent的那个UniqueRoleValidator实例ngOnInit(): void { const roleControl new FormControl(, { asyncValidators: [this.roleValidator.validate.bind(this.roleValidator)], updateOn: blur, }); roleControl.setValue(this.actor.role); this.actorForm new FormGroup({ name: new FormControl(this.actor.name, [ Validators.required, Validators.minLength(4), forbiddenNameValidator(/bob/i), ]), role: roleControl, skill: new FormControl(this.actor.skill, Validators.required), }); }asyncValidators的值可以是单个异步验证器函数也可以是函数数组。关于FormControl选项的更多细节可参考AbstractControlOptionsAPI。向模板驱动表单添加异步验证器模板驱动表单中需要创建一个新指令并在其上注册NG_ASYNC_VALIDATORS提供者。下例中指令注入含有真实验证逻辑的UniqueRoleValidator类并在 Angular 触发验证时于validate函数内调用它见 role.directive.tsDirective({ selector: [appUniqueRole], providers: [ { provide: NG_ASYNC_VALIDATORS, useExisting: forwardRef(() UniqueRoleValidatorDirective), multi: true, }, ], }) export class UniqueRoleValidatorDirective implements AsyncValidator { private readonly validator inject(UniqueRoleValidator); validate(control: AbstractControl): ObservableValidationErrors | null { return this.validator.validate(control); } }然后与同步验证器一样把指令的选择器加到输入元素上即可激活它见 actor-form-template.component.html 中的 role 输入区input typetext idrole namerole #rolengModel [(ngModel)]actor.role [ngModelOptions]{updateOn: blur} appUniqueRole / if (role.pending) { divValidating.../div } if (role.invalid) { div classalert role-errors if (role.hasError(uniqueRole)) { divRole is already taken./div } /div }该模板片段同时示范了模板驱动表单中对异步验证的两个关键反馈通过role.pending显示正在校验以及通过role.hasError(uniqueRole)展示该角色已被占用。异步验证器的性能优化默认情况下每次表单值变化后所有验证器都会运行。同步验证器通常不会对应用性能造成可感知的影响而异步验证器通常会发起某种 HTTP 请求来校验控件——每次按键都触发一次 HTTP 请求会给后端 API 带来压力应尽量避免。可以通过把updateOn属性从默认的change改为submit或blur来推迟更新表单有效性模板驱动表单在模板中设置该属性input [(ngModel)]name [ngModelOptions]{updateOn: blur} /响应式表单在FormControl实例中设置new FormControl(, {updateOn: blur});在 actors 示例中响应式与模板驱动两个版本都把角色字段的更新时机设为blur从而避免每次按键都触发isRoleTaken的异步查询模拟服务仍自带 400ms 延迟以便肉眼观察 pending 状态。在响应式表单中动态管理验证器在复杂响应式表单中你可能需要根据用户输入或应用状态新增、移除或修改验证器。AbstractControl定义于 packages/forms/src/model/abstract_model.ts为此提供了多个方法无需重建表单控件即可在运行时管理验证器。添加与移除验证器addValidators与removeValidators方法允许你在初始化之后修改控件的验证器集合。例如根据用户选择的国家动态决定邮编字段是否必填、是否需匹配美国邮编格式onCountryChange(country: string) { const postalCodeControl this.profileForm.get(postalCode); if (country US) { // 为美国邮编添加验证器 postalCodeControl.addValidators([Validators.required, Validators.pattern(/^\d{5}$/)]); } else { // 非美国时移除验证器 postalCodeControl.removeValidators([Validators.required]); } postalCodeControl.updateValueAndValidity(); }整体替换或清空验证器使用setValidators替换控件上的全部现有同步验证器或用clearValidators移除所有验证器。例如根据一个严格模式开关切换姓名字段的校验强度toggleStrictNameValidation(isStrict: boolean) { const nameControl this.profileForm.get(name); if (enable) { // 设置严格验证规则 nameControl.setValidators([ Validators.required, Validators.minLength(3), Validators.pattern(/^[a-zA-Z]$/), ]); } else { // 清空所有验证器 nameControl.clearValidators(); } nameControl.updateValueAndValidity(); }同样的模式也适用于异步验证器对应方法为addAsyncValidators、removeAsyncValidators、setAsyncValidators与clearAsyncValidators。触发验证更新修改验证器之后应调用updateValueAndValidity重新计算控件的验证状态。该方法接收选项参数以控制更新行为// 更新控件并通知父级 control.updateValueAndValidity(); // 只更新控件自身不通知父级、不发出事件 control.updateValueAndValidity({onlySelf: true, emitEvent: false});从源码abstract_model.ts 中updateValueAndValidity的实现可以看到它除了执行校验器外还会负责把新的状态同步到_status字段、更新_updateTreeValidity链并默认向父级传播因此任何对验证器集合的运行时改动都需要这一调用来让状态树保持一致。与原生 HTML 表单验证的协同默认情况下Angular 通过给外层form添加novalidate属性来禁用原生 HTML 表单验证浏览器的约束验证 UI 不会弹出并改用指令把这些属性与框架内的验证器函数匹配起来。如果你希望配合Angular 验证一起使用原生验证可以通过ngNativeValidate指令重新启用它。此时两种机制会叠加例如先借助浏览器的原生约束如typeemail、pattern拦截明显非法输入再让 Angular 的验证体系接管状态展示与自定义业务规则。小结Angular 的表单验证体系可以用一条主线概括声明式规则 状态驱动 UI。模板驱动表单用 HTML 属性加NG_VALIDATORS/NG_ASYNC_VALIDATORS指令注册规则响应式表单用Validators函数与FormControl构造参数声明规则控件值一旦变化同步验证先行、异步验证随后错误对象写入控件的errors状态则反映在VALID/INVALID/PENDING与dirty/touched等标志及自动生成的 CSS 类上。跨字段验证把校验提升到FormGroup层级处理字段间约束异步验证器配合updateOn优化网络开销而addValidators/setValidators等方法则为复杂业务场景提供了运行时的动态验证能力。掌握这一套体系后无论表单多复杂你都能用统一、可维护的方式保证输入质量并给出恰到好处的错误提示。想亲自验证这些能力可直接运行 angular 仓库中的form-validation文档示例位于 adev/src/content/examples/form-validation对照响应式与模板驱动两个版本的演员表单观察同步校验、跨字段校验与异步校验各自的真实行为。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
