angular-cn/public/docs/ts/latest/guide/reactive-forms.jade

include ../_util-fns

:marked
  _Reactive forms_ is an Angular technique for creating forms in a _reactive_ style.
  This guide explains reactive forms as you follow the steps to build a "Hero Detail Editor" form.
  
  *响应式表单*是Angular中用*响应式*风格创建表单的技术。
  本章中，我们会在构建"英雄详情编辑器"的过程中，逐步讲解响应式表单的概念。

a#toc
:marked
  ## Contents
  
  ## 目录

  *[Introduction to reactive forms](#intro)

    [响应式表单简介](#intro)

  *[Setup](#setup)

    [准备工作](#setup)

  *[Create a data model](#data-model)

    [创建数据模型](#data-model)

  *[Create a _reactive forms_ component](#create-component)

    [创建*响应式表单*组件](#create-component)

  *[Create its template file](#create-template)

    [创建模板文件](#create-template)

  *[Import the _ReactiveFormsModule_](#import)

    [导入`ReactiveFormsModule`](#import)

  *[Display the _HeroDetailComponent_](#update)

    [显示`HeroDetailComponent`](#update)

  *[Add a FormGroup](#formgroup)

    [添加FormGroup](#formgroup)

  *[Taking a look at the form model](#json)

    [表单模型概览](#json)

  *[Introduction to _FormBuilder_](#formbuilder)

    [`FormBuilder`简介](#formbuilder)

  *[Validators.required](#validators)

  *[Nested FormGroups](#grouping)

    [嵌套的FormGroup](#grouping)

  *[Inspect _FormControl_ properties](#properties)

    [`FormControl`的属性](#properties)

  *[Set form model data using _setValue_ and _patchValue_](#set-data)

    [用`setValue`和`patchValue`设置表单的模型数据](#set-data)

  *[Use _FormArray_ to present an array of _FormGroups_](#form-array)

    [用`FormArray`来表示`FormGroup`的数组](#form-array)

  *[Observe control changes](#observe-control)

    [观察控件的变化](#observe-control)

  *[Save form data](#save)

    [保存表单数据](#save)


  Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker">Reactive Forms live-example</live-example>.
  
  试试<live-example plnkr="final" title="Reactive Forms (final) in Plunker">响应式表单的在线例子</live-example>。

  You can also run the <live-example title="Reactive Forms Demo in Plunker">Reactive Forms Demo</live-example> version
  and choose one of the intermediate steps from the "demo picker" at the top.
  
  你还可以运行<live-example title="Reactive Forms Demo in Plunker">响应式表单的演示程序</live-example>，并从顶部选取一个中间步骤。

a#intro
:marked
  ## Introduction to Reactive Forms
  
  ## 响应式表单简介

  Angular offers two form-building technologies: _reactive_ forms and _template-driven_ forms.
  The two technologies belong to the `@angular/forms` library
  and share a common set of form control classes.
  
  Angular提供了两种构建表单的技术：*响应式*表单和*模板驱动*表单。
  这两项技术都属于`@angular/forms`库，并且共享一组公共的表单控件类。

  But they diverge markedly in philosophy, programming style, and technique.
  They even have their own modules: the `ReactiveFormsModule` and the `FormsModule`.
  
  但是它们在设计哲学、编程风格和具体技术上有显著区别。
  所以，它们都有自己的模块：`ReactiveFormsModule` 和 `FormsModule`。

  ### _Reactive_ forms
  
  ### *响应式*表单
  
  Angular _reactive_ forms facilitate a _reactive style_ of programming 
  that favors explicit management of the data flowing between
  a non-UI _data model_ (typically retrieved from a server) and a 
  UI-oriented _form model_ that retains the states 
  and values of the HTML controls on screen. Reactive forms offer the ease 
  of using reactive patterns, testing, and validation.
  
  Angular的*响应式*表单能让实现*响应式编程风格*更容易，这种编程风格更喜欢在非UI的*数据模型*（通常接收自服务器）之间显式的管理数据流，
  并且用一个UI导向的*表单模型*来保存屏幕上HTML控件的状态和值。
  响应式表单可以让使用响应式编程模式、测试和校验变得更容易。

  With _reactive_ forms, you create a tree of Angular form control objects
  in the component class and bind them to native form control elements in the 
  component template, using techniques described in this guide. 
  
  使用*响应式*表单，我们可以在组件中创建表单控件的对象树，并使用本章中传授的技巧把它们绑定到组件模板中的原生表单控件元素上。

  You create and manipulate form control objects directly in the 
  component class. As the component class has immediate access to both the data 
  model and the form control structure, you can push data model values into 
  the form controls and pull user-changed values back out. The component can 
  observe changes in form control state and react to those changes.
  
  我们可以在组件类中直接创建和维护表单控件对象。由于组件类可以同时访问数据模型和表单控件结构，
  因此我们可以把表单模型值的变化推送到表单控件中，并把变化后的值拉取回来。
  组件可以监听表单控件状态的变化，并对此做出响应。

  One advantage of working with form control objects directly is that value and validity updates 
  are [always synchronous and under your control](#async-vs-sync "Async vs sync"). 
  You won't encounter the timing issues that sometimes plague a template-driven form
  and reactive forms can be easier to unit test.
  
  直接使用表单控件对象的优点之一是值和有效性状态的更新[总是同步的，并且在你的控制之下](#async-vs-sync "Async vs sync")。
  我们不会遇到时序问题，这个问题有时在模板驱动表单中会成为灾难。而且响应式表单更容易进行单元测试。

  In keeping with the reactive paradigm, the component 
  preserves the immutability of the _data model_,
  treating it as a pure source of original values.
  Rather than update the data model directly, 
  the component extracts user changes and forwards them to an external component or service, 
  which does something with them (such as saving them) 
  and returns a new _data model_ to the component that reflects the updated model state. 
  
  在响应式编程范式中，组件会负责维护*数据模型*的不可变性，把模型当做纯粹的原始数据源。
  组件不会直接更新数据模型，而是把用户的修改提取出来，把它们转发给外部的组件或服务，外部程序才会使用这些进行处理（比如保存它们），
  并且给组件返回一个新的*数据模型*，以反映模型状态的变化。
    
  Using reactive form directives does not require you to follow all reactive priniciples, 
  but it does facilitate the reactive programming approach should you choose to use it.
  
  使用响应式表单的指令，并不要求你遵循所有的响应式编程原则，但它能让你更容易使用响应式编程方法，从而更愿意使用它。

  ### _Template-driven_ forms
  
  ### *模板驱动*表单

  _Template-driven_ forms, introduced in the [Template guide](forms.html), take a completely different approach.
  
  在[模板](forms.html)一章我们介绍过的*模板驱动*表单，是一种完全不同的方式。
  
  You place HTML form controls (such as `<input>` and `<select>`) in the component template and 
  bind them to _data model_ properties in the component, using directives 
  like `ngModel`.
  
  我们把HTML表单控件（比如`<input>`和`<select>`）放进组件模板中，并用`ngModel`等指令把它们绑定到组件中*数据模型*的属性上。

  You don't create Angular form control objects. Angular directives 
  create them for you, using the information in your data bindings. 
  You don't push and pull data values. Angular handles that for you with `ngModel`.
  Angular updates the mutable _data model_ with user changes as they happen.
  
  我们不用自己创建Angular表单控件对象。Angular指令会使用数据绑定中的信息创建它们。
  我们不用自己推送和拉取数据。Angular使用`ngModel`来替你管理它们。
  当用户做出修改时，Angular会据此更新可变的*数据模型*。

  For this reason, the `ngModel` directive is not part of the ReactiveFormsModule.
  
  因此，`ngModel`并不是`ReactiveFormsModule`模块的一部分。

  While this means less code in the component class, 
  [template-driven forms are asynchronous](#async-vs-sync "Async vs sync")
  which may complicate development in more advanced scenarios. 
  
  虽然这意味着组件中的代码更少，但是[模板驱动表单是异步工作的](#async-vs-sync "Async vs sync")，这可能在更高级的场景中让开发复杂化。

a#async-vs-sync
:marked
  ### Async vs. sync
  
  ### 异步 vs. 同步

  Reactive forms are synchronous. Template-driven forms are asynchronous. It's a difference that matters.
  
  响应式表单是同步的。模板驱动表单是异步的。这个不同点很重要。

  In reactive forms, you create the entire form control tree in code. 
  You can immediately update a value or drill down through the descendents of the parent form 
  because all controls are always available.
  
  使用响应式表单，我们会在代码中创建整个表单控件树。
  我们可以立即更新一个值或者深入到表单中的任意节点，因为所有的控件都始终是可用的。

  Template-driven forms delegate creation of their form controls to directives.
  To avoid "_changed after checked_" errors, 
  these directives take more than one cycle to build the entire control tree.
  That means you must wait a tick before manipulating any of the controls
  from within the component class.
  
  模板驱动表单会委托指令来创建它们的表单控件。
  为了消除"检查完后又变化了"的错误，这些指令需要消耗一个以上的变更检测周期来构建整个控件树。
  这意味着在从组件类中操纵任何控件之前，我们都必须先等待一个节拍。
  
  For example, if you inject the form control with a `@ViewChild(NgForm)` query and examine it in the 
  [`ngAfterViewInit` lifecycle hook](lifecycle-hooks.html#afterview "Lifecycle hooks guide: AfterView"),
  you'll discover that it has no children.
  You must wait a tick, using `setTimeout`, before you can
  extract a value from a control, test its validity, or set it to a new value.
  
  比如，如果我们用`@ViewChild(NgForm)`查询来注入表单控件，并在[生命周期钩子`ngAfterViewInit`](lifecycle-hooks.html#afterview "Lifecycle hooks guide: AfterView")中检查它，就会发现它没有子控件。
  我们必须使用`setTimeout`等待一个节拍才能从控件中提取值、测试有效性，或把它设置为新值。
  
  The asynchrony of template-driven forms also complicates unit testing. 
  You must wrap your test block in `async()` or `fakeAsync()` to 
  avoid looking for values in the form that aren't there yet. 
  With reactive forms, everything is available when you expect it to be.
  
  模板驱动表单的异步性让单元测试也变得复杂化了。
  我们必须把测试代码包裹在`async()`或`fakeAsync()`中来解决要查阅的值尚不存在的情况。
  使用响应式表单，在所期望的时机一切都是可用的。

  ### Which is better, reactive or template-driven? 
  
  ### 哪一个更好？响应式还是模板驱动？

  Neither is "better".
  They're two different architectural paradigms, 
  with their own strengths and weaknesses.
  Choose the approach that works best for you.
  You may decide to use both in the same application.
  
  没有哪个"更好"。
  它们是两种架构范式，各有优缺点。
  请自行选择更合适的方法，甚至可以在同一个应用中同时使用它们。

  The balance of this _reactive forms_ guide explores the _reactive_ paradigm and 
  concentrates exclusively on reactive forms techniques. 
  For information on _template-driven forms_, see the [_Forms_](forms.html) guide.
  
  在这章*响应式表单*中，我们只专注于*响应式*范式以及响应式表单技术的详情。

  In the next section, you'll set up your project for the reactive form demo.
  Then you'll learn about the [Angular form classes](#essentials) and how to use them in a reactive form.
  
  在下一节，我们将先准备一个响应式表单范例的项目，然后就可以开始学习[Angular表单类](#essentials)，并在响应式表单中使用它们了。

.l-main-section
a#setup
:marked
  ## Setup
  
  ## 准备工作

  Follow the steps in the [_Setup_ guide](../guide/setup.html "Setup guide") 
  for creating a new project folder (perhaps called `reactive-forms`)
  based on the _QuickStart seed_.
  
  遵循[*准备工作*一章](../guide/setup.html "Setup guide")中的步骤基于*快速起步种子工程*创建一个新的项目目录（比如叫`reactive-forms`）。 

.l-main-section
a#data-model
:marked
  ## Create a data model
  
  ## 创建数据模型
  
  The focus of this guide is a reactive forms component that edits a hero.
  You'll need a `hero` class and some hero data.
  Create a new `data-model.ts` file in the `app` directory and copy the content below into it.
  
  本章的焦点是响应式表单组件以及编辑一个英雄。
  我们需要一个`Hero`类和一些英雄数据。
  在`app`目录下创建一个`data-model.ts`文件，并粘贴进下列内容：

+makeExample('reactive-forms/ts/src/app/data-model.ts', '','src/app/data-model.ts')(format=".")

:marked
  The file exports two classes and two constants. The `Address` 
  and `Hero` classes define the application _data model_. 
  The `heroes` and `states` constants supply the test data. 
  
  这个文件导出两个类和两个常量。`Address`和`Hero`类定义应用的*数据模型*。
  `heroes`和`states`常量提供测试数据。

.l-main-section
a#create-component
:marked
  ## Create a _reactive forms_ component
  
  ## 创建*响应式表单*组件
  
  Make a new file called 
  `hero-detail.component.ts` in the `app` directory and import these symbols:
  
  在`app`目录下创建一个名叫`hero-detail.component.ts`的新文件，并且导入下列符号：

+makeExample('reactive-forms/ts/src/app/hero-detail-1.component.ts', 'imports','src/app/hero-detail.component.ts')(format=".")

:marked
  Now enter the `@Component` decorator that specifies the `HeroDetailComponent` metadata:
  
  然后输入这个`@Component`来为`HeroDetailComponent`指定元数据：

+makeExample('reactive-forms/ts/src/app/hero-detail.component.ts', 'metadata','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  Next, create an exported `HeroDetailComponent` class with a `FormControl`. 
  `FormControl` is a directive that allows you to create and manage 
  a `FormControl` instance directly.
  
  
  接下来，创建并导出一个带`FormControl`的`HeroDetailComponent`类。
  `FormControl`是一个指令，它允许我们直接创建并管理一个`FormControl`实例。
  

+makeExample('reactive-forms/ts/src/app/hero-detail-1.component.ts', 'v1','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  Here you are creating a `FormControl` called `name`. 
  It will be bound in the template to an HTML `input` box for the hero name. 
  
  这里我们创建了一个名叫`name`的`FormControl`。
  它将会绑定到模板中的一个`input`框，表示英雄的名字。

  A `FormControl` constructor accepts three, optional arguments: 
  the initial data value, an array of validators, and an array of async validators.
  
  `FormControl`构造函数接收三个可选参数：
  初始值、验证器数组和异步验证器数组。
  
  This simple control doesn't have data or validators.
  In real apps, most form controls have both. 
  
  最简单的控件并不需要数据或验证器，但是在实际应用中，大部分表单控件都会同时具备它们。

.l-sub-section
  :marked
    This guide touches only briefly on `Validators`. For an in-depth look at them,
    read the [Form Validation](../cookbook/form-validation.html) cookbook.
    
    本章中只会接触`Validators`中的一点点，要想更深入的了解它们，请阅读烹饪宝典中的[表单验证](../cookbook/form-validation.html)一章。

.l-main-section
a#create-template
:marked
  ## Create the template
  
  ## 创建模板

  Now create the component's template, `src/app/hero-detail.component.html`, with the following markup.
  
  现在，在创建组件的模板文件`src/app/hero-detail.component.html`，内容如下：

+makeExample('reactive-forms/ts/src/app/hero-detail-1.component.html', 'simple-control','src/app/hero-detail.component.html')(format=".")

:marked
  To let Angular know that this is the input that you want to 
  associate to the `name` `FormControl` in the class, 
  you need `[formControl]="name"` in the template on the `<input>`. 
  
  要让Angular知道我们希望把这个输入框关联到类中的`FormControl`型属性`name`，我们需要在模板中的`<input>`上加一句`[formControl]="name"`。
  

.l-sub-section
  :marked
    Disregard the `form-control` _CSS_ class. It belongs to the 
    <a href="http://getbootstrap.com/" target="_blank" title="Bootstrap CSS">Bootstrap CSS library</a>,
    not Angular.
    It _styles_ the form but in no way impacts the logic of the form.
    
    请忽略CSS类`form-control`，它属于<a href="http://getbootstrap.com/" target="_blank" title="Bootstrap CSS">Bootstrap CSS library</a>而不是Angular。
    它会为表单添加样式，但是对表单的逻辑毫无影响。

a#import
:marked
  ## Import the _ReactiveFormsModule_
  
  ## 导入`ReactiveFormsModule`

  The HeroDetailComponent template uses `formControlName` 
  directive from the `ReactiveFormsModule`.
  
  `HeroDetailComponent`的模板中使用了来自`ReactiveFormsModule`的`formControlName`。
  
  In this sample, you declare the `HeroDetailComponent` in the `AppModule`.
  Therefore, do the following three things in `app.module.ts`:
  
  在这个例子中，我们在`AppModule`中声明了`HeroDetailComponent`。因此现在`app.module.ts`中做了三件事：

  1. Use a JavaScript `import` statement to access 
  the `ReactiveFormsModule` and the `HeroDetailComponent`.
  
    使用JavaScript的`import`语句访问`ReactiveFormsModule`和`HeroDetailComponent`。
    
  1. Add `ReactiveFormsModule` to the `AppModule`'s `imports` list.
  
    把`ReactiveFormsModule`添加到`AppModule`的`imports`列表中。
    
  1. Add `HeroDetailComponent` to the declarations array.
  
    把`HeroDetailComponent`添加到声明数组中。

+makeExample('reactive-forms/ts/src/app/app.module.ts', 'v1','src/app/app.module.ts (excerpt)')(format=".")

a#update
.l-main-section
:marked
  ## Display the _HeroDetailComponent_
  
  ## 显示`HeroDetailComponent`
  
  Revise the `AppComponent` template so it displays the `HeroDetailComponent`.
  
  修改`AppComponent`的模板，以便显示`HeroDetailComponent`。
  
+makeExample('reactive-forms/ts/src/app/app.component.1.ts', '','src/app/app.component.ts')(format=".")

a#essentials
:marked
  ### Essential form classes
  
  ### 基础的表单类
  
  It may be helpful to read a brief description of the core form classes.
  
  阅读一下这些核心表单类的简短描述也许会有用。
  
  * [_AbstractControl_](../api/forms/index/AbstractControl-class.html "API Reference: AbstractControl")
  is the abstract base class for the three concrete form control classes: 
  `FormControl`, `FormGroup`, and `FormArray`.
  It provides their common behaviors and properties, some of which are _observable_.
  
    [`AbstractControl`](../api/forms/index/AbstractControl-class.html "API Reference: AbstractControl")是三个具体表单类的抽象基类。
    并为它们提供了一些共同的行为和属性，其中有些是*可观察对象（Observable）*。

  * [_FormControl_](../api/forms/index/FormControl-class.html "API Reference: FormControl") 
  tracks the value and validity status of an _individual_ form control.
  It corresponds to an HTML form control such as an input box or selector.
  
    [_FormControl_](../api/forms/index/FormControl-class.html "API Reference: FormControl")
    用于跟踪一个*单独的*表单控件的值和有效性状态。它对应于一个HTML表单控件，比如输入框和下拉框。

  * [_FormGroup_](../api/forms/index/FormGroup-class.html "API Reference: FormGroup")
  tracks the value and validity state of a _group_ of `AbstractControl` instances.
  The group's properties include its child controls.
  The top-level form in your component is a `FormGroup`.
  
    [_FormGroup_](../api/forms/index/FormGroup-class.html "API Reference: FormGroup")用于
    跟踪*一组*`AbstractControl`的实例的值和有效性状态。
    该组的属性中包含了它的子控件。
    组件中的顶级表单就是一个`FormGroup`。

  * [_FormArray_](../api/forms/index/FormArray-class.html "API Reference: FormArray")
  tracks the value and validity state of a numerically indexed _array_ of `AbstractControl` instances.
  
    [_FormArray_](../api/forms/index/FormArray-class.html "API Reference: FormArray")用于跟踪`AbstractControl`实例组成的有序数组的值和有效性状态。

  You'll learn more about these classes as you work through this guide.
  
  随着本章的深入，我们将学到关于这三个类的更多知识。


:marked
  ### Style the app
  
  ### 为应用添加样式
  
  You used bootstrap CSS classes in the template HTML of both the `AppComponent` and the `HeroDetailComponent`.
  Add the `bootstrap` _CSS stylesheet_ to the head of `index.html`:
  
  我们在`AppComponent`和`HeroDetailComponent`的模板中使用Bootstrap中的CSS类。请把`bootstrap`的*CSS样式表文件*添加到`index.html`的`head`区。

+makeExample('reactive-forms/ts/src/index.html', 'bootstrap','index.html')(format=".")

:marked
  Now that everything is wired up, the browser should display something like this: 
  
  这些做好之后，浏览器中应该显示成这样：

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/just-formcontrol.png" width="400px" alt="Single FormControl")

a#formgroup
:marked
  ## Add a FormGroup
  
  ## 添加FormGroup
  
  Usually, if you have multiple *FormControls*, you'll want to register 
  them within a parent `FormGroup`.
  This is simple to do. To add a `FormGroup`, add it to the imports section 
  of `hero-detail.component.ts`:
  
  通常，如果有多个*FormControl*，我们会希望把它们注册进一个父`FormGroup`中。这很容易。只要把它加入`hero-detail.component.ts`的`import`区就可以了。

+makeExample('reactive-forms/ts/src/app/hero-detail-2.component.ts', 'imports','src/app/hero-detail.component.ts')(format=".")

:marked
  In the class, wrap the `FormControl` in a `FormGroup` called `heroForm` as follows:
  
  在这个类中，把`FormControl`包裹进了一个名叫`heroForm`的`FormGroup`中，代码如下：

+makeExample('reactive-forms/ts/src/app/hero-detail-2.component.ts', 'v2','src/app/hero-detail.component.ts')(format=".")

:marked
  Now that you've made changes in the class, they need to be reflected in the 
  template. Update `hero-detail.component.html` by replacing it with the following.
  
  现在我们改完了这个类，该把它映射到模板中了。把`hero-detail.component.html`改成这样：

+makeExample('reactive-forms/ts/src/app/hero-detail-2.component.html', 'basic-form','src/app/hero-detail.component.html')(format=".")

:marked
  Notice that now the single input is in a `form` element. The `novalidate` 
  attribute in the `<form>` element prevents the browser 
  from attempting native HTML validations. 
  
  注意，现在单行输入框位于一个`form`元素中。`<form>`元素上的`novalidate`属性会阻止浏览器使用原生HTML中的表单验证器。

  `formGroup` is a reactive form directive that takes an existing 
  `FormGroup` instance and associates it with an HTML element. 
  In this case, it associates the `FormGroup` you saved as 
  `heroForm` with the form element.
  
  `formGroup`是一个响应式表单的指令，它拿到一个现有`FormGroup`实例，并把它关联到一个HTML元素上。
  这种情况下，它关联到的是`form`元素上的`FormGroup`实例`heroForm`。

  Because the class now has a `FormGroup`, you must update the template 
  syntax for associating the input with the corresponding 
  `FormControl` in the component class. 
  Without a parent `FormGroup`, 
  `[formControl]="name"` worked earlier because that directive 
  can stand alone, that is, it works without being in a `FormGroup`. 
  With a parent `FormGroup`, the `name` input needs the syntax 
  `formControlName=name` in order to be associated 
  with the correct `FormControl` 
  in the class. This syntax tells Angular to look for the parent 
  `FormGroup`, in this case `heroForm`, and then _inside_ that group 
  to look for a `FormControl` called `name`.
  
  由于现在有了一个`FormGroup`，因此我们必须修改模板语法来把输入框关联到组件类中对应的`FormControl`上。
  以前没有父`FormGroup`的时候，`[formControl]="name"`也能正常工作，因为该指令可以独立工作，也就是说，不在`FormGroup`中时它也能用。
  有了`FormGroup`，`name`输入框就需要再添加一个语法`formControlName=name`，以便让它关联到类中正确的`FormControl`上。
  这个语法告诉Angular，查阅父`FormGroup`（这里是`heroForm`），然后在这个`FormGroup`中查阅一个名叫`name`的`FormControl`。

.l-sub-section
  :marked
    Disregard the `form-group` _CSS_ class. It belongs to the 
    <a href="http://getbootstrap.com/" target="_blank" title="Bootstrap CSS">Bootstrap CSS library</a>,
    not Angular.
    Like the `form-control` class, it _styles_ the form 
    but in no way impacts its logic.

    请无视*CSS*类`form-group`，它属于<a href="http://getbootstrap.com/" target="_blank" title="Bootstrap CSS">Bootstrap CSS library</a>而不是Angular。
    就像`form-control`类一样，它只是为表单添加样式，而对表单逻辑毫无影响。

:marked
  The form looks great. But does it work? 
  When the user enters a name, where does the value go? 
  
  表单看起来很棒，但是它能用吗？
  当用户输入名字时，它的值去了哪里？

a#json
:marked
  ## Taking a look at the form model
  
  表单模型概览
  
  The value goes into the **_form model_** that backs the group's `FormControls`.
  To see the form model, add the following line after the 
  closing `form` tag in the `hero-detail.component.html`:
  
  这个值进入了幕后**表单模型**中的`FormControl`构成的表单组。
  要想知道表单模型是什么样的，请在`hero-detail.component.html`的`form`标签紧后面添加如下代码：

+makeExample('reactive-forms/ts/src/app/hero-detail-3.component.html', 'form-value-json','src/app/hero-detail.component.html')(format=".")

:marked
  The `heroForm.value` returns the _form model_.
  Piping it through the `JsonPipe` renders the model as JSON in the browser:
  
  `heroForm.value`会返回表单模型。
  用`JsonPipe`管道把这个模型以JSON格式渲染到浏览器中。

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/json-output.png" width="400px" alt="JSON output")

:marked
  The initial `name` property value is the empty string. 
  Type into the _name_ input box and watch the keystokes appear in the JSON.



  最初的`name`属性是个空字符串，在*name*输入框中输入之后，可以看到这些按键出现在了JSON中。
  

:marked
  Great! You have the basics of a form. 
  
  真棒！我们有了一个基本版表单。
  
  In real life apps, forms get big fast. 
  `FormBuilder` makes form development and maintenance easier.

  
  在真实的应用中，表单很快就会变大。
  `FormBuilder`能让表单开发和维护变得更简单。

.l-main-section
a#formbuilder
:marked
  ## Introduction to _FormBuilder_
  
  ## `FormBuilder`简介

  The `FormBuilder` class helps reduce repetition and 
  clutter by handling details of control creation for you. 
  
  `FormBuilder`类能通过处理控件创建的细节问题来帮我们减少重复劳动。

  To use `FormBuilder`, you need to import it into `hero-detail.component.ts`:
  
  要使用`FormBuilder`，我们就要先把它导入到`hero-detail.component.ts`中：
  
+makeExample('reactive-forms/ts/src/app/hero-detail-3a.component.ts', 'imports','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  Use it now to refactor the `HeroDetailComponent` into something that's a little easier to read and write,
  by following this plan:
  
  现在，我们遵循下列步骤用`FormBuilder`来把`HeroDetailComponent`重构得更加容易读写。

  * Explicitly declare the type of the `heroForm` property to be `FormGroup`; you'll initialize it later.
  
    明确把`heroForm`属性的类型声明为`FormGroup`，稍后我们会初始化它。
    
  * Inject a `FormBuilder` into the constructor.
  
    把`FormBuilder`注入到构造函数中。
    
  * Add a new method that uses the `FormBuilder` to define the `heroForm`; call it `createForm`.
  
    添加一个名叫`createForm`的新方法，它会用`FormBuilder`来定义`heroForm`。
    
  * Call `createForm` in the constructor.
  
    在构造函数中调用`createForm`。

  The revised `HeroDetailComponent` looks like this:
  
  修改过的`HeroDetailComponent`代码如下：
  
+makeExample('reactive-forms/ts/src/app/hero-detail-3a.component.ts', 'v3a','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  `FormBuilder.group` is a factory method that creates a `FormGroup`. &nbsp;
  `FormBuilder.group` takes an object whose keys and values are `FormControl` names and their definitions. 
  In this example, the `name` control is defined by its initial data value, an empty string.
  
  `FormBuilder.group`是一个用来创建`FormGroup`的工厂方法，它接受一个对象，对象的键和值分别是`FormControl`的名字和它的定义。
  在这个例子中，`name`控件的初始值是空字符串。

  Defining a group of controls in a single object makes for a compact, readable style.
  It beats writing an equivalent series of `new FormControl(...)` statements.
  
  把一组控件定义在一个单一对象中，可以更加紧凑、易读。
  完成相同功能时，这种形式优于一系列`new FormControl(...)`语句。

a#validators
:marked
 ### Validators.required
 
 Though this guide doesn't go deeply into validations, here is one example that 
 demonstrates the simplicity of using `Validators.required` in reactive forms. 

 First, import the `Validators` symbol.
+makeExample('reactive-forms/ts/src/app/hero-detail-3.component.ts', 'imports','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
 To make the `name` `FormControl` required, replace the `name` 
 property in the `FormGroup` with an array. 
 The first item is the initial value for `name`;
 the second is the required validator, `Validators.required`.

+makeExample('reactive-forms/ts/src/app/hero-detail-3.component.ts', 'required','src/app/hero-detail.component.ts (excerpt)')(format=".")
.l-sub-section
  :marked
    Reactive validators are simple, composable functions.
    Configuring validation is harder in template-driven forms where you must wrap validators in a directive. 
:marked
  Update the diagnostic message at the bottom of the template to display the form's validity status.

+makeExample('reactive-forms/ts/src/app/hero-detail-3.component.html', 'form-value-json','src/app/hero-detail.component.html (excerpt)')(format=".")
  
:marked
  The browser displays the following:

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/validators-json-output.png" width="400px" alt="Single FormControl")

:marked
  `Validators.required` is working. The status is `INVALID` because the input box has no value.
  Type into the input box to see the status change from `INVALID` to `VALID`. 

  In a real app, you'd replace the diagnosic message with a user-friendly experience.
  
:marked
  Using `Validators.required` is optional for the rest of the guide. 
  It remains in each of the following examples with the same configuration.

  For more on validating Angular forms, see the
  [Form Validation](../cookbook/form-validation.html) guide. 

:marked
  ### More FormControls
  A hero has more than a name. 
  A hero has an address, a super power and sometimes a sidekick too. 
  
  The address has a state property. The user will select a state with a `<select>` box and you'll populate 
  the `<option>` elements with states. So import `states` from `data-model.ts`.
+makeExample('reactive-forms/ts/src/app/hero-detail-4.component.ts', 'imports','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  Declare the `states` property and add some address `FormControls` to the `heroForm` as follows. 

+makeExample('reactive-forms/ts/src/app/hero-detail-4.component.ts', 'v4','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  Then add corresponding markup in `hero-detail.component.html` 
  within the `form` element.

+makeExample('reactive-forms/ts/src/app/hero-detail-4.component.html', '','src/app/hero-detail.component.html')(format=".")

.alert.is-helpful
  :marked
    *Reminder*: Ignore the many mentions of `form-group`, 
    `form-control`, `center-block`, and `checkbox` in this markup.
    Those are _bootstrap_ CSS classes that Angular itself ignores.
    Pay attention to the `formGroupName` and `formControlName` attributes.
    They are the Angular directives that bind the HTML controls to the 
    Angular `FormGroup` and `FormControl` properties in the component class.

:marked
  The revised template includes more text inputs, a select box for the `state`, radio buttons for the `power`, 
  and a checkbox for the `sidekick`. 
  
  You must bind the option's value property with `[value]="state"`. 
  If you do not bind the value, the select shows the first option from the data model.

  The component _class_ defines control properties without regard for their representation in the template.
  You define the `state`, `power`, and `sidekick` controls the same way you defined the `name` control.
  You tie these controls to the template HTML elements in the same way, 
  specifiying the `FormControl` name with the `formControlName` directive. 

  See the API reference for more information about 
  [radio buttons](../api/forms/index/RadioControlValueAccessor-directive.html "API: RadioControlValueAccessor"), 
  [selects](../api/forms/index/SelectControlValueAccessor-directive.html "API: SelectControlValueAccessor"), and
  [checkboxes](../api/forms/index/CheckboxControlValueAccessor-directive.html "API: CheckboxControlValueAccessor").

.l-main-section
a#grouping
:marked
  ### Nested FormGroups

  This form is getting big and unwieldy. You can group some of the related `FormControls` 
  into a nested `FormGroup`. The `street`, `city`, `state`, and `zip` are properties 
  that would make a good _address_ `FormGroup`.
  Nesting groups and controls in this way allows you to 
  mirror the hierarchical structure of the data model 
  and helps track validation and state for related sets of controls. 
  
  You used the `FormBuilder` to create one `FormGroup` in this component called `heroForm`.
  Let that be the parent `FormGroup`.
  Use `FormBuilder` again to create a child `FormGroup` that encapsulates the address controls;
  assign the result to a new `address` property of the parent `FormGroup`.
+makeExample('reactive-forms/ts/src/app/hero-detail-5.component.ts', 'v5','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  You’ve changed the structure of the form controls in the component class; 
  you must make corresponding adjustments to the component template.
  
  In `hero-detail.component.html`, wrap the address-related `FormControls` in a `div`.
  Add a `formGroupName` directive to the `div` and bind it to `"address"`.
  That's the property of the _address_ child `FormGroup` within the parent `FormGroup` called `heroForm`.
  
  To make this change visually obvious, slip in an `<h4>` header near the top with the text, _Secret Lair_. 
  The new _address_ HTML looks like this:

+makeExample('reactive-forms/ts/src/app/hero-detail-5.component.html', 'add-group','src/app/hero-detail.component.html (excerpt)')(format=".")

:marked
  After these changes, the JSON output in the browser shows the revised _form model_
  with the nested address `FormGroup`: 

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/address-group.png" width="400px" alt="JSON output")

:marked
  Great! You’ve made a group and you can see that the template 
  and the form model are talking to one another.

.l-main-section
a#properties

:marked
  ## Inspect _FormControl_ Properties
  At the moment, you're dumping the entire form model onto the page.
  Sometimes you're interested only in the state of one particular `FormControl`.

  You can inspect an individual `FormControl` within a form by extracting it with the `.get()` method.
  You can do this _within_ the component class or display it on the 
  page by adding the following to the template, 
  immediately after the `{{form.value | json}}` interpolation as follows: 

+makeExample('reactive-forms/ts/src/app/hero-detail-5.component.html', 'inspect-value','src/app/hero-detail.component.html')(format=".")

:marked
  To get the state of a `FormControl` that’s inside a `FormGroup`, use dot notation to path to the control.

+makeExample('reactive-forms/ts/src/app/hero-detail-5.component.html', 'inspect-child-control','src/app/hero-detail.component.html')(format=".")

:marked
  You can use this technique to display _any_ property of a `FormControl` 
  such as one of the following:
style td, th {vertical-align: top}
table(width="100%")
  col(width="10%")
  col(width="90%")
  tr
    th Property
    th Description
  tr
    td <code>myControl.value</code>
    td
      :marked
         the value of a `FormControl`.
  tr
    td <code>myControl.status</code>
    td
      :marked
        the validity of a `FormControl`. Possible values: `VALID`, 
         `INVALID`, `PENDING`, or `DISABLED`.
  tr
    td <code>myControl.pristine</code>
    td
      :marked
         `true` if the user has _not_ changed the value in the UI.
         Its opposite is `myControl.dirty`.
  tr
    td <code>myControl.untouched</code>
    td
      :marked
         `true` if the control user has not yet entered the HTML control
          and triggered its blur event. Its opposite is `myControl.touched`.
                                  
:marked
  Learn about other `FormControl` properties in the 
  [_AbstractControl_](../api/forms/index/AbstractControl-class.html) API reference.

  One common reason for inspecting `FormControl` properties is to 
  make sure the user entered valid values. 
  Read more about validating Angular forms in the 
  [Form Validation](../cookbook/form-validation.html) guide. 

.l-main-section
a#data-model-form-model
:marked
  ## The _data model_ and the _form model_

  At the moment, the form is displaying empty values.
  The `HeroDetailComponent` should display values of a hero,
  possibly a hero retrieved from a remote server.

  In this app, the `HeroDetailComponent` gets its hero from a parent `HeroListComponent`

  The `hero` from the server is the **_data model_**.
  The `FormControl` structure is the **_form model_**.
 
  The component must copy the hero values in the _data model_ into the _form model_.
  There are two important implications:

  1. The developer must understand how the properties of the _data model_ 
  map to the properties of the _form model_.

  2. User changes flow from the DOM elements to the _form model_, not to the _data model_.
  The form controls never update the _data model_.

  The _form_ and _data_ model structures need not match exactly.
  You often present a subset of the _data model_ on a particular screen.
  But it makes things easier if the shape of the _form model_ is close to the shape of the _data model_.
  
  In this `HeroDetailComponent`, the two models are quite close.

  Recall the definition of `Hero` in `data-model.ts`:
+makeExample('reactive-forms/ts/src/app/data-model.ts', 'model-classes','src/app/data-model.ts (classes)')(format=".")
:marked
  Here, again, is the component's `FormGroup` definition.

+makeExample('reactive-forms/ts/src/app/hero-detail-6.component.ts', 'hero-form-model','src/app/hero-detail.component.ts (excerpt)')(format=".")
:marked
  There are two significant differences between these models:

  1. The `Hero` has an `id`. The form model does not because you generally don't show primary keys to users.

  1. The `Hero` has an array of addresses. This form model presents only one address,
  a choice [revisited below](#form-array "Form arrays").

  Nonetheless, the two models are pretty close in shape and you'll see in a moment how this alignment facilitates copying the _data model_ properties
  to the _form model_ with the `patchValue` and `setValue` methods.

:marked
  Take a moment to refactor the _address_ `FormGroup` definition for brevity and clarity as follows:
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'address-form-group')(format=".")

:marked
  Also be sure to update the import from `data-model` so you can reference the `Hero` and `Address` classes:
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'import-address')(format=".")

.l-main-section
a#set-data
:marked
  ## Populate the form model with _setValue_ and _patchValue_
  Previously you created a control and initialized its value at the same time. 
  You can also initialize or reset the values _later_ with the 
  `setValue` and `patchValue` methods.

  ### _setValue_
  With **`setValue`**, you assign _every_ form control value _at once_
  by passing in a data object whose properties exactly match the _form model_ behind the `FormGroup`.

+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'set-value','src/app/hero-detail.component.ts (excerpt)')(format=".")
:marked
  The `setValue` method checks the data object thoroughly before assigning any form control values.

  It will not accept a data object that doesn't match the FormGroup structure or is 
  missing values for any control in the group. This way, it can return helpful 
  error messages if you have a typo or if you've nested controls incorrectly. 
  `patchValue` will fail silently.

  On the other hand,`setValue` will catch 
  the error and report it clearly. 

  Notice that you can _almost_ use the entire `hero` as the argument to `setValue`
  because its shape is similar to the component's `FormGroup` structure.

  You can only show the hero's first address and you must account for the possibility that the `hero` has no addresses at all.
  This explains the conditional setting of the `address` property in the data object argument:
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'set-value-address')(format=".")

:marked
  ### _patchValue_
  With **`patchValue`**, you can assign values to specific controls in a `FormGroup`
  by supplying an object of key/value pairs for just the controls of interest. 

  This example sets only the form's `name` control.
+makeExample('reactive-forms/ts/src/app/hero-detail-6.component.ts', 'patch-value','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  With **`patchValue`** you have more flexibility to cope with wildly divergent data and form models.
  But unlike `setValue`,  `patchValue` cannot check for missing control 
  values and does not throw helpful errors.

  ### When to set form model values (_ngOnChanges_)

  Now you know _how_ to set the _form model_ values. But _when_ do you set them?
  The answer depends upon when the component gets the _data model_ values.

  The `HeroDetailComponent` in this reactive forms sample is nested within a _master/detail_ `HeroListComponent` ([discussed below](#hero-list)).
  The `HeroListComponent` displays hero names to the user.
  When the user clicks on a hero, the list component passes the selected hero into the `HeroDetailComponent`
  by binding to its `hero` input property.

+makeExample('reactive-forms/ts/src/app/hero-list.component.1.html', '','hero-list.component.html (simplified)')(format=".")

:marked
  In this approach, the value of `hero` in the `HeroDetailComponent` changes 
  every time the user selects a new hero.
  You should call  _setValue_ in the [ngOnChanges](lifecycle-hooks.html#onchanges)
  hook, which Angular calls whenever the input `hero` property changes
  as the following steps demonstrate.

  First, import the `OnChanges` and `Input` symbols in `hero-detail.component.ts`.

+makeExample('reactive-forms/ts/src/app/hero-detail-6.component.ts', 'import-input','src/app/hero-detail.component.ts (core imports)')(format=".")

:marked
  Add the `hero` input property.
+makeExample('reactive-forms/ts/src/app/hero-detail-6.component.ts', 'hero')(format=".")

:marked
  Add the `ngOnChanges` method to the class as follows:

+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'ngOnChanges-1','src/app/hero-detail.component.ts (ngOnchanges)')(format=".")

:marked
  ### _reset_ the form flags

  You should  reset the form when the hero changes so that 
  control values from the previous hero are cleared and 
  status flags are restored to the _pristine_ state.
  You could call `reset` at the top of `ngOnChanges` like this.
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'reset')(format=".")

:marked
  The `reset` method has an optional `state` value so you can reset the flags _and_ the control values at the same. 
  Internally, `reset` passes the argument to `setValue`. 
  A little refactoring and `ngOnChanges` becomes this:
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'ngOnChanges', 'src/app/hero-detail.component.ts (ngOnchanges - revised)')(format=".")

a#hero-list
:marked
  ### Create the _HeroListComponent_ and _HeroService_

  The `HeroDetailComponent` is a nested sub-component of the `HeroListComponent` in a _master/detail_ view.
  Together they look a bit like this:

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/hero-list.png" width="420px" alt="HeroListComponent")
:marked
  The `HeroListComponent` uses an injected `HeroService` to retrieve heroes from the server
  and then presents those heroes to the user as a series of buttons.
  The `HeroService` emulates an HTTP service. 
  It returns an `Observable` of heroes that resolves after a short delay, 
  both to simulate network latency and to indicate visually 
  the necessarily asynchronous nature of the application.

  When the user clicks on a hero,
  the component sets its `selectedHero` property which
  is bound to the `hero` input property of the `HeroDetailComponent`.
  The `HeroDetailComponent` detects the changed hero and re-sets its form
  with that hero's data values.

  A "Refresh" button clears the hero list and the current selected hero before refetching the heroes.

  The remaining `HeroListComponent` and `HeroService` implementation details are not relevant to understanding reactive forms.
  The techniques involved are covered elsewhere in the documentation, including the _Tour of Heroes_
  [here](../tutorial/toh-pt3.html "ToH: Multiple Components") and [here](../tutorial/toh-pt4.html "ToH: Services").

  If you're coding along with the steps in this reactive forms tutorial, 
  create the pertinent files based on the 
  [source code displayed below](#source-code "Reactive Forms source code"). 
  Notice that `hero-list.component.ts` imports `Observable` and `finally` while `hero.service.ts` imports `Observable`, `of`,
  and `delay` from `rxjs`. 
  Then return here to learn about _form array_ properties.

.l-main-section
a#form-array
:marked
  ## Use _FormArray_ to present an array of _FormGroups_
  So far, you've seen `FormControls` and `FormGroups`.
  A `FormGroup` is a named object whose property values are `FormControls` and other `FormGroups`.

  Sometimes you need to present an arbitrary number of controls or groups.
  For example, a hero may have zero, one, or any number of addresses.
  
  The `Hero.addresses` property is an array of `Address` instances.
  An _address_ `FormGroup` can display one `Address`.
  An Angular `FormArray` can display an array of _address_ `FormGroups`.

  To get access to the `FormArray` class, import it into `hero-detail.component.ts`:
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'imports','src/app/hero-detail.component.ts (excerpt)')(format=".")

:marked
  To _work_ with a `FormArray` you do the following:
  1. Define the items (`FormControls` or `FormGroups`) in the array.
  1. Initialize the array with items created from data in the _data model_.
  1. Add and remove items as the user requires.

  In this guide, you define a `FormArray` for `Hero.addresses` and
  let the user add or modify addresses (removing addresses is your homework).

  You’ll need to redefine the form model in the `HeroDetailComponent` constructor,
  which currently only displays the first hero address in an _address_ `FormGroup`. 
+makeExample('reactive-forms/ts/src/app/hero-detail-7.component.ts', 'address-form-group')(format=".")

:marked
  ### From _address_ to _secret lairs_

  From the user's point of view, heroes don't have _addresses_.
  _Addresses_ are for mere mortals. Heroes have _secret lairs_!
  Replace the _address_ `FormGroup` definition with a _secretLairs_ `FormArray` definition:
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'secretLairs-form-array')(format=".")

.alert.is-helpful
  :marked
    Changing the form control name from `address` to `secretLairs` drives home an important point:
    the _form model_ doesn't have to match the _data model_.
    
    Obviously there has to be a relationship between the two. 
    But it can be anything that makes sense within the application domain.

    _Presentation_ requirements often differ from _data_ requirements.
    The reactive forms approach both emphasizes and facilitates this distinction.

:marked
  ### Initialize the "secretLairs" _FormArray_

  The default form displays a nameless hero with no addresses.
  
  You need a method to populate (or repopulate) the _secretLairs_ with actual hero addresses whenever
  the parent `HeroListComponent` sets the `HeroListComponent.hero` input property to a new `Hero`.

  The following `setAddresses` method replaces the _secretLairs_ `FormArray` with a new `FormArray`,
  initialized by an array of hero address `FormGroups`.
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'set-addresses')(format=".")

:marked
  Notice that you replace the previous `FormArray` with the **`FormGroup.setControl` method**, not with `setValue`.
  You're replacing a _control_, not the _value_ of a control.

  Notice also that the _secretLairs_ `FormArray` contains **`FormGroups`**, not `Addresses`.

  ### Get the _FormArray_
  The `HeroDetailComponent` should be able to display, add, and remove items from the _secretLairs_ `FormArray`.

  Use the `FormGroup.get` method to acquire a reference to that `FormArray`.
  Wrap the expression in a `secretLairs` convenience property for clarity and re-use.
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'get-secret-lairs','src/app/hero-detail.component.ts (secretLayers property)')(format=".")

:marked
  ### Display the _FormArray_ 

  The current HTML template displays a single _address_ `FormGroup`.
  Revise it to display zero, one, or more of the hero's _address_ `FormGroups`.
  
  This is mostly a matter of wrapping the previous template HTML for an address in a `<div>` and 
  repeating that `<div>` with `*ngFor`.
  
  The trick lies in knowing how to write the `*ngFor`. There are three key points:

  1. Add another wrapping `<div>`, around the `<div>` with `*ngFor`, and 
  set its `formArrayName` directive to `"secretLairs"`.
  This step establishes the _secretLairs_ `FormArray` as the context for form controls in the inner, repeated HTML template. 

  1. The source of the repeated items is the `FormArray.controls`, not the `FormArray` itself. 
  Each control is an _address_ `FormGroup`, exactly what the previous (now repeated) template HTML expected.

  1. Each repeated `FormGroup` needs a unique `formGroupName` which must be the index of the `FormGroup` in the `FormArray`.
  You'll re-use that index to compose a unique label for each address.

  Here's the skeleton for the _secret lairs_ section of the HTML template:
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.html', 'form-array-skeleton','src/app/hero-detail.component.html (*ngFor)')(format=".")

:marked
  Here's the complete template for the _secret lairs_ section:
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.html', 'form-array','src/app/hero-detail.component.html (excerpt)')

:marked
  ### Add a new lair to the _FormArray_

  Add an `addLair` method that gets the _secretLairs_ `FormArray` and appends a new _address_ `FormGroup` to it. 
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'add-lair','src/app/hero-detail.component.ts (addLair method)')(format=".")

:marked
  Place a button on the form so the user can add a new _secret lair_ and wire it to the component's `addLair` method.

+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.html', 'add-lair','src/app/hero-detail.component.html (addLair button)')(format=".")

.alert.is-important
  :marked
    Be sure to **add the `type="button"` attribute**. 
    In fact, you should always specify a button's `type`.
    Without an explict type, the button type defaults to "submit".
    When you later add a _form submit_ action, every "submit" button triggers the submit action which
    might do something like save the current changes.
    You do not want to save changes when the user clicks the _Add a Secret Lair_ button.

:marked
  ### Try it!

  Back in the browser, select the hero named "Magneta".
  "Magneta" doesn't have an address, as you can see in the diagnostic JSON at the bottom of the form.

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/addresses-array.png" width="400px" alt="JSON output of addresses array")

:marked
  Click the "_Add a Secret Lair_" button. 
  A new address section appears. Well done!

  ### Remove a lair

  This example can _add_ addresses but it can't _remove_ them.
  For extra credit, write a `removeLair` method and wire it to a button on the repeating address HTML.

.l-main-section
a#observe-control
:marked
  ## Observe control changes

  Angular calls `ngOnChanges` when the user picks a hero in the parent `HeroListComponent`.
  Picking a hero changes the `HeroDetailComponent.hero` input property.
  
  Angular does _not_ call `ngOnChanges` when the user modifies the hero's _name_ or _secret lairs_.
  Fortunately, you can learn about such changes by subscribing to one of the form control properties 
  that raises a change event.
  
  These are properties, such as `valueChanges`, that return an RxJS `Observable`.
  You don't need to know much about RxJS `Observable` to monitor form control values.

  Add the following method to log changes to the value of the _name_ `FormControl`.
+makeExample('reactive-forms/ts/src/app/hero-detail.component.ts', 'log-name-change','src/app/hero-detail.component.ts (logNameChange)')(format=".")

:marked
  Call it in the constructor, after creating the form.
+makeExample('reactive-forms/ts/src/app/hero-detail-8.component.ts', 'ctor')(format=".")

:marked
  The `logNameChange` method pushes name-change values into a `nameChangeLog` array.
  Display that array at the bottom of the component template with this `*ngFor` binding:
+makeExample('reactive-forms/ts/src/app/hero-detail.component.html', 'name-change-log','src/app/hero-detail.component.html (Name change log)')(format=".")

:marked
  Return to the browser, select a hero (e.g, "Magneta"), and start typing in the _name_ input box.
  You should see a new name in the log after each keystroke.

  ### When to use it
  
  An interpolation binding is the easier way to _display_ a name change.
  Subscribing to an observable form control property is handy for triggering 
  application logic _within_ the component class.

.l-main-section
a#save
:marked
  ## Save form data

  The `HeroDetailComponent` captures user input but it doesn't do anything with it.
  In a real app, you'd probably save those hero changes.
  In a real app, you'd also be able to revert unsaved changes and resume editing.
  After you implement both features in this section, the form will look like this:

figure.image-display
  img(src="/resources/images/devguide/reactive-forms/save-revert-buttons.png" width="389px" alt="Form with save & revert buttons")

:marked
  ### Save
  In this sample application, when the user submits the form,
  the `HeroDetailComponent` will pass an instance of the hero _data model_
  to a save method on the injected `HeroService`.
+makeExample('reactive-forms/ts/src/app/hero-detail.component.ts', 'on-submit','src/app/hero-detail.component.ts (onSubmit)')(format=".")
:marked
  This original `hero` had the pre-save values. The user's changes are still in the _form model_.
  So you create a new `hero` from a combination of original hero values (the `hero.id`)
  and deep copies of the changed form model values, using the `prepareSaveHero` helper. 

+makeExample('reactive-forms/ts/src/app/hero-detail.component.ts', 'prepare-save-hero','src/app/hero-detail.component.ts (prepareSaveHero)')(format=".")

.l-sub-section
  :marked
    **Address deep copy**

    Had you assigned the `formModel.secretLairs` to `saveHero.addresses` (see line commented out),
    the addresses in `saveHero.addresses` array would be the same objects 
    as the lairs in the `formModel.secretLairs`.
    A user's subsequent changes to a lair street would mutate an address street in the `saveHero`.
    
    The `prepareSaveHero` method makes copies of the form model's `secretLairs` objects so that can't happen.

:marked
  ### Revert (cancel changes)
  The user cancels changes and reverts the form to the original state by pressing the _Revert_ button.

  Reverting is easy. Simply re-execute the `ngOnChanges` method that built the _form model_ from the original, unchanged `hero` _data model_.
+makeExample('reactive-forms/ts/src/app/hero-detail.component.ts', 'revert','src/app/hero-detail.component.ts (revert)')(format=".")

:marked
  ### Buttons
  Add the "Save" and "Revert" buttons near the top of the component's template:
+makeExample('reactive-forms/ts/src/app/hero-detail.component.html', 'buttons','src/app/hero-detail.component.html (Save and Revert buttons)')(format=".")
:marked
  The buttons are disabled until the user "dirties" the form by changing a value in any of its form controls (`heroForm.dirty`).

  Clicking a button of type `"submit"` triggers the `ngSubmit` event which calls the component's `onSubmit` method.
  Clicking the revert button triggers a call to the component's `revert` method.
  Users now can save or revert changes.
  
  This is the final step in the demo.
  Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker"></live-example>.


.l-main-section
:marked
  ## Conclusion

  This page covered:

  * How to create a reactive form component and its corresponding template.
  * How to use `FormBuilder` to simplify coding a reactive form.
  * Grouping `FormControls`.
  * Inspecting `FormControl` properties.
  * Setting data with `patchValue` and `setValue`.
  * Adding groups dynamically with `FormArray`.
  * Observing changes to the value of a `FormControl`.
  * Saving form changes.

a#source-code
:marked
  The key files of the final version are as follows:

+makeTabs(
  `reactive-forms/ts/src/app/app.component.ts,
   reactive-forms/ts/src/app/app.module.ts,
   reactive-forms/ts/src/app/hero-detail.component.ts,
   reactive-forms/ts/src/app/hero-detail.component.html,
   reactive-forms/ts/src/app/hero-list.component.html, 
   reactive-forms/ts/src/app/hero-list.component.ts,   
   reactive-forms/ts/src/app/data-model.ts,
   reactive-forms/ts/src/app/hero.service.ts
   `,
  '',
  `src/app/app.component.ts,
   src/app/app.module.ts,
   src/app/hero-detail.component.ts,
   src/app/hero-detail.component.html,  
   src/app/hero-list.component.html, 
   src/app/hero-list.component.ts,   
   src/app/data-model.ts,
   src/app/hero.service.ts,
   `)

:marked
  You can download the complete source for all steps in this guide
  from the <live-example title="Reactive Forms Demo in Plunker">Reactive Forms Demo</live-example> live example.