Angular 表单简介link

Introduction to forms in Angularlink

用表单处理用户输入是许多常见应用的基础功能。 应用通过表单来让用户登录、修改个人档案、输入敏感信息以及执行各种数据输入任务。

Handling user input with forms is the cornerstone of many common applications. Applications use forms to enable users to log in, to update a profile, to enter sensitive information, and to perform many other data-entry tasks.

Angular 提供了两种不同的方法来通过表单处理用户输入：响应式表单和模板驱动表单。 两者都从视图中捕获用户输入事件、验证用户输入、创建表单模型、修改数据模型，并提供跟踪这些更改的途径。

Angular provides two different approaches to handling user input through forms: reactive and template-driven. Both capture user input events from the view, validate the user input, create a form model and data model to update, and provide a way to track changes.

本指南提供的信息可以帮你确定哪种方式最适合你的情况。它介绍了这两种方法所用的公共构造块，还总结了两种方式之间的关键区别，并在建立、数据流和测试等不同的情境下展示了这些差异。

This guide provides information to help you decide which type of form works best for your situation. It introduces the common building blocks used by both approaches. It also summarizes the key differences between the two approaches, and demonstrates those differences in the context of setup, data flow, and testing.

先决条件link

Prerequisiteslink

本指南假设你对以下内容有基本的了解。

This guide assumes that you have a basic understanding of the following.

• TypeScript和 HTML5 编程。

  TypeScript and HTML5 programming.

• Angular 的应用设计基础，就像Angular Concepts 中描述的那样。

  Angular app-design fundamentals, as described in Angular Concepts.

• Angular 模板语法的基础知识。

  The basics of Angular template syntax.

选择一种方法link

Choosing an approachlink

响应式表单和模板驱动表单以不同的方式处理和管理表单数据。每种方法都有各自的优点。

Reactive forms and template-driven forms process and manage form data differently. Each approach offers different advantages.

• 响应式表单提供对底层表单对象模型直接、显式的访问。它们与模板驱动表单相比，更加健壮：它们的可扩展性、可复用性和可测试性都更高。如果表单是你的应用程序的关键部分，或者你已经在使用响应式表单来构建应用，那就使用响应式表单。

  Reactive forms provide direct, explicit access to the underlying forms object model. Compared to template-driven forms, they are more robust: they're more scalable, reusable, and testable. If forms are a key part of your application, or you're already using reactive patterns for building your application, use reactive forms.

• 模板驱动表单依赖模板中的指令来创建和操作底层的对象模型。它们对于向应用添加一个简单的表单非常有用，比如电子邮件列表注册表单。它们很容易添加到应用中，但在扩展性方面不如响应式表单。如果你有可以只在模板中管理的非常基本的表单需求和逻辑，那么模板驱动表单就很合适。

  Template-driven forms rely on directives in the template to create and manipulate the underlying object model. They are useful for adding a simple form to an app, such as an email list signup form. They're easy to add to an app, but they don't scale as well as reactive forms. If you have very basic form requirements and logic that can be managed solely in the template, template-driven forms could be a good fit.

关键差异link

Key differenceslink

下表总结了响应式表单和模板驱动表单之间的一些关键差异。

The table below summarizes the key differences between reactive and template-driven forms.

可伸缩性link

Scalabilitylink

如果表单是应用程序的核心部分，那么可伸缩性就非常重要。能够跨组件复用表单模型是至关重要的。

If forms are a central part of your application, scalability is very important. Being able to reuse form models across components is critical.

响应式表单比模板驱动表单更有可伸缩性。它们提供对底层表单 API 的直接访问，并且在视图和数据模型之间使用同步数据流，从而可以更轻松地创建大型表单。响应式表单需要较少的测试设置，测试时不需要深入理解变更检测，就能正确测试表单更新和验证。

Reactive forms are more scalable than template-driven forms. They provide direct access to the underlying form API, and use synchronous data flow between the view and the data model, which makes creating large-scale forms easier. Reactive forms require less setup for testing, and testing does not require deep understanding of change detection to properly test form updates and validation.

