docs(component-communication): copy edits and update TOCs (#3417)
This commit is contained in:
Kapunahele Wong
Ward Bell
parent
3ba79f9eb5
commit
9fb57f6b98
|
|
@ -13,21 +13,14 @@ include ../_util-fns
|
|||
|
||||
<a id="toc"></a>
|
||||
:marked
|
||||
## Table of contents
|
||||
# Contents
|
||||
|
||||
[Pass data from parent to child with input binding](#parent-to-child)
|
||||
- [Pass data from parent to child with input binding](#parent-to-child)
|
||||
- [Intercept input property changes with a setter](#parent-to-child-setter)
|
||||
- [Intercept input property changes with `ngOnChanges()`](#parent-to-child-on-changes)
|
||||
- [Parent calls an `@ViewChild()`](#parent-to-view-child)
|
||||
- [Parent and children communicate via a service](#bidirectional-service)
|
||||
|
||||
[Intercept input property changes with a setter](#parent-to-child-setter)
|
||||
|
||||
[Intercept input property changes with *ngOnChanges*](#parent-to-child-on-changes)
|
||||
|
||||
[Parent listens for child event](#child-to-parent)
|
||||
|
||||
[Parent interacts with child via a *local variable*](#parent-to-child-local-var)
|
||||
|
||||
[Parent calls a *ViewChild*](#parent-to-view-child)
|
||||
|
||||
[Parent and children communicate via a service](#bidirectional-service)
|
||||
|
||||
:marked
|
||||
**See the <live-example name="cb-component-communication"></live-example>**.
|
||||
|
|
@ -45,7 +38,7 @@ include ../_util-fns
|
|||
The second `@Input` aliases the child component property name `masterName` as `'master'`.
|
||||
|
||||
The `HeroParentComponent` nests the child `HeroChildComponent` inside an `*ngFor` repeater,
|
||||
binding its `master` string property to the child's `master` alias
|
||||
binding its `master` string property to the child's `master` alias,
|
||||
and each iteration's `hero` instance to the child's `hero` property.
|
||||
|
||||
+makeExample('cb-component-communication/ts/src/app/hero-parent.component.ts')
|
||||
|
|
@ -98,14 +91,14 @@ figure.image-display
|
|||
.l-main-section
|
||||
<a id="parent-to-child-on-changes"></a>
|
||||
:marked
|
||||
## Intercept input property changes with *ngOnChanges*
|
||||
## Intercept input property changes with *ngOnChanges()*
|
||||
|
||||
Detect and act upon changes to input property values with the `ngOnChanges` method of the `OnChanges` lifecycle hook interface.
|
||||
Detect and act upon changes to input property values with the `ngOnChanges()` method of the `OnChanges` lifecycle hook interface.
|
||||
.l-sub-section
|
||||
:marked
|
||||
May prefer this approach to the property setter when watching multiple, interacting input properties.
|
||||
You may prefer this approach to the property setter when watching multiple, interacting input properties.
|
||||
|
||||
Learn about `ngOnChanges` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.
|
||||
Learn about `ngOnChanges()` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.
|
||||
:marked
|
||||
This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes:
|
||||
|
||||
|
|
@ -148,15 +141,15 @@ figure.image-display
|
|||
+makeExample('cb-component-communication/ts/src/app/voter.component.ts')
|
||||
|
||||
:marked
|
||||
Clicking a button triggers emission of a `true` or `false` (the boolean *payload*).
|
||||
Clicking a button triggers emission of a `true` or `false`, the boolean *payload*.
|
||||
|
||||
The parent `VoteTakerComponent` binds an event handler (`onVoted`) that responds to the child event
|
||||
payload (`$event`) and updates a counter.
|
||||
The parent `VoteTakerComponent` binds an event handler called `onVoted()` that responds to the child event
|
||||
payload `$event` and updates a counter.
|
||||
|
||||
+makeExample('cb-component-communication/ts/src/app/votetaker.component.ts')
|
||||
|
||||
:marked
|
||||
The framework passes the event argument — represented by `$event` — to the handler method,
|
||||
The framework passes the event argument—represented by `$event`—to the handler method,
|
||||
and the method processes it:
|
||||
|
||||
figure.image-display
|
||||
|
|
@ -177,30 +170,30 @@ figure.image-display
|
|||
## Parent interacts with child via *local variable*
|
||||
|
||||
A parent component cannot use data binding to read child properties
|
||||
or invoke child methods. We can do both
|
||||
or invoke child methods. You can do both
|
||||
by creating a template reference variable for the child element
|
||||
and then reference that variable *within the parent template*
|
||||
as seen in the following example.
|
||||
|
||||
<a id="countdown-timer-example"></a>
|
||||
We have a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket.
|
||||
The following is a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket.
|
||||
It has `start` and `stop` methods that control the clock and it displays a
|
||||
countdown status message in its own template.
|
||||
+makeExample('cb-component-communication/ts/src/app/countdown-timer.component.ts')
|
||||
:marked
|
||||
Let's see the `CountdownLocalVarParentComponent` that hosts the timer component.
|
||||
The `CountdownLocalVarParentComponent` that hosts the timer component is as follows:
|
||||
|
||||
+makeExample('cb-component-communication/ts/src/app/countdown-parent.component.ts', 'lv')
|
||||
:marked
|
||||
The parent component cannot data bind to the child's
|
||||
`start` and `stop` methods nor to its `seconds` property.
|
||||
|
||||
We can place a local variable (`#timer`) on the tag (`<countdown-timer>`) representing the child component.
|
||||
That gives us a reference to the child component itself and the ability to access
|
||||
You can place a local variable, `#timer`, on the tag `<countdown-timer>` representing the child component.
|
||||
That gives you a reference to the child component and the ability to access
|
||||
*any of its properties or methods* from within the parent template.
|
||||
|
||||
In this example, we wire parent buttons to the child's `start` and `stop` and
|
||||
use interpolation to display the child's `seconds` property.
|
||||
This example wires parent buttons to the child's `start` and `stop` and
|
||||
uses interpolation to display the child's `seconds` property.
|
||||
|
||||
Here we see the parent and child working together.
|
||||
|
||||
|
|
@ -223,52 +216,53 @@ a(id="countdown-tests")
|
|||
.l-main-section
|
||||
<a id="parent-to-view-child"></a>
|
||||
:marked
|
||||
## Parent calls a *ViewChild*
|
||||
## Parent calls an _@ViewChild()_
|
||||
|
||||
The *local variable* approach is simple and easy. But it is limited because
|
||||
the parent-child wiring must be done entirely within the parent template.
|
||||
The parent component *itself* has no access to the child.
|
||||
|
||||
We can't use the *local variable* technique if an instance of the parent component *class*
|
||||
You can't use the *local variable* technique if an instance of the parent component *class*
|
||||
must read or write child component values or must call child component methods.
|
||||
|
||||
When the parent component *class* requires that kind of access,
|
||||
we ***inject*** the child component into the parent as a *ViewChild*.
|
||||
***inject*** the child component into the parent as a *ViewChild*.
|
||||
|
||||
We'll illustrate this technique with the same [Countdown Timer](#countdown-timer-example) example.
|
||||
We won't change its appearance or behavior.
|
||||
The following example illustrates this technique with the same
|
||||
[Countdown Timer](#countdown-timer-example) example.
|
||||
Neither its appearance nor its behavior will change.
|
||||
The child [CountdownTimerComponent](#countdown-timer-example) is the same as well.
|
||||
.l-sub-section
|
||||
:marked
|
||||
We are switching from the *local variable* to the *ViewChild* technique
|
||||
solely for the purpose of demonstration.
|
||||
The switch from the *local variable* to the *ViewChild* technique
|
||||
is solely for the purpose of demonstration.
|
||||
:marked
|
||||
Here is the parent, `CountdownViewChildParentComponent`:
|
||||
+makeExample('cb-component-communication/ts/src/app/countdown-parent.component.ts', 'vc')
|
||||
:marked
|
||||
It takes a bit more work to get the child view into the parent component *class*.
|
||||
|
||||
We import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook.
|
||||
First, you have to import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook.
|
||||
|
||||
We inject the child `CountdownTimerComponent` into the private `timerComponent` property
|
||||
Next, inject the child `CountdownTimerComponent` into the private `timerComponent` property
|
||||
via the `@ViewChild` property decoration.
|
||||
|
||||
The `#timer` local variable is gone from the component metadata.
|
||||
Instead we bind the buttons to the parent component's own `start` and `stop` methods and
|
||||
Instead, bind the buttons to the parent component's own `start` and `stop` methods and
|
||||
present the ticking seconds in an interpolation around the parent component's `seconds` method.
|
||||
|
||||
These methods access the injected timer component directly.
|
||||
|
||||
The `ngAfterViewInit` lifecycle hook is an important wrinkle.
|
||||
The `ngAfterViewInit()` lifecycle hook is an important wrinkle.
|
||||
The timer component isn't available until *after* Angular displays the parent view.
|
||||
So we display `0` seconds initially.
|
||||
So it displays `0` seconds initially.
|
||||
|
||||
Then Angular calls the `ngAfterViewInit` lifecycle hook at which time it is *too late*
|
||||
to update the parent view's display of the countdown seconds.
|
||||
Angular's unidirectional data flow rule prevents us from updating the parent view's
|
||||
in the same cycle. We have to *wait one turn* before we can display the seconds.
|
||||
Angular's unidirectional data flow rule prevents updating the parent view's
|
||||
in the same cycle. The app has to *wait one turn* before it can display the seconds.
|
||||
|
||||
We use `setTimeout` to wait one tick and then revise the `seconds` method so
|
||||
Use `setTimeout()` to wait one tick and then revise the `seconds()` method so
|
||||
that it takes future values from the timer component.
|
||||
|
||||
### Test it
|
||||
|
|
@ -304,12 +298,12 @@ a(id="countdown-tests")
|
|||
|
||||
.l-sub-section
|
||||
:marked
|
||||
Notice that we capture the `subscription` and unsubscribe when the `AstronautComponent` is destroyed.
|
||||
Notice that this example captures the `subscription` and `unsubscribe()` when the `AstronautComponent` is destroyed.
|
||||
This is a memory-leak guard step. There is no actual risk in this app because the
|
||||
lifetime of a `AstronautComponent` is the same as the lifetime of the app itself.
|
||||
That *would not* always be true in a more complex application.
|
||||
|
||||
We do not add this guard to the `MissionControlComponent` because, as the parent,
|
||||
You don't add this guard to the `MissionControlComponent` because, as the parent,
|
||||
it controls the lifetime of the `MissionService`.
|
||||
:marked
|
||||
The *History* log demonstrates that messages travel in both directions between
|
||||
|
|
@ -323,7 +317,7 @@ figure.image-display
|
|||
### Test it
|
||||
|
||||
Tests click buttons of both the parent `MissionControlComponent` and the `AstronautComponent` children
|
||||
and verify that the *History* meets expectations:
|
||||
and verify that the history meets expectations:
|
||||
|
||||
+makeExample('cb-component-communication/e2e-spec.ts', 'bidirectional-service')
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue