angular-forms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@angular/forms

Version: Angular 21 (2025) Tags: Forms, Validation, Reactive Forms, Template-Driven

References: Reactive Forms • Template-Driven • API

版本: Angular 21 (2025) 标签: Forms, Validation, Reactive Forms, Template-Driven

参考资料: 响应式表单 • 模板驱动表单 • API

API Changes

API变更

This section documents recent version-specific API changes.

NEW: Signal-based form controls — Angular 19+ signal integration for form controls
NEW: Functional validators — Prefer functional validators over class-based validators
NEW:
```
AbstractControl.markAllAsTouched()
```
— New method to mark all controls as touched
NEW:
```
nonNullable
```
option — Create non-nullable FormControls
NEW: Typed forms — Full TypeScript support for form groups and arrays
DEPRECATED: Class-based validators — Migrate to functional validators

本节记录了近期对应版本的API改动。

新增：基于Signal的表单控件 —— Angular 19+ 版本为表单控件集成了Signal支持
新增：函数式验证器 —— 优先使用函数式验证器而非基于类的验证器
新增：
```
AbstractControl.markAllAsTouched()
```
—— 用于将所有控件标记为已触碰的新方法
新增：
```
nonNullable
```
选项 —— 用于创建非空的FormControls
新增：类型化表单 —— 为表单组和表单数组提供完整的TypeScript支持
已弃用：基于类的验证器 —— 请迁移至函数式验证器

Best Practices

最佳实践

Use Reactive Forms for complex forms — Better structure, validation, and testability

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());
    }
  }
}

Use FormBuilder for cleaner code

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

Use custom validators for complex logic

// 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]

Use async validators for server-side validation

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

Use FormArray for dynamic form fields

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(''));
}

Use
```
updateOn
```
option for performance

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

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

Show validation errors conditionally

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

Use disable() for conditionally disabled fields

// 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 form properly

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

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

复杂表单使用响应式表单 —— 结构更清晰、验证更方便、可测试性更强

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: ['']
  })
});

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

// 函数式验证器（推荐使用）
const forbiddenNameValidator = (control: AbstractControl): ValidationErrors | null => {
  const forbidden = ['admin', 'root', 'superuser'];
  return forbidden.includes(control.value) ? { forbiddenName: true } : null;
};

// 使用示例
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
```
选项优化性能

// 仅在失焦时验证
email: ['', { updateOn: 'blur' }]

// 仅在提交时验证
password: ['', { updateOn: 'submit' }]

条件性展示验证错误

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

使用disable()实现字段的条件禁用

// 根据其他控件的状态切换禁用状态
this.form.statusChanges.subscribe(() => {
  if (this.form.value.isAdmin) {
    this.form.controls.permissions.enable();
  } else {
    this.form.controls.permissions.disable();
  }
});

正确重置表单

// 重置为默认值
this.form.reset({ email: '', name: 'Default' });

// 重置并清空验证规则
this.form.reset();
this.form.clearValidators();