模板驱动表单专注于简单的场景，可复用性没那么高。它们抽象出了底层表单 API，并且在视图和数据模型之间使用异步数据流。对模板驱动表单的这种抽象也会影响测试。测试程序非常依赖于手动触发变更检测才能正常运行，并且需要进行更多设置工作。

Template-driven forms focus on simple scenarios and are not as reusable. They abstract away the underlying form API, and use asynchronous data flow between the view and the data model. The abstraction of template-driven forms also affects testing. Tests are deeply reliant on manual change detection execution to run properly, and require more setup.

建立表单模型link

Setting up the form modellink

响应式表单和模板驱动型表单都会跟踪用户与之交互的表单输入元素和组件模型中的表单数据之间的值变更。这两种方法共享同一套底层构建块，只在如何创建和管理常用表单控件实例方面有所不同。

Both reactive and template-driven forms track value changes between the form input elements that users interact with and the form data in your component model. The two approaches share underlying building blocks, but differ in how you create and manage the common form-control instances.

常用表单基础类link

Common form foundation classeslink

响应式表单和模板驱动表单都建立在下列基础类之上。

Both reactive and template-driven forms are built on the following base classes.

• FormControl 实例用于追踪单个表单控件的值和验证状态。

  FormControl tracks the value and validation status of an individual form control.

• FormGroup 用于追踪一个表单控件组的值和状态。

  FormGroup tracks the same values and status for a collection of form controls.

• FormArray 用于追踪表单控件数组的值和状态。

  FormArray tracks the same values and status for an array of form controls.

• ControlValueAccessor 用于在 Angular 的 FormControl 实例和原生 DOM 元素之间创建一个桥梁。

  ControlValueAccessor creates a bridge between Angular FormControl instances and native DOM elements.

建立响应式表单link

Setup in reactive formslink

对于响应式表单，你可以直接在组件类中定义表单模型。[formControl] 指令会通过内部值访问器来把显式创建的 FormControl 实例与视图中的特定表单元素联系起来。

With reactive forms, you define the form model directly in the component class. The [formControl] directive links the explicitly created FormControl instance to a specific form element in the view, using an internal value accessor.

下面的组件使用响应式表单为单个控件实现了一个输入字段。在这个例子中，表单模型是 FormControl 实例。

The following component implements an input field for a single control, using reactive forms. In this example, the form model is the FormControl instance.

      
        content_copy
      
      import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';

@Component({
  selector: 'app-reactive-favorite-color',
  template: `
    Favorite Color: <input type="text" [formControl]="favoriteColorControl">
  `
})
export class FavoriteColorComponent {
  favoriteColorControl = new FormControl('');
}
    

图 1 展示了在响应式表单中，表单模型是如何成为事实之源（source of truth）的。它通过输入元素上的 [formControl] 指令，在任何给定的时间点提供表单元素的值和状态。

Figure 1 shows how, in reactive forms, the form model is the source of truth; it provides the value and status of the form element at any given point in time, through the [formControl] directive on the input element.

图 1. 在响应式表单中直接访问表单模型

Figure 1. Direct access to forms model in a reactive form.

建立模板驱动表单link

Setup in template-driven formslink

在模板驱动表单中，表单模型是隐式的，而不是显式的。指令 NgModel 为指定的表单元素创建并管理一个 FormControl 实例。

In template-driven forms, the form model is implicit, rather than explicit. The directive NgModel creates and manages a FormControl instance for a given form element.

下面的组件使用模板驱动表单为单个控件实现了同样的输入字段。

The following component implements the same input field for a single control, using template-driven forms.

      
        content_copy
      
      import { Component } from '@angular/core';

@Component({
  selector: 'app-template-favorite-color',
  template: `
    Favorite Color: <input type="text" [(ngModel)]="favoriteColor">
  `
})
export class FavoriteColorComponent {
  favoriteColor = '';
}
    

