honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(forms): reduce ambiguity in forms data flow wording (#41900) 

PR Close #41900
This commit is contained in:
Mikhail 2021-04-30 09:53:32 -07:00 committed by Misko Hevery
parent 6e11febf60
commit f12d067539
2 changed files with 12 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
aio/content/guide/forms-overview.md
View File

@ -36,19 +36,19 @@ The table below summarizes the key differences between reactive and template-dri
||Reactive|Template-driven| ||Reactive|Template-driven|
|--- |--- |--- | |--- |--- |--- |
|[Setup of form model](#setup) | Explicit, created in component class | Implicit, created by directives | |[Setup of form model](#setup) | Explicit, created in component class | Implicit, created by directives |
|[Data model](#data-flow-in-forms) | Structured and immutable | Unstructured and mutable | |[Data model](#mutability-of-the-data-model) | Structured and immutable | Unstructured and mutable |
|Predictability | Synchronous | Asynchronous | |[Data flow](#data-flow-in-forms) | Synchronous | Asynchronous |
|[Form validation](#validation) | Functions | Directives | |[Form validation](#validation) | Functions | Directives |
### Scalability ### Scalability
If forms are a central part of your application, scalability is very important. Being able to reuse form models across components is critical. If forms are a central part of your application, scalability is very important. Being able to reuse form models across components is critical.
Reactive forms are more scalable than template-driven forms. They provide direct access to the underlying form API, and synchronous access to the form data model, making creating large-scale forms easier. Reactive forms are more scalable than template-driven forms. They provide direct access to the underlying form API, and use [synchronous data flow](#data-flow-in-reactive-forms) between the view and the data model, which makes creating large-scale forms easier.
Reactive forms require less setup for testing, and testing does not require deep understanding of change detection to properly test form updates and validation. Reactive forms require less setup for testing, and testing does not require deep understanding of change detection to properly test form updates and validation.
Template-driven forms focus on simple scenarios and are not as reusable. Template-driven forms focus on simple scenarios and are not as reusable.
They abstract away the underlying form API, and provide only asynchronous access to the form data model. They abstract away the underlying form API, and use [asynchronous data flow](#data-flow-in-template-driven-forms) between the view and the data model.
The abstraction of template-driven forms also affects testing. The abstraction of template-driven forms also affects testing.
Tests are deeply reliant on manual change detection execution to run properly, and require more setup. Tests are deeply reliant on manual change detection execution to run properly, and require more setup.
@ -119,6 +119,8 @@ Similarly, when the program logic changes values in the data model, those values
Reactive and template-driven forms differ in how they handle data flowing from the user or from programmatic changes. Reactive and template-driven forms differ in how they handle data flowing from the user or from programmatic changes.
The following diagrams illustrate both kinds of data flow for each type of form, using the favorite-color input field defined above. The following diagrams illustrate both kinds of data flow for each type of form, using the favorite-color input field defined above.
{@a data-flow-in-reactive-forms}
### Data flow in reactive forms ### Data flow in reactive forms
In reactive forms each form element in the view is directly linked to the form model (a `FormControl` instance). Updates from the view to the model and from the model to the view are synchronous and do not depend on how the UI is rendered. In reactive forms each form element in the view is directly linked to the form model (a `FormControl` instance). Updates from the view to the model and from the model to the view are synchronous and do not depend on how the UI is rendered.
@ -146,6 +148,8 @@ The model-to-view diagram shows how a programmatic change to the model is propag
<img src="generated/images/guide/forms-overview/dataflow-reactive-forms-mtv.png" alt="Reactive forms data flow - model to view"> <img src="generated/images/guide/forms-overview/dataflow-reactive-forms-mtv.png" alt="Reactive forms data flow - model to view">
</div> </div>
{@a data-flow-in-template-driven-forms}
### Data flow in template-driven forms ### Data flow in template-driven forms
In template-driven forms, each form element is linked to a directive that manages the form model internally. In template-driven forms, each form element is linked to a directive that manages the form model internally.
@ -181,6 +185,8 @@ The model-to-view diagram shows how data flows from model to view when the `favo
<img src="generated/images/guide/forms-overview/dataflow-td-forms-mtv.png" alt="Template-driven forms data flow - model to view" width="100%"> <img src="generated/images/guide/forms-overview/dataflow-td-forms-mtv.png" alt="Template-driven forms data flow - model to view" width="100%">
</div> </div>
{@a mutability-of-the-data-model}
### Mutability of the data model ### Mutability of the data model
The change-tracking method plays a role in the efficiency of your application. The change-tracking method plays a role in the efficiency of your application.
@ -201,6 +207,7 @@ The difference is demonstrated in the previous examples that use the favorite-co
* With template-driven forms, the **favorite color property** is always modified to its new value. * With template-driven forms, the **favorite color property** is always modified to its new value.
{@a validation} {@a validation}
## Form validation ## Form validation
Validation is an integral part of managing any set of forms. Whether you're checking for required fields or querying an external API for an existing username, Angular provides a set of built-in validators as well as the ability to create custom validators. Validation is an integral part of managing any set of forms. Whether you're checking for required fields or querying an external API for an existing username, Angular provides a set of built-in validators as well as the ability to create custom validators.

2
aio/content/guide/reactive-forms.md
View File

@ -24,7 +24,7 @@ Reactive forms use an explicit and immutable approach to managing the state of a
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 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](guide/forms "Template-driven forms guide") 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. Reactive forms differ from [template-driven forms](guide/forms "Template-driven forms guide") in distinct ways. Reactive forms provide synchronous access to the data model, immutability with observable operators, and change tracking through observable streams.
Template-driven forms allow direct access to modify data in your template, but are less explicit than reactive forms because they rely on directives embedded in the template, along with mutable data to track changes asynchronously. See the [Forms Overview](guide/forms-overview "Overview of Angular forms.") for detailed comparisons between the two paradigms. Template-driven forms allow direct access to modify data in your template, but are less explicit than reactive forms because they rely on directives embedded in the template, along with mutable data to track changes asynchronously. See the [Forms Overview](guide/forms-overview "Overview of Angular forms.") for detailed comparisons between the two paradigms.