angular-forms

@angular/forms

版本： Angular 21（2025） 标签： 表单、验证、响应式表单、模板驱动

参考： 响应式表单 • 模板驱动 • API

API 变更

本节介绍近期特定版本的 API 变更。

• 新增：基于信号的表单控件 — Angular 19+ 为表单控件提供的信号集成

• 新增：函数式验证器 — 优先使用函数式验证器，而非基于类的验证器

• 新增：AbstractControl.markAllAsTouched() — 用于将所有控件标记为已触碰的新方法

• 新增：nonNullable 选项 — 创建不可为空的 FormControl

• 新增：类型化表单 — 为表单组和数组提供完整的 TypeScript 支持

• 已弃用：基于类的验证器 — 迁移到函数式验证器

最佳实践

• 复杂表单使用响应式表单 — 结构、验证和可测试性更佳

import { FormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';

@Component({
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <input formControlName="email" />
      <div *ngIf="form.controls.email.invalid && form.controls.email.touched">
        Email is required
      </div>
    </form>
  `
})
export class LoginComponent {
  private fb = inject(FormBuilder);
  
  form = this.fb.nonNullable.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]]
  });

  onSubmit() {
    if (this.form.valid) {
      console.log(this.form.getRawValue());
    }
  }
}

• 使用 FormBuilder，让代码更简洁

form = this.fb.group({
  name: ['', Validators.required],
  email: ['', [Validators.required, Validators.email]],
  address: this.fb.group({
    street: [''],
    city: ['']
  })
});

• 复杂逻辑使用自定义验证器

// Functional validator (preferred)
const forbiddenNameValidator = (control: AbstractControl): ValidationErrors | null => {
  const forbidden = ['admin', 'root', 'superuser'];
  return forbidden.includes(control.value) ? { forbiddenName: true } : null;
};

// Usage
name: ['', forbiddenNameValidator]

• 使用异步验证器进行服务端验证

email: ['', 
  [Validators.email], 
  [asyncValidator, { debounceTime: 300 }]
]

• 使用 FormArray 创建动态表单字段

const form = this.fb.group({
  emails: this.fb.array([
    this.fb.control('')
  ])
});

get emails(): FormArray {
  return this.form.get('emails') as FormArray;
}

addEmail() {
  this.emails.push(this.fb.control(''));
}

• 使用 updateOn 选项提升性能

// Only validate on blur
email: ['', { updateOn: 'blur' }]

// Only validate on submit
password: ['', { updateOn: 'submit' }]

• 根据条件显示验证错误

<input formControlName="email" 
       [class.is-invalid]="email.invalid && (email.dirty || email.touched)" />

• 使用 disable() 有条件地禁用字段

// Disable based on another control
this.form.statusChanges.subscribe(() => {
  if (this.form.value.isAdmin) {
    this.form.controls.permissions.enable();
  } else {
    this.form.controls.permissions.disable();
  }
});

• 正确重置表单

// Reset with default values
this.form.reset({ email: '', name: 'Default' });

// Reset and clear validators
this.form.reset();
this.form.clearValidators();