在模板驱动表单中，其事实之源就是模板。你没有对 FormControl 实例的直接编程访问，如图 2 所示。

In a template-driven form the source of truth is the template. You do not have direct programmatic access to the FormControl instance, as shown in Figure 2.

图 2. 模板驱动表单中对表单模型的间接访问。

Figure 2. Indirect access to forms model in a template-driven form.

表单中的数据流link

Data flow in formslink

当应用包含一个表单时，Angular 必须让该视图与组件模型保持同步，并让组件模型与视图保持同步。当用户通过视图更改值并进行选择时，新值必须反映在数据模型中。同样，当程序逻辑改变数据模型中的值时，这些值也必须反映到视图中。

When an application contains a form, Angular must keep the view in sync with the component model and the component model in sync with the view. As users change values and make selections through the view, the new values must be reflected in the data model. Similarly, when the program logic changes values in the data model, those values must be reflected in the view.

响应式表单和模板驱动表单在处理来自用户或程序化变更时的数据处理方式上有所不同。下面的这些示意图会以上面定义的 favorite-color 输入字段为例，分别说明两种表单各自的数据流。

Reactive and template-driven forms differ in how they handle data flowing from the user or from programmatic changes. The following diagrams illustrate both kinds of data flow for each type of form, using the favorite-color input field defined above.

响应式表单中的数据流link

Data flow in reactive formslink

在响应式表单中，视图中的每个表单元素都直接链接到一个表单模型（FormControl 实例）。 从视图到模型的修改以及从模型到视图的修改都是同步的，而且不依赖于 UI 的渲染方式。

In reactive forms each form element in the view is directly linked to the form model (a FormControl instance). Updates from the view to the model and from the model to the view are synchronous and do not depend on how the UI is rendered.

这个视图到模型的示意图展示了当输入字段的值发生变化时数据是如何从视图开始，经过下列步骤进行流动的。

The view-to-model diagram shows how data flows when an input field's value is changed from the view through the following steps.

1. 最终用户在输入框元素中键入了一个值，这里是 "Blue"。

   The user types a value into the input element, in this case the favorite color Blue.

2. 这个输入框元素会发出一个带有最新值的 "input" 事件。

   The form input element emits an "input" event with the latest value.

3. 这个控件值访问器 ControlValueAccessor 会监听表单输入框元素上的事件，并立即把新值传给 FormControl 实例。

   The control value accessor listening for events on the form input element immediately relays the new value to the FormControl instance.

4. FormControl 实例会通过 valueChanges 这个可观察对象发出这个新值。

   The FormControl instance emits the new value through the valueChanges observable.

5. valueChanges 的任何一个订阅者都会收到这个新值。

   Any subscribers to the valueChanges observable receive the new value.

这个模型到视图的示意图体现了程序中对模型的修改是如何通过下列步骤传播到视图中的。

The model-to-view diagram shows how a programmatic change to the model is propagated to the view through the following steps.

1. favoriteColorControl.setValue() 方法被调用，它会更新这个 FormControl 的值。

   The user calls the favoriteColorControl.setValue() method, which updates the FormControl value.

2. FormControl 实例会通过 valueChanges 这个可观察对象发出新值。

   The FormControl instance emits the new value through the valueChanges observable.

3. valueChanges 的任何订阅者都会收到这个新值。

   Any subscribers to the valueChanges observable receive the new value.

4. 该表单输入框元素上的控件值访问器会把控件更新为这个新值。

   The control value accessor on the form input element updates the element with the new value.

模板驱动表单中的数据流link

Data flow in template-driven formslink

在模板驱动表单中，每一个表单元素都是和一个负责管理内部表单模型的指令关联起来的。

In template-driven forms, each form element is linked to a directive that manages the form model internally.

这个视图到模型的图表展示了当输入字段的值发生变化时，数据流是如何从视图开始经过下列步骤进行流动的。

The view-to-model diagram shows how data flows when an input field's value is changed from the view through the following steps.

1. 最终用户在输入框元素中敲 "Blue"。

   The user types Blue into the input element.

