根据名字将现有 FormGroup 中的 FormControl 与一个表单控件进行同步。

Syncs a FormControl in an existing FormGroup to a form control element by name.





control: FormControl 只读

Tracks the FormControl instance bound to the directive.

name: string

Tracks the name of the FormControl bound to the directive. The name corresponds to a key in the parent FormGroup or FormArray.

isDisabled: boolean

Triggers a warning that this input should not be used with reactive forms.

model: any
update: EventEmitter
path: string[] 只读

Returns an array that represents the path from the top-level form to this control. Each index is the string name of the control on that level.

formDirective: any 只读

The top-level directive for this group if present, otherwise null.

validator: ValidatorFn | null 只读

Synchronous validator function composed of all the synchronous validators registered with this directive.

asyncValidator: AsyncValidatorFn 只读

Async validator function composed of all the async validators registered with this directive.

继承自 NgControl

继承自 AbstractControlDirective


FormControl 注册进一个组

Register FormControl within a group


The following example shows how to register multiple form controls within a form group and set their value.

import {Component} from '@angular/core'; import {FormControl, FormGroup, Validators} from '@angular/forms'; @Component({ selector: 'example-app', template: ` <form [formGroup]="form" (ngSubmit)="onSubmit()"> <div *ngIf="first.invalid"> Name is too short. </div> <input formControlName="first" placeholder="First name"> <input formControlName="last" placeholder="Last name"> <button type="submit">Submit</button> </form> <button (click)="setValue()">Set preset value</button> `, }) export class SimpleFormGroup { form = new FormGroup({ first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew'), }); get first(): any { return this.form.get('first'); } onSubmit(): void { console.log(this.form.value); // {first: 'Nancy', last: 'Drew'} } setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); } }
  1. import {Component} from '@angular/core';
  2. import {FormControl, FormGroup, Validators} from '@angular/forms';
  4. @Component({
  5. selector: 'example-app',
  6. template: `
  7. <form [formGroup]="form" (ngSubmit)="onSubmit()">
  8. <div *ngIf="first.invalid"> Name is too short. </div>
  10. <input formControlName="first" placeholder="First name">
  11. <input formControlName="last" placeholder="Last name">
  13. <button type="submit">Submit</button>
  14. </form>
  15. <button (click)="setValue()">Set preset value</button>
  16. `,
  17. })
  18. export class SimpleFormGroup {
  19. form = new FormGroup({
  20. first: new FormControl('Nancy', Validators.minLength(2)),
  21. last: new FormControl('Drew'),
  22. });
  24. get first(): any { return this.form.get('first'); }
  26. onSubmit(): void {
  27. console.log(this.form.value); // {first: 'Nancy', last: 'Drew'}
  28. }
  30. setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); }
  31. }

要查看把 formControlName 应用于不同类型的表单控件的例子,参见:

To see formControlName examples with different form control types, see:

和 ngModel 一起使用

Use with ngModel

从 Angular v6 开始,已经废弃了在响应式表单中使用输入属性 ngModel 和事件 ngModelChange 的方式,并将在 Angular v7 中移除。

Support for using the ngModel input property and ngModelChange event with reactive form directives has been deprecated in Angular v6 and will be removed in Angular v7.


Now deprecated:

<form [formGroup]="form"> <input formControlName="first" [(ngModel)]="value"> </form>
      <form [formGroup]="form">
  <input formControlName="first" [(ngModel)]="value">
this.value = 'some value';
      this.value = 'some value';

它被废弃有几个理由。 首先,一些开发者觉得这种用法让人困惑。它看起来好像是在使用 ngModel 指令, 但实际上它只是响应式表单指令上的一个名叫 ngModel 的输入/输出属性,只是在行为上和 ngModel 指令有点相似而已。 特别是,它运行获取 / 设置控件值,并拦截值变更事件。 不过,不支持 ngModel 的某些其它特性 - 比如不能用 ngModelOptions 进行延迟修改,也不能导出该指令, 如果没有理解这一点,就会带来一些困惑。

This has been deprecated for a few reasons. First, developers have found this pattern confusing. It seems like the actual ngModel directive is being used, but in fact it's an input/output property named ngModel on the reactive form directive that simply approximates (some of) its behavior. Specifically, it allows getting/setting the value and intercepting value events. However, some of ngModel's other features - like delaying updates withngModelOptions or exporting the directive - simply don't work, which has understandably caused some confusion.

此外,该模式混用了模板驱动表单和响应式表单的策略,我们通常不建议这么实用,因为它无法同时得到这两种策略的全部优点。 在模板中设置值,违背了响应式表单背后的 "模板无关性" 设计原则;而在类中增加 FormControl/FormGroup 层次则破坏了在模板中定义表单带来的便利性。

In addition, this pattern mixes template-driven and reactive forms strategies, which we generally don't recommend because it doesn't take advantage of the full benefits of either strategy. Setting the value in the template violates the template-agnostic principles behind reactive forms, whereas adding a FormControl/FormGroup layer in the class removes the convenience of defining forms in the template.

要在 Angular v7 之前修改你的现有代码,就要决定是钉死在响应式表单指令(并通过响应式表单模式来获取/设置值)或切换到那些模板驱动表单的指令。

To update your code before v7, you'll want to decide whether to stick with reactive form directives (and get/set values using reactive forms patterns) or switch over to template-driven directives.

以后的写法(选择 1 - 使用响应式表单):

After (choice 1 - use reactive forms):

<form [formGroup]="form"> <input formControlName="first"> </form>
      <form [formGroup]="form">
  <input formControlName="first">
this.form.get('first').setValue('some value');
      this.form.get('first').setValue('some value');

以后的写法(选择 2 - 使用模板驱动表单):

After (choice 2 - use template-driven forms):

<input [(ngModel)]="value">
      <input [(ngModel)]="value">
this.value = 'some value';
      this.value = 'some value';

默认情况下,当你使用此模式时,你会在开发模式下看到一个废弃(deprecation)警告。 你可以在导入 ReactiveFormsModule 时提供一个配置项来消除这个警告:

By default, when you use this pattern, you will see a deprecation warning once in dev mode. You can choose to silence this warning by providing a config for ReactiveFormsModule at import time:

imports: [ ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'}); ]
      imports: [
  ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});

或者,你也可以选择指定一个配置值 "always" 来为每个符合这种模式的实例都单独显示一个警告。 这会帮助你在修改代码时追踪代码中用到这种模式的所有位置。

Alternatively, you can choose to surface a separate warning for each instance of this pattern with a config value of "always". This may help to track down where in the code the pattern is being used as the code is being updated.


A lifecycle method called when the directive's inputs change. For internal use only.

ngOnChanges(changes: SimpleChanges)
      ngOnChanges(changes: SimpleChanges)
changes SimpleChanges

A object of key/value pairs for the set of changed inputs.

Lifecycle method called before the directive's instance is destroyed. For internal use only.

ngOnDestroy(): void
      ngOnDestroy(): void




Sets the new value for the view model and emits an ngModelChange event.

viewToModelUpdate(newValue: any): void
      viewToModelUpdate(newValue: any): void
newValue any

The new value for the view model.



继承自 NgControl

继承自 AbstractControlDirective