Brandon Roberts
Jason Aden
parent
6482f6f0fe
commit
de03abbd34
|
|
@ -1,6 +1,6 @@
|
|||
# Reactive forms
|
||||
# Reactive Forms
|
||||
|
||||
_Reactive forms_ provide a model-driven approach to handling form inputs whose values change over time. This guide shows you how to create and update a simple form control, progress to using multiple controls in a group, validate form values, and implement more advanced forms.
|
||||
*Reactive forms* provide a model-driven approach to handling form inputs whose values change over time. This guide shows you how to create and update a simple form control, progress to using multiple controls in a group, validate form values, and implement more advanced forms.
|
||||
|
||||
|
||||
|
||||
|
|
@ -12,17 +12,17 @@ Try the <live-example title="Reactive Forms in Stackblitz">Reactive Forms live-e
|
|||
|
||||
## Introduction to reactive forms
|
||||
|
||||
Reactive forms use an explicit and immutable approach to managing the state of a form at a given point in time. Each change to the form state returns a new state, which maintains the integrity of the model between changes. Reactive forms are built around observable streams, where form inputs and values are provided as streams of input values, also while giving you synchronous access to the data. This approach allows your templates to take advantage of these streams of form state changes, rather than to be dependent to them.
|
||||
Reactive forms use an explicit and immutable approach to managing the state of a form at a given point in time. Each change to the form state returns a new state, which maintains the integrity of the model between changes. Reactive forms are built around observable streams, where form inputs and values are provided as streams of input values, which can be accessed synchronously.
|
||||
|
||||
Reactive forms also allow for easier testing because you have an assurance that your data is consistent and predictable when requested. Consumers outside your templates have access to the same streams, where they can manipulate that data safely.
|
||||
Reactive forms also provide a straightforward path to testing because you are assured that your data is consistent and predictable when requested. Any consumers of the streams have access to manipulate that data safely.
|
||||
|
||||
Reactive forms differ from template-driven forms in distinct ways. Reactive forms provide more predictability with synchronous access to the data model, immutability with observable operators, and change tracking through observable streams. If you prefer direct access to modify data in your template, template-driven forms are less explicit because they rely on directives embedded in the template, along with mutable data to track changes asynchronously. See the [Appendix](#appendix) for detailed comparisons between the two paradigms.
|
||||
|
||||
## Getting started
|
||||
|
||||
This section describes the key steps to add a single form control. The example allows a user to enter their name into an input field, captures that input value, and displays the current value of the form control element.
|
||||
This section describes how to add a single form control. In the example, the user enters their name into an input field, captures that input value, and displays the current value of the form control element.
|
||||
|
||||
### Step 1 - Register the `ReactiveFormsModule`
|
||||
### Step 1: Registering the reactive forms module
|
||||
|
||||
To use reactive forms, import `ReactiveFormsModule` from the `@angular/forms` package and add it to your NgModule's `imports` array.
|
||||
|
||||
|
|
@ -30,7 +30,7 @@ To use reactive forms, import `ReactiveFormsModule` from the `@angular/forms` pa
|
|||
|
||||
</code-example>
|
||||
|
||||
### Step 2 - Import and create a new form control
|
||||
### Step 2: Generating and importing a new form control
|
||||
|
||||
Generate a component for the control.
|
||||
|
||||
|
|
@ -40,17 +40,17 @@ Generate a component for the control.
|
|||
|
||||
</code-example>
|
||||
|
||||
The `FormControl` is the most basic building block when using reactive forms. To register a single form control, import the `FormControl` class into your component and create a new instance of `FormControl` to save as a class property.
|
||||
The `FormControl` class is the basic building block when using reactive forms. To register a single form control, import the `FormControl` class into your component and create a new instance of the form control to save as a class property.
|
||||
|
||||
<code-example path="reactive-forms/src/app/name-editor/name-editor.component.ts" region="create-control" title="src/app/name-editor/name-editor.component.ts">
|
||||
|
||||
</code-example>
|
||||
|
||||
The constructor of the `FormControl` can be used to set its initial value, which in this case is set to an empty string. By creating these controls in your component class, you get immediate access to listen, update, and validate the state of the form input.
|
||||
Use the constructor of `FormControl` to set its initial value, which in this case is an empty string. By creating these controls in your component class, you get immediate access to listen for, update, and validate the state of the form input.
|
||||
|
||||
### Step 3 - Register the control in the template
|
||||
### Step 3: Registering the control in the template
|
||||
|
||||
After you create the control in the component class, you must associate it with a form control element in the template. Update the template with the form control using the `formControl` binding provided by the `FormControlDirective` included in the `ReactiveFormsModule`.
|
||||
After you create the control in the component class, you must associate it with a form control element in the template. Update the template with the form control using the `formControl` binding provided by `FormControlDirective` included in `ReactiveFormsModule`.
|
||||
|
||||
<code-example path="reactive-forms/src/app/name-editor/name-editor.component.html" region="control-binding" linenums="false" title="src/app/name-editor/name-editor.component.html">
|
||||
|
||||
|
|
@ -58,15 +58,15 @@ After you create the control in the component class, you must associate it with
|
|||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: For a more detailed list of classes and directives provided by the `ReactiveFormsModule`, see the [Reactive Forms API](#reactive-forms-api) section.
|
||||
**Note:** For a more detailed list of classes and directives provided by `ReactiveFormsModule`, see the [Reactive forms API](#reactive-forms-api) section.
|
||||
|
||||
</div>
|
||||
|
||||
Using the template binding syntax, the form control is now registered to the `name` input element in the template. The form control and DOM element communicate with each other: the view reflects changes in the model, and the model reflects changes in the view.
|
||||
|
||||
#### Display the component
|
||||
#### Displaying the component
|
||||
|
||||
The `FormControl` assigned to `name` is displayed once the component is added to a template.
|
||||
The form control assigned to `name` is displayed when the component is added to a template.
|
||||
|
||||
<code-example path="reactive-forms/src/app/app.component.1.html" region="app-name-editor" linenums="false" title="src/app/app.component.html (name editor)">
|
||||
|
||||
|
|
@ -79,15 +79,18 @@ The `FormControl` assigned to `name` is displayed once the component is added to
|
|||
## Managing control values
|
||||
|
||||
Reactive forms give you access to the form control state and value at a point in time. You can manipulate
|
||||
the current state and value through the component class or the component template. The following examples display the value of a `FormControl` and change it.
|
||||
the current state and value through the component class or the component template. The following examples display the value of the form control instance and change it.
|
||||
|
||||
{@a display-value}
|
||||
|
||||
### Display the control’s value
|
||||
### Displaying a form control value
|
||||
|
||||
Every `FormControl` provides its current value as an observable through the `valueChanges` property. You can listen to changes in the form’s value in the template using the `AsyncPipe` or in the component class using the `subscribe()` method. The `value` property also gives you a snapshot of the current value.
|
||||
You can display the value in these ways:
|
||||
|
||||
Display the current value using interpolation in the template as shown in the following example.
|
||||
* Through the `valueChanges` observable where you can listen for changes in the form's value in the template using `AsyncPipe` or in the component class using the `subscribe()` method.
|
||||
* With the `value` property. which gives you a snapshot of the current value.
|
||||
|
||||
The following example shows you how to display the current value using interpolation in the template.
|
||||
|
||||
<code-example path="reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value" linenums="false" title="src/app/name-editor/name-editor.component.html (control value)">
|
||||
|
||||
|
|
@ -95,27 +98,27 @@ Display the current value using interpolation in the template as shown in the fo
|
|||
|
||||
The displayed value changes as you update the form control element.
|
||||
|
||||
Reactive forms also provide access to more information about a given control through properties and methods provided with each instance. These properties and methods of the underlying [AbstractControl](api/forms/AbstractControl) are used to control form state and determine when to display messages when handling validation. For more information, see [Simple Form Validation](#simple-form-validation) later in this guide.
|
||||
Reactive forms provide access to information about a given control through properties and methods provided with each instance. These properties and methods of the underlying [AbstractControl](api/forms/AbstractControl) class are used to control form state and determine when to display messages when handling validation. For more information, see [Simple form validation](#simple-form-validation) later in this guide.
|
||||
|
||||
Read about other `FormControl` properties and methods in the [Reactive Forms API](#reactive-forms-api) section.
|
||||
Read about other `FormControl` properties and methods in the [Reactive forms API](#reactive-forms-api) section.
|
||||
|
||||
### Replace the form control value
|
||||
### Replacing a form control value
|
||||
|
||||
Reactive forms have methods to change a control's value programmatically, which gives you the flexibility to update the control’s value without user interaction. The `FormControl` provides a `setValue()` method which updates the value of the form control and validates the structure of the value provided against the control’s structure. For example, when retrieving form data from a backend API or service, use the `setValue()` method to update the control to its new value, replacing the old value entirely.
|
||||
Reactive forms have methods to change a control's value programmatically, which gives you the flexibility to update the value without user interaction. A form control instance provides a `setValue()` method that updates the value of the form control and validates the structure of the value provided against the control's structure. For example, when retrieving form data from a backend API or service, use the `setValue()` method to update the control to its new value, replacing the old value entirely.
|
||||
|
||||
The following example adds a method to the component class to update the value of the control to _Nancy_ using the `setValue()` method.
|
||||
The following example adds a method to the component class to update the value of the control to *Nancy* using the `setValue()` method.
|
||||
|
||||
<code-example path="reactive-forms/src/app/name-editor/name-editor.component.ts" region="update-value" title="src/app/name-editor/name-editor.component.ts (update value)">
|
||||
|
||||
</code-example>
|
||||
|
||||
Update the template with a button to simulate a name update. Any value entered in the form control element before clicking the `Update Name` button will be reflected as its current value.
|
||||
Update the template with a button to simulate a name update. When you click the **Update Name** button, the value entered in the form control element is reflected as its current value.
|
||||
|
||||
<code-example path="reactive-forms/src/app/name-editor/name-editor.component.html" region="update-value" linenums="false" title="src/app/name-editor/name-editor.component.html (update value)">
|
||||
|
||||
</code-example>
|
||||
|
||||
Because the form model is the source of truth for the control, when you click the button the value of the input is also changed within the component class, overriding its current value.
|
||||
The form model is the source of truth for the control, so when you click the button, the value of the input is changed within the component class, overriding its current value.
|
||||
|
||||
<figure>
|
||||
<img src="generated/images/guide/reactive-forms/name-editor-2.png" alt="Name Editor Update">
|
||||
|
|
@ -123,13 +126,13 @@ Because the form model is the source of truth for the control, when you click th
|
|||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: In this example, you are only using a single control, but when using the `setValue()` method with a `FormGroup` or `FormArray` the value needs to match the structure of the group or array.
|
||||
**Note:** In this example, you're using a single control. When using the `setValue()` method with a form group or form array instance, the value needs to match the structure of the group or array.
|
||||
|
||||
</div>
|
||||
|
||||
## Grouping form controls
|
||||
|
||||
Just as a `FormControl` instance gives you control over a single input field, a `FormGroup` tracks the form state of a group of `FormControl` instances (for example, a form). Each control in `FormGroup` is tracked by name when creating the `FormGroup`. The following example shows how to manage multiple `FormControl` instances in a single group.
|
||||
Just as a form control instance gives you control over a single input field, a form group instance tracks the form state of a group of form control instances (for example, a form). Each control in a form group instance is tracked by name when creating the form group. The following example shows how to manage multiple form control instances in a single group.
|
||||
|
||||
Generate a `ProfileEditor` component and import the `FormGroup` and `FormControl` classes from the `@angular/forms` package.
|
||||
|
||||
|
|
@ -143,31 +146,31 @@ Generate a `ProfileEditor` component and import the `FormGroup` and `FormControl
|
|||
|
||||
</code-example>
|
||||
|
||||
### Step 1 - Create a `FormGroup`
|
||||
### Step 1: Creating a FormGroup instance
|
||||
|
||||
Create a property in the component class named `profileForm` and set the property to a new instance of a `FormGroup`. To initialize the `FormGroup`, provide the constructor with an object of controls with their respective names.
|
||||
Create a property in the component class named `profileForm` and set the property to a new form group instance. To initialize the form group, provide the constructor with an object of named keys mapped to their control.
|
||||
|
||||
For the profile form, add two `FormControl` instances with the names `firstName` and `lastName`.
|
||||
For the profile form, add two form control instances with the names `firstName` and `lastName`.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="formgroup" title="src/app/profile-editor/profile-editor.component.ts (form group)">
|
||||
|
||||
</code-example>
|
||||
|
||||
The individual form controls are now collected within a group. The `FormGroup` provides its model value as an object reduced from the values of each control in the group. A `FormGroup` instance has the same properties (such as `value`, `untouched`) and methods (such as `setValue()`) as a `FormControl` instance.
|
||||
The individual form controls are now collected within a group. A `FormGroup` instance provides its model value as an object reduced from the values of each control in the group. A form control instance has the same properties (such as `value` and `untouched`) and methods (such as `setValue()`) as a form control instance.
|
||||
|
||||
### Step 2 - Associate the `FormGroup` model and view
|
||||
### Step 2: Associating the FormGroup model and view
|
||||
|
||||
The `FormGroup` also tracks the status and changes of each of its controls, so if one of the control’s status or value changes, the parent control also emits a new status or value change. The model for the group is maintained from its members. After you define the model, you must update the template to reflect the model in the view.
|
||||
A form group tracks the status and changes for each of its controls, so if one of the controls changes, the parent control also emits a new status or value change. The model for the group is maintained from its members. After you define the model, you must update the template to reflect the model in the view.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroup" linenums="false" title="src/app/profile-editor/profile-editor.component.html (template form group)">
|
||||
|
||||
</code-example>
|
||||
|
||||
Note that just as the `FormGroup` contains a group of controls, the _profileForm_ `FormGroup` is bound to the `form` element with the `FormGroup` directive, creating a communication layer between the model and the form containing the inputs. The `formControlName` input provided by the `FormControlName` directive binds each individual input to the form control defined in the `FormGroup`. The form controls communicate with their respective elements. The also communicate changes to the `FormGroup`, which provides the source of truth for the model value.
|
||||
Note that just as a form group contains a group of controls, the *profile form* `FormGroup` is bound to the `form` element with the `FormGroup` directive, creating a communication layer between the model and the form containing the inputs. The `formControlName` input provided by the `FormControlName` directive binds each individual input to the form control defined in `FormGroup`. The form controls communicate with their respective elements. They also communicate changes to the form group instance, which provides the source of truth for the model value.
|
||||
|
||||
### Save form data
|
||||
### Saving form data
|
||||
|
||||
The `ProfileEditor` component takes input from the user, but in a real scenario you want to capture the form value for further processing outside the component. The `FormGroup` directive listens for the `submit` event emitted by the `form` element and emits an `ngSubmit` event that you can bind to a callback function.
|
||||
The `ProfileEditor` component accepts input from the user, but in a real scenario you want to capture the form value and make available for further processing outside the component. The `FormGroup` directive listens for the `submit` event emitted by the `form` element and emits an `ngSubmit` event that you can bind to a callback function.
|
||||
|
||||
Add an `ngSubmit` event listener to the `form` tag with the `onSubmit()` callback method.
|
||||
|
||||
|
|
@ -175,15 +178,15 @@ Add an `ngSubmit` event listener to the `form` tag with the `onSubmit()` callbac
|
|||
|
||||
</code-example>
|
||||
|
||||
The `onSubmit()` method in the `ProfileEditor` component captures the current value of the `profileForm`. To keep the form encapsulated, to provide the form value outside the component, use an `EventEmitter`. The following example uses `console.warn` to log to the browser console.
|
||||
The `onSubmit()` method in the `ProfileEditor` component captures the current value of `profileForm`. Use `EventEmitter` to keep the form encapsulated and to provide the form value outside the component. The following example uses `console.warn` to log a message to the browser console.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="on-submit" title="src/app/profile-editor/profile-editor.component.ts (submit method)">
|
||||
|
||||
</code-example>
|
||||
|
||||
The `submit` event is emitted by the `form` tag using the native DOM event. You trigger the event by clicking a button with `submit` type. This allows the user to use the enter key to trigger submission after filling out the form.
|
||||
The `submit` event is emitted by the `form` tag using the native DOM event. You trigger the event by clicking a button with `submit` type. This allows the user to press the **Enter** key to submit the completed form.
|
||||
|
||||
Add a `button` to the bottom of the form to trigger the form submission.
|
||||
Use a `button` element to add a button to the bottom of the form to trigger the form submission.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.html" region="submit-button" linenums="false" title="src/app/profile-editor/profile-editor.component.html (submit button)">
|
||||
|
||||
|
|
@ -191,41 +194,41 @@ Add a `button` to the bottom of the form to trigger the form submission.
|
|||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note:* The button in the snippet above also has a `disabled` binding attached to it to disable the button when the `profileForm` is invalid. You aren't performing any validation yet, so the button is always enabled. Simple form validation is covered later in the [Form Validation](#simple-form-validation) section.
|
||||
**Note:** The button in the snippet above also has a `disabled` binding attached to it to disable the button when `profileForm` is invalid. You aren't performing any validation yet, so the button is always enabled. Simple form validation is covered in the [Simple form validation](#simple-form-validation) section.
|
||||
|
||||
</div>
|
||||
|
||||
#### Display the component
|
||||
#### Displaying the component
|
||||
|
||||
The `ProileEditor` component that contains the form is displayed when added to a component template.
|
||||
To display the `ProfileEditor` component that contains the form, add it to a component template.
|
||||
|
||||
<code-example path="reactive-forms/src/app/app.component.1.html" region="app-profile-editor" linenums="false" title="src/app/app.component.html (profile editor)">
|
||||
|
||||
</code-example>
|
||||
|
||||
The `ProfileEditor` allows you to manage the `FormControl` instances for the `firstName` and `lastName` controls within the `FormGroup`.
|
||||
`ProfileEditor` allows you to manage the form control instances for the `firstName` and `lastName` controls within the form group instance.
|
||||
|
||||
<figure>
|
||||
<img src="generated/images/guide/reactive-forms/profile-editor-1.png" alt="Profile Editor">
|
||||
</figure>
|
||||
|
||||
## Nesting form groups
|
||||
## Creating nested form groups
|
||||
|
||||
When building complex forms, managing the different areas of information is easier in smaller sections, and some groups of information naturally fall into the same group. Using a nested `FormGroup` allows you to break large forms groups into smaller, more manageable ones.
|
||||
When building complex forms, managing the different areas of information is easier in smaller sections, and some groups of information naturally fall into the same group. Using a nested form group instance allows you to break large forms groups into smaller, more manageable ones.
|
||||
|
||||
### Step 1 - Create a nested group
|
||||
### Step 1: Creating a nested group
|
||||
|
||||
An address is a good example of information that can be grouped together. A `FormGroup` can accept both `FormControl` and `FormGroup` instances as children. This makes composing complex form models easier to maintain and logically group together. To create a nested group in the `profileForm`, add a nested `address` `FormGroup`.
|
||||
An address is a good example of information that can be grouped together. Form groups can accept both form control and form group instances as children. This makes composing complex form models easier to maintain and logically group together. To create a nested group in `profileForm`, add a nested `address` element to the form group instance.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup" linenums="false" title="src/app/profile-editor/profile-editor.component.ts (nested form group)">
|
||||
|
||||
</code-example>
|
||||
|
||||
In this example, the `address group` combines the current `firstName` and `lastName` controls with the new `street`, `city`, `state` and `zip` controls. Even though the `address` `FormGroup` is a child of the overall `profileForm` `FormGroup`, the same rules still apply with value and status changes. Changes in status and value from the nested form group will propagate up to the parent form group, maintaining consistency with the overall model.
|
||||
In this example, `address group` combines the current `firstName` and `lastName` controls with the new `street`, `city`, `state`, and `zip` controls. Even though the `address` element in the form group is a child of the overall `profileForm` element in the form group, the same rules apply with value and status changes. Changes in status and value from the nested form group propagate to the parent form group, maintaining consistency with the overall model.
|
||||
|
||||
### Step 2 - Group the nested form in the template
|
||||
### Step 2: Grouping the nested form in the template
|
||||
|
||||
After you update the model in the component class, update the template to connect the `FormGroup` instance and its input elements.
|
||||
After you update the model in the component class, update the template to connect the form group instance and its input elements.
|
||||
|
||||
Add the `address` form group containing the `firstName` and `lastName` fields to the `ProfileEditor` template.
|
||||
|
||||
|
|
@ -241,19 +244,25 @@ The `ProfileEditor` form is displayed as one group, but the model is broken down
|
|||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: Display the value for the `FormGroup` in the component template using the `value` property and the `JsonPipe`.
|
||||
**Note:** Display the value for the form group instance in the component template using the `value` property and `JsonPipe`.
|
||||
|
||||
</div>
|
||||
|
||||
## Partial model updates
|
||||
|
||||
When updating the value for a `FormGroup` that contains multiple controls, you may only want to update parts of the model instead of replacing its entire value. This section covers how to update specific parts of an `AbstractControl` model.
|
||||
When updating the value for a form group instance that contains multiple controls, you may only want to update parts of the model. This section covers how to update specific parts of a form control data model.
|
||||
|
||||
### Patch the model value
|
||||
### Patching the model value
|
||||
|
||||
With a single control, you used the `setValue()` method to set the new value for an individual control. The `setValue()` method is more strict about adhering to the structure of the `FormGroup` and replaces the entire value for the control. The `patchValue()` method is more forgiving; it only replaces properties defined in the object that have changed in the form model, because you’re only providing partial updates. The strict checks in `setValue()` help catch errors in the nesting of complex forms, while `patchValue()` will fail silently in those cases.
|
||||
There are two ways to update the model value:
|
||||
|
||||
In the `ProfileEditorComponent`, the `updateProfile` method with the following example below to update the first name and street address for the user.
|
||||
* Use the `setValue()` method to set a new value for an individual control. The `setValue()` method strictly adheres to the structure of the form group and replaces the entire value for the control.
|
||||
|
||||
* Use the `patchValue()` method to replace any properties defined in the object that have changed in the form model.
|
||||
|
||||
The strict checks of the `setValue()` method help catch nesting errors in complex forms, while `patchValue()` fails silently on those errors.
|
||||
|
||||
In `ProfileEditorComponent`, use the `updateProfile` method with the example below to update the first name and street address for the user.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="patch-value" title="src/app/profile-editor/profile-editor.component.ts (patch value)">
|
||||
|
||||
|
|
@ -265,47 +274,49 @@ Simulate an update by adding a button to the template to update the user profile
|
|||
|
||||
</code-example>
|
||||
|
||||
When the button is clicked, the `profileForm` model is updated with just the `firstName` and `street` being modified. Notice that the `street` is provided in an object inside the `address` property. This is necessary because the `patchValue()` method applies the update against the model structure. `PatchValue()` only updates properties that the form model defines.
|
||||
When a user clicks the button, the `profileForm` model is updated with new values for `firstName` and `street`. Notice that `street` is provided in an object inside the `address` property. This is necessary because the `patchValue()` method applies the update against the model structure. `PatchValue()` only updates properties that the form model defines.
|
||||
|
||||
## Generating form controls with `FormBuilder`
|
||||
## Generating form controls with FormBuilder
|
||||
|
||||
Creating multiple form control instances manually can become very repetitive when dealing with multiple forms. The `FormBuilder` service provides convenience methods to handle generating controls. Underneath, the `FormBuilder` is creating and returning the instances in the same manner, but with much less work. The following section refactors the `ProfileEditor` component to use the `FormBuilder` instead of creating each `FormControl` and `FormGroup` by hand.
|
||||
Creating form control instances manually can become repetitive when dealing with multiple forms. The `FormBuilder` service provides convenient methods for generating controls.
|
||||
|
||||
### Step 1 - Import the `FormBuilder` class
|
||||
The following section refactors the `ProfileEditor` component to use the form builder service to create form control and form group instances.
|
||||
|
||||
To use the `FormBuilder` service, import its class from the `@angular/forms` package.
|
||||
### Step 1: Importing the FormBuilder class
|
||||
|
||||
Import the `FormBuilder` class from the `@angular/forms` package.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder-imports" title="src/app/profile-editor/profile-editor.component.ts (import)">
|
||||
|
||||
</code-example>
|
||||
|
||||
### Step 2 - Inject the `FormBuilder` service
|
||||
### Step 2: Injecting the FormBuilder service
|
||||
|
||||
The FormBuilder is an injectable service that is provided with the `ReactiveFormsModule`. Inject this dependency by adding it to the component constructor.
|
||||
The `FormBuilder` service is an injectable provider that is provided with the reactive forms module. Inject this dependency by adding it to the component constructor.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder" title="src/app/profile-editor/profile-editor.component.ts (constructor)">
|
||||
|
||||
</code-example>
|
||||
|
||||
### Step 3 - Generate form controls
|
||||
### Step 3: Generating form controls
|
||||
|
||||
The `FormBuilder` service has three methods: `control()`, `group()`, and `array()`. These methods are factory methods for generating form controls in your component class including a `FormControl`, `FormGroup`, and `FormArray` respectively.
|
||||
The `FormBuilder` service has three methods: `control()`, `group()`, and `array()`. These are factory methods for generating instances in your component classes including form controls, form groups, and form arrays.
|
||||
|
||||
Replace the creation of the `profileForm` by using the `group` method to create the controls.
|
||||
Use the `group` method to create the `profileForm` controls.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder" title="src/app/profile-editor/profile-editor.component.ts (form builder)">
|
||||
|
||||
</code-example>
|
||||
|
||||
In the example above, you use the `group()` method with the same names to define the properties in the model. Here, the value for each control name is an array containing the initial value as the first item.
|
||||
In the example above, you use the `group()` method with the same object to define the properties in the model. The value for each control name is an array containing the initial value as the first item in the array.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: You can define the control with just the initial value, but if your controls need sync or async validation, add sync and async validators as the second and third items in the array.
|
||||
**Note:** You can define the control with just the initial value, but if your controls need sync or async validation, add sync and async validators as the second and third items in the array.
|
||||
|
||||
</div>
|
||||
|
||||
Compare the two paths to achieve the same result.
|
||||
Compare using the form builder to creating the instances manually.
|
||||
|
||||
<code-tabs>
|
||||
|
||||
|
|
@ -321,11 +332,11 @@ Compare the two paths to achieve the same result.
|
|||
|
||||
## Simple form validation
|
||||
|
||||
Form validation is necessary when receiving user input through forms. This section covers adding a single validator to a form control and displaying the overall form status. Form validation is covered more extensively in the [Form Validation](guide/form-validation) guide.
|
||||
_Form validation_ is used to validate user input to ensure it's complete and correct. This section covers adding a single validator to a form control and displaying the overall form status. Form validation is covered more extensively in the [Form Validation](guide/form-validation) guide.
|
||||
|
||||
### Step 1 - Import a validator function
|
||||
### Step 1: Importing a validator function
|
||||
|
||||
Reactive forms include a set of validator functions out of the box for common use cases. These functions receive a control to validate against and return an error object or null based on the validation check.
|
||||
Reactive forms include a set of validator functions for common use cases. These functions receive a control to validate against and return an error object or a null value based on the validation check.
|
||||
|
||||
Import the `Validators` class from the `@angular/forms` package.
|
||||
|
||||
|
|
@ -333,7 +344,7 @@ Import the `Validators` class from the `@angular/forms` package.
|
|||
|
||||
</code-example>
|
||||
|
||||
### Step 2 - Make a field required
|
||||
### Step 2: Making a field required
|
||||
|
||||
The most common validation is making a field required. This section describes how to add a required validation to the `firstName` control.
|
||||
|
||||
|
|
@ -343,7 +354,7 @@ In the `ProfileEditor` component, add the `Validators.required` static method as
|
|||
|
||||
</code-example>
|
||||
|
||||
HTML5 has a set of built-in attributes that can be used for native validation, including `required`, `minlength`, `maxlength`, and more. Although _optional_, you can take advantage of these as additional attributes on your form input elements. Add the `required` attribute to the `firstName` input element.
|
||||
HTML5 has a set of built-in attributes that you can use for native validation, including `required`, `minlength`, and `maxlength`. You can take advantage of these optional attributes on your form input elements. Add the `required` attribute to the `firstName` input element.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.html" region="required-attribute" linenums="false" title="src/app/profile-editor/profile-editor.component.html (required attribute)">
|
||||
|
||||
|
|
@ -351,15 +362,15 @@ HTML5 has a set of built-in attributes that can be used for native validation, i
|
|||
|
||||
<div class="alert is-important">
|
||||
|
||||
*Note:* These HTML5 validation attributes should be used _in combination with_ the built-in validators provided by Angular's reactive forms. Using these two validation practices in combination prevents errors about the expression being changed after the template has been checked.
|
||||
**Caution:** Use these HTML5 validation attributes *in combination with* the built-in validators provided by Angular's reactive forms. Using these in combination prevents errors when the expression is changed after the template has been checked.
|
||||
|
||||
</div>
|
||||
|
||||
### Display form status
|
||||
### Displaying form status
|
||||
|
||||
Now that you’ve added a required field to the form control, its initial status is invalid. This invalid status propagates to the parent `FormGroup`, making its status invalid. You have access to the current status of the `FormGroup` through the `status` property on the instance.
|
||||
When you add a required field to the form control, its initial status is invalid. This invalid status propagates to the parent form group element, making its status invalid. Access the current status of the form group instance through its `status` property.
|
||||
|
||||
Display the current status of the `profileForm` using interpolation.
|
||||
Display the current status of `profileForm` using interpolation.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status" linenums="false" title="src/app/profile-editor/profile-editor.component.html (display status)">
|
||||
|
||||
|
|
@ -369,15 +380,15 @@ Display the current status of the `profileForm` using interpolation.
|
|||
<img src="generated/images/guide/reactive-forms/profile-editor-3.png" alt="Profile Editor Validation">
|
||||
</figure>
|
||||
|
||||
The submit button is disabled because the `profileForm` is invalid due to the required `firstName` form control. After you fill out the `firstName` input, the form becomes valid and the submit button is enabled.
|
||||
The **Submit** button is disabled because `profileForm` is invalid due to the required `firstName` form control. After you fill out the `firstName` input, the form becomes valid and the **Submit** button is enabled.
|
||||
|
||||
For more on form validation, visit the [Form Validation](guide/form-validation) guide.
|
||||
|
||||
## Dynamic controls using form arrays
|
||||
|
||||
A `FormArray` is an alternative to a `FormGroup` for managing any number of unnamed controls. As with `FormGroup` instances, you can dynamically insert and remove controls from a `FormArray`, and the `FormArray` instance's value and validation status is calculated from its child controls. However, you don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance. The following example shows you how to manage an array of _aliases_ in the `ProfileEditor`.
|
||||
`FormArray` is an alternative to `FormGroup` for managing any number of unnamed controls. As with form group instances, you can dynamically insert and remove controls from form array instances, and the form array instance value and validation status is calculated from its child controls. However, you don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance. The following example shows you how to manage an array of *aliases* in `ProfileEditor`.
|
||||
|
||||
### Step 1 - Import the `FormArray`
|
||||
### Step 1: Importing the FormArray class
|
||||
|
||||
Import the `FormArray` class from `@angular/forms` to use for type information. The `FormBuilder` service is ready to create a `FormArray` instance.
|
||||
|
||||
|
|
@ -385,9 +396,9 @@ Import the `FormArray` class from `@angular/forms` to use for type information.
|
|||
|
||||
</code-example>
|
||||
|
||||
### Step 2 - Define a `FormArray`
|
||||
### Step 2: Defining a FormArray control
|
||||
|
||||
You can initialize a `FormArray` with any number of controls, from zero to many, by defining them in an array. Add an `aliases` property to the `FormGroup` for the `profileForm` to define the `FormArray`.
|
||||
You can initialize a form array with any number of controls, from zero to many, by defining them in an array. Add an `aliases` property to the form group instance for `profileForm` to define the form array.
|
||||
|
||||
Use the `FormBuilder.array()` method to define the array, and the `FormBuilder.control()` method to populate the array with an initial control.
|
||||
|
||||
|
|
@ -395,57 +406,57 @@ Use the `FormBuilder.array()` method to define the array, and the `FormBuilder.c
|
|||
|
||||
</code-example>
|
||||
|
||||
The _aliases_ control in the `FormGroup` is now populated with a single control until more are added dynamically.
|
||||
The aliases control in the form group instance is now populated with a single control until more controls are added dynamically.
|
||||
|
||||
### Step 3 - Access the `FormArray` control
|
||||
### Step 3: Accessing the FormArray control
|
||||
|
||||
Because a `FormArray` represents an undefined number of controls in array, accessing the control through a getter provides convenience and reusability. Use the _getter_ syntax to create an _aliases_ class property to retrieve the alias's `FormArray` control from the parent `FormGroup`.
|
||||
A getter provides easy access to the aliases in the form array instance compared to repeating the `profileForm.get()` method to get each instance. The form array instance represents an undefined number of controls in an array. It's convenient to access a control through a getter, and this approach is easy to repeat for additional controls.
|
||||
|
||||
Use the getter syntax to create an `aliases` class property to retrieve the alias's form array control from the parent form group.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases-getter" title="src/app/profile-editor/profile-editor.component.ts (aliases getter)">
|
||||
|
||||
</code-example>
|
||||
|
||||
The getter provides easy access to the aliases `FormArray` instead of repeating the `profileForm.get()` method to get the instance.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: Because the returned control is of type `AbstractControl`, you provide an explicit type to access the `FormArray` specific syntax for the methods.
|
||||
**Note:** Because the returned control is of the type `AbstractControl`, you need to provide an explicit type to access the method syntax for the form array instance.
|
||||
|
||||
</div>
|
||||
|
||||
Define a method to dynamically insert an alias control into the alias's `FormArray`. The `FormArray.push()` method inserts the control as a new item in the array.
|
||||
Define a method to dynamically insert an alias control into the alias's form array. The `FormArray.push()` method inserts the control as a new item in the array.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias" title="src/app/profile-editor/profile-editor.component.ts (add alias)">
|
||||
|
||||
</code-example>
|
||||
|
||||
In the template, the controls are iterated over to display each control as a separate input field.
|
||||
In the template, each control is displayed as a separate input field.
|
||||
|
||||
### Step 4 - Display the form array in the template
|
||||
### Step 4: Displaying the form array in the template
|
||||
|
||||
After you define the aliases `FormArray` in your model, you must add it to the template for user input. Similar to the `formGroupName` input provided by the `FormGroupNameDirective`, a `formArrayName` binds communication from the `FormArray` to the template with the `FormArrayNameDirective`.
|
||||
To attach the aliases from your form model, you must add it to the template. Similar to the `formGroupName` input provided by `FormGroupNameDirective`, `formArrayName` binds communication from the form array instance to the template with `FormArrayNameDirective`.
|
||||
|
||||
Add the template HTML below after the closing `formGroupName` `<div>` element.
|
||||
Add the template HTML below after the `<div>` closing the `formGroupName` element.
|
||||
|
||||
<code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.html" region="formarrayname" linenums="false" title="src/app/profile-editor/profile-editor.component.html (aliases form array template)">
|
||||
|
||||
</code-example>
|
||||
|
||||
The `*ngFor` directive iterates over each `FormControl` provided by the aliases `FormArray`. Because `FormArray` elements are unnamed, you assign the _index_ to the `i` variable and pass it to each control to bind it to the `formControlName` input.
|
||||
The `*ngFor` directive iterates over each form control instance provided by the aliases form array instance. Because form array elements are unnamed, you assign the index to the `i` variable and pass it to each control to bind it to the `formControlName` input.
|
||||
|
||||
<figure>
|
||||
<img src="generated/images/guide/reactive-forms/profile-editor-4.png" alt="Profile Editor Aliases">
|
||||
</figure>
|
||||
|
||||
Each time a new `alias` is added, the `FormArray` is provided its control based on the index. This allows you to track each individual control when calculating the status and value of the root control.
|
||||
Each time a new alias instance is added, the new form array instance is provided its control based on the index. This allows you to track each individual control when calculating the status and value of the root control.
|
||||
|
||||
#### Add an Alias
|
||||
#### Adding an alias
|
||||
|
||||
Initially, the form only contains one `Alias` field. Click the `Add Alias` button, and another field appears. You can also validate the array of aliases reported by the form model displayed by the `Form Value` at the bottom of the template.
|
||||
Initially, the form contains one `Alias` field. To add another field, click the **Add Alias** button. You can also validate the array of aliases reported by the form model displayed by `Form Value` at the bottom of the template.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
*Note*: Instead of a `FormControl` for each alias, you could compose another `FormGroup` with additional fields. The process of defining a control for each item is the same.
|
||||
**Note:** Instead of a form control instance for each alias, you can compose another form group instance with additional fields. The process of defining a control for each item is the same.
|
||||
|
||||
</div>
|
||||
|
||||
|
|
@ -483,7 +494,7 @@ Listed below are the base classes and services used to create and manage form co
|
|||
|
||||
<td>
|
||||
|
||||
The abstract base class for the three concrete form control classes; `FormControl`, `FormGroup`, and `FormArray`. It provides their common behaviors and properties.
|
||||
The abstract base class for the concrete form control classes `FormControl`, `FormGroup`, and `FormArray`. It provides their common behaviors and properties.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -497,7 +508,7 @@ Listed below are the base classes and services used to create and manage form co
|
|||
|
||||
<td>
|
||||
|
||||
Manages the value and validity status of an individual form control. It corresponds to an HTML form control such as an `<input>` or `<select>`.
|
||||
Manages the value and validity status of an individual form control. It corresponds to an HTML form control such as `<input>` or `<select>`.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -511,7 +522,7 @@ Listed below are the base classes and services used to create and manage form co
|
|||
|
||||
<td>
|
||||
|
||||
Manages 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`.
|
||||
Manages 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 `FormGroup`.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -547,8 +558,6 @@ Listed below are the base classes and services used to create and manage form co
|
|||
|
||||
</table>
|
||||
|
||||
When importing the `ReactiveFormsModule`, you also gain access to directives to use in your templates for binding the data model to the forms declaratively.
|
||||
|
||||
#### Directives
|
||||
|
||||
<table>
|
||||
|
|
@ -587,7 +596,7 @@ When importing the `ReactiveFormsModule`, you also gain access to directives to
|
|||
|
||||
<td>
|
||||
|
||||
Syncs a `FormControl` in an existing `FormGroup` to a form control element by name.
|
||||
Syncs `FormControl` in an existing `FormGroup` instance to a form control element by name.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -601,7 +610,7 @@ When importing the `ReactiveFormsModule`, you also gain access to directives to
|
|||
|
||||
<td>
|
||||
|
||||
Syncs an existing `FormGroup` to a DOM element.
|
||||
Syncs an existing `FormGroup` instance to a DOM element.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -615,7 +624,7 @@ When importing the `ReactiveFormsModule`, you also gain access to directives to
|
|||
|
||||
<td>
|
||||
|
||||
Syncs a nested `FormGroup` to a DOM element.
|
||||
Syncs a nested `FormGroup` instance to a DOM element.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -629,7 +638,7 @@ When importing the `ReactiveFormsModule`, you also gain access to directives to
|
|||
|
||||
<td>
|
||||
|
||||
Syncs a nested `FormArray` to a DOM element.
|
||||
Syncs a nested `FormArray` instance to a DOM element.
|
||||
|
||||
</td>
|
||||
|
||||
|
|
@ -639,17 +648,17 @@ When importing the `ReactiveFormsModule`, you also gain access to directives to
|
|||
|
||||
### Comparison to template-driven forms
|
||||
|
||||
_Template-driven_ forms, introduced in the [Template-driven forms guide](guide/forms), take a completely different approach.
|
||||
*Template-driven* forms, introduced in the [Template-driven forms guide](guide/forms), take a completely different approach compared to reactive forms. With template-drive forms, you follow these rules:
|
||||
|
||||
* 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 such as `ngModel`.
|
||||
* 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 such as `ngModel`.
|
||||
|
||||
* You don't create Angular form control objects. Angular directives create them for you, using the information in your data bindings.
|
||||
* 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.
|
||||
* 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.
|
||||
|
||||
While this means less code in the component class,
|
||||
[template-driven forms are asynchronous](guide/reactive-forms#async-vs-sync "Async vs sync")
|
||||
which may complicate development in more advanced scenarios.
|
||||
While using template-driven forms means less code in the component class,
|
||||
they are [asynchronous](guide/reactive-forms#async-vs-sync "Async vs sync"),
|
||||
which can complicate development in more advanced scenarios.
|
||||
|
||||
|
||||
{@a async-vs-sync}
|
||||
|
|
@ -663,20 +672,21 @@ In reactive forms, you create the entire form control tree in code.
|
|||
You can immediately update a value or drill down through the descendants 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,
|
||||
Template-driven forms delegate the 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
|
||||
That means you must wait until the next change detection cycle happens 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](guide/lifecycle-hooks#afterview "Lifecycle hooks guide: AfterView"),
|
||||
you'll discover that it has no children.
|
||||
You must wait a tick, using `setTimeout`, before you can
|
||||
You must trigger a change detection cycle using `setTimeout()` before you can
|
||||
extract a value from a control, test its validity, or set it to a new value.
|
||||
|
||||
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.
|
||||
With reactive forms, everything is available immediately.
|
||||
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 8.4 KiB After Width: | Height: | Size: 5.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 9.6 KiB |
Loading…
Reference in New Issue