2. 该输入框元素会发出一个 "input" 事件，带着值 "Blue"。

   The input element emits an "input" event with the value Blue.

3. 附着在该输入框上的控件值访问器会触发 FormControl 实例上的 setValue() 方法。

   The control value accessor attached to the input triggers the setValue() method on the FormControl instance.

4. FormControl 实例通过 valueChanges 这个可观察对象发出新值。

   The FormControl instance emits the new value through the valueChanges observable.

5. valueChanges 的任何订阅者都会收到新值。

   Any subscribers to the valueChanges observable receive the new value.

6. 控件值访问器 ControlValueAccessory 还会调用 NgModel.viewToModelUpdate() 方法，它会发出一个 ngModelChange 事件。

   The control value accessor also calls the NgModel.viewToModelUpdate() method which emits an ngModelChange event.

7. 由于该组件模板双向数据绑定到了 favoriteColor，组件中的 favoriteColor 属性就会修改为 ngModelChange 事件所发出的值（"Blue"）。

   Because the component template uses two-way data binding for the favoriteColor property, the favoriteColor property in the component is updated to the value emitted by the ngModelChange event (Blue).

这个模型到视图的示意图展示了当 favoriteColor 从蓝变到红时，数据是如何经过如下步骤从模型流动到视图的。

The model-to-view diagram shows how data flows from model to view when the favoriteColor changes from Blue to Red, through the following steps

1. 组件中修改了 favoriteColor 的值。

   The favoriteColor value is updated in the component.

2. 变更检测开始。

   Change detection begins.

3. 在变更检测期间，由于这些输入框之一的值发生了变化，Angular 就会调用 NgModel 指令上的 ngOnChanges 生命周期钩子。

   During change detection, the ngOnChanges lifecycle hook is called on the NgModel directive instance because the value of one of its inputs has changed.

4. ngOnChanges() 方法会把一个异步任务排入队列，以设置内部 FormControl 实例的值。

   The ngOnChanges() method queues an async task to set the value for the internal FormControl instance.

5. 变更检测完成。

   Change detection completes.

6. 在下一个检测周期，用来为 FormControl 实例赋值的任务就会执行。

   On the next tick, the task to set the FormControl instance value is executed.

7. FormControl 实例通过可观察对象 valueChanges 发出最新值。

   The FormControl instance emits the latest value through the valueChanges observable.

8. valueChanges 的任何订阅者都会收到这个新值。

   Any subscribers to the valueChanges observable receive the new value.

9. 控件值访问器 ControlValueAccessor 会使用 favoriteColor 的最新值来修改表单的输入框元素。

   The control value accessor updates the form input element in the view with the latest favoriteColor value.

数据模型的可变性link

Mutability of the data modellink

变更追踪的方法对应用的效率有着重要影响。

The change-tracking method plays a role in the efficiency of your application.

• 响应式表单通过以不可变的数据结构提供数据模型，来保持数据模型的纯粹性。每当在数据模型上触发更改时，FormControl 实例都会返回一个新的数据模型，而不会更新现有的数据模型。这使你能够通过该控件的可观察对象跟踪对数据模型的唯一更改。这让变更检测更有效率，因为它只需在唯一性更改（译注：也就是对象引用发生变化）时进行更新。由于数据更新遵循响应式模式，因此你可以把它和可观察对象的各种运算符集成起来以转换数据。

  Reactive forms keep the data model pure by providing it as an immutable data structure. Each time a change is triggered on the data model, the FormControl instance returns a new data model rather than updating the existing data model. This gives you the ability to track unique changes to the data model through the control's observable. Change detection is more efficient because it only needs to update on unique changes. Because data updates follow reactive patterns, you can integrate with observable operators to transform data.

• 模板驱动的表单依赖于可变性和双向数据绑定，可以在模板中做出更改时更新组件中的数据模型。由于使用双向数据绑定时没有用来对数据模型进行跟踪的唯一性更改，因此变更检测在需要确定何时更新时效率较低。

  Template-driven forms rely on mutability with two-way data binding to update the data model in the component as changes are made in the template. Because there are no unique changes to track on the data model when using two-way data binding, change detection is less efficient at determining when updates are required.

前面那些使用 favorite-color 输入元素的例子就演示了这种差异。

The difference is demonstrated in the previous examples that use the favorite-color input element.

• 对于响应式表单，当控件值更新时，FormControl 的实例总会返回一个新值。

  With reactive forms, the FormControl instance always returns a new value when the control's value is updated.

• 对于模板驱动表单，favorite-color 属性总会被修改为新值。

  With template-driven forms, the favorite color property is always modified to its new value.

表单验证link

Form validationlink

验证是管理任何表单时必备的一部分。无论你是要检查必填项，还是查询外部 API 来检查用户名是否已存在，Angular 都会提供一组内置的验证器，以及创建自定义验证器所需的能力。

Validation is an integral part of managing any set of forms. Whether you're checking for required fields or querying an external API for an existing username, Angular provides a set of built-in validators as well as the ability to create custom validators.

• 响应式表单把自定义验证器定义成函数，它以要验证的控件作为参数。

  Reactive forms define custom validators as functions that receive a control to validate.

• 模板驱动表单和模板指令紧密相关，并且必须提供包装了验证函数的自定义验证器指令。

  Template-driven forms are tied to template directives, and must provide custom validator directives that wrap validation functions.

要了解验证器的更多知识，参阅表单验证。

For more information, see Form Validation.

测试link

Testinglink

测试在复杂的应用程序中也起着重要的作用。当验证你的表单功能是否正确时，更简单的测试策略往往也更有用。测试响应式表单和模板驱动表单的差别之一在于它们是否需要渲染 UI 才能基于表单控件和表单字段变化来执行断言。下面的例子演示了使用响应式表单和模板驱动表单时表单的测试过程。

Testing plays a large part in complex applications. A simpler testing strategy is useful when validating that your forms function correctly. Reactive forms and template-driven forms have different levels of reliance on rendering the UI to perform assertions based on form control and form field changes. The following examples demonstrate the process of testing forms with reactive and template-driven forms.

测试响应式表单link

Testing reactive formslink

响应式表单提供了相对简单的测试策略，因为它们能提供对表单和数据模型的同步访问，而且不必渲染 UI 就能测试它们。在这些测试中，控件和数据是通过控件进行查询和操纵的，不需要和变更检测周期打交道。

Reactive forms provide a relatively easy testing strategy because they provide synchronous access to the form and data models, and they can be tested without rendering the UI. In these tests, status and data are queried and manipulated through the control without interacting with the change detection cycle.

下面的测试利用前面例子中的 "喜欢的颜色" 组件来验证响应式表单中的 "从视图到模型" 和 "从模型到视图" 数据流。

The following tests use the favorite-color components from previous examples to verify the view-to-model and model-to-view data flows for a reactive form.

验证“从视图到模型”的数据流

Verifying view-to-model data flow

第一个例子执行了下列步骤来验证“从视图到模型”数据流。

The first example performs the following steps to verify the view-to-model data flow.

1. 查询表单输入框元素的视图，并为测试创建自定义的 "input" 事件

   Query the view for the form input element, and create a custom "input" event for the test.

2. 把输入的新值设置为 Red，并在表单输入元素上调度 "input" 事件。

   Set the new value for the input to Red, and dispatch the "input" event on the form input element.

3. 断言该组件的 favoriteColorControl 的值与来自输入框的值是匹配的。

   Assert that the component's favoriteColorControl value matches the value from the input.

      
        content_copy
      
      it('should update the value of the input field', () => {
  const input = fixture.nativeElement.querySelector('input');
  const event = createNewEvent('input');

  input.value = 'Red';
  input.dispatchEvent(event);

  expect(fixture.componentInstance.favoriteColorControl.value).toEqual('Red');
});
    

下一个例子执行了下列步骤来验证“从模型到视图”数据流。

The next example performs the following steps to verify the model-to-view data flow.

1. 使用 favoriteColorControl 这个 FormControl 实例来设置新值。

   Use the favoriteColorControl, a FormControl instance, to set the new value.

2. 查询表单中输入框的视图。

   Query the view for the form input element.

3. 断言控件上设置的新值与输入中的值是匹配的。

   Assert that the new value set on the control matches the value in the input.

      
        content_copy
      
      it('should update the value in the control', () => {
  component.favoriteColorControl.setValue('Blue');

  const input = fixture.nativeElement.querySelector('input');

  expect(input.value).toBe('Blue');
});
    

测试模板驱动表单link

Testing template-driven formslink

使用模板驱动表单编写测试就需要详细了解变更检测过程，以及指令在每个变更检测周期中如何运行，以确保在正确的时间查询、测试或更改元素。

Writing tests with template-driven forms requires a detailed knowledge of the change detection process and an understanding of how directives run on each cycle to ensure that elements are queried, tested, or changed at the correct time.

下面的测试使用了以前的 "喜欢的颜色" 组件，来验证模板驱动表单的 "从视图到模型" 和 "从模型到视图" 数据流。

The following tests use the favorite color components mentioned earlier to verify the data flows from view to model and model to view for a template-driven form.

下面的测试验证了 "从视图到模型" 数据流：

The following test verifies the data flow from view to model.

      
        content_copy
      
      it('should update the favorite color in the component', fakeAsync(() => {
     const input = fixture.nativeElement.querySelector('input');
     const event = createNewEvent('input');

     input.value = 'Red';
     input.dispatchEvent(event);

     fixture.detectChanges();

     expect(component.favoriteColor).toEqual('Red');
   }));
    

这个 "视图到模型" 测试的执行步骤如下：

Here are the steps performed in the view to model test.

1. 查询表单输入元素中的视图，并为测试创建自定义 "input" 事件。

   Query the view for the form input element, and create a custom "input" event for the test.

2. 把输入框的新值设置为 Red，并在表单输入框元素上派发 "input" 事件。

   Set the new value for the input to Red, and dispatch the "input" event on the form input element.

3. 通过测试夹具（Fixture）来运行变更检测。

   Run change detection through the test fixture.

4. 断言该组件 favoriteColor 属性的值与来自输入框的值是匹配的。

   Assert that the component favoriteColor property value matches the value from the input.

下面的测试验证了 "从模型到视图" 的数据流：

The following test verifies the data flow from model to view.

      
        content_copy
      
      it('should update the favorite color on the input field', fakeAsync(() => {
     component.favoriteColor = 'Blue';

     fixture.detectChanges();

     tick();

     const input = fixture.nativeElement.querySelector('input');

     expect(input.value).toBe('Blue');
   }));
    

这个 "模型到视图" 测试的执行步骤如下：

Here are the steps performed in the model to view test.

1. 使用组件实例来设置 favoriteColor 的值。

   Use the component instance to set the value of the favoriteColor property.

2. 通过测试夹具（Fixture）来运行变更检测。

   Run change detection through the test fixture.

3. 在 fakeAsync() 任务中使用 tick() 方法来模拟时间的流逝。

   Use the tick() method to simulate the passage of time within the fakeAsync() task.

4. 查询表单输入框元素的视图。

   Query the view for the form input element.

5. 断言输入框的值与该组件实例的 favoriteColor 属性值是匹配的。

   Assert that the input value matches the value of the favoriteColor property in the component instance.

后续步骤link

Next stepslink

要进一步了解响应式表单，参阅下列章节：

To learn more about reactive forms, see the following guides:

• 响应式表单

  Reactive forms

• 表单验证

  Form validation

• 动态表单

  Dynamic forms

要进一步了解模板驱动表单，参阅下列章节：

To learn more about template-driven forms, see the following guides:

• 构建模板驱动表单教程

  Building a template-driven form tutorial

• 表单验证

  Form validation

• NgForm 指令 API 参考手册

  NgForm directive API reference