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

docs: edit event-binding doc copy and headers (#38903) 

PR Close #38903
This commit is contained in:
Kapunahele Wong 2020-09-18 16:43:40 -04:00 committed by Alex Rickabaugh
parent e7ce96e780
commit 177d76533d
4 changed files with 74 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.pullapprove.yml
View File

@ -371,6 +371,7 @@ groups:
'aio/content/guide/built-in-template-functions.md',
'aio/content/examples/built-in-template-functions/**',
'aio/content/guide/event-binding.md',
'aio/content/guide/event-binding-concepts.md',
'aio/content/examples/event-binding/**',
'aio/content/guide/interpolation.md',
'aio/content/examples/interpolation/**',

31
aio/content/guide/event-binding-concepts.md Normal file
View File

@ -0,0 +1,31 @@
# How event binding works
In an event binding, Angular configures an event handler for the target event.
You can use event binding with your own custom events.
When the component or directive raises the event, the handler executes the template statement.
The template statement performs an action in response to the event.
## Handling events
A common way to handle events is to pass the event object, `$event`, to the method handling the event.
The `$event` object often contains information the method needs, such as a user's name or an image URL.
The target event determines the shape of the `$event` object.
If the target event is a native DOM element event, then `$event` is a [DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events), with properties such as `target` and `target.value`.
In the following example the code sets the `<input>` `value` property by binding to the `name` property.
<code-example path="event-binding/src/app/app.component.html" region="event-binding-3" header="src/app/app.component.html"></code-example>
With this example, the following actions occur:
1. The code binds to the `input` event of the `<input>` element, which allows the code to listen for changes.
1. When the user makes changes, the component raises the `input` event.
1. The binding executes the statement within a context that includes the DOM event object, `$event`.
1. Angular retrieves the changed text by following the path `$event.target.value` and updates the `name` property.
If the event belongs to a directive or component, `$event` has the shape that the directive or component produces.

116
aio/content/guide/event-binding.md
View File

@ -1,7 +1,6 @@
# Event binding `(event)`
# Event binding
Event binding allows you to listen for certain events such as
keystrokes, mouse movements, clicks, and touches.
Event binding allows you to listen for and respond to user actions such as keystrokes, mouse movements, clicks, and touches.
<div class="alert is-helpful">
@ -9,100 +8,59 @@ See the <live-example></live-example> for a working example containing the code
</div>
Angular event binding syntax consists of a **target event** name
within parentheses on the left of an equal sign, and a quoted
template statement on the right.
The following event binding listens for the button's click events, calling
the component's `onSave()` method whenever a click occurs:
## Binding to events
To bind to an event you use the Angular event binding syntax.
This syntax consists of a target event name within parentheses to the left of an equal sign, and a quoted template statement to the right.
In the following example, the target event name is `click` and the template statement is `onSave()`.
<code-example language="html" header="Event binding syntax">
&lt;button (click)="onSave()"&gt;Save&lt;button&gt;
</code-example>
The event binding listens for the button's click events and calls the component's `onSave()` method whenever a click occurs.
<div class="lightbox">
<img src='generated/images/guide/template-syntax/syntax-diagram.svg' alt="Syntax diagram">
</div>
## Target event
As above, the target is the button's click event.
<code-example path="event-binding/src/app/app.component.html" region="event-binding-1" header="src/app/app.component.html"></code-example>
Alternatively, use the `on-` prefix, known as the canonical form:
<code-example path="event-binding/src/app/app.component.html" region="event-binding-2" header="src/app/app.component.html"></code-example>
Element events may be the more common targets, but Angular looks first to see if the name matches an event property
of a known directive, as it does in the following example:
<code-example path="event-binding/src/app/app.component.html" region="custom-directive" header="src/app/app.component.html"></code-example>
If the name fails to match an element event or an output property of a known directive,
Angular reports an “unknown directive” error.
## *$event* and event handling statements
In an event binding, Angular sets up an event handler for the target event.
When the event is raised, the handler executes the template statement.
The template statement typically involves a receiver, which performs an action
in response to the event, such as storing a value from the HTML control
into a model.
The binding conveys information about the event. This information can include data values such as an event object, string, or number named `$event`.
The target event determines the shape of the `$event` object.
If the target event is a native DOM element event, then `$event` is a
[DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events),
with properties such as `target` and `target.value`.
Consider this example:
<code-example path="event-binding/src/app/app.component.html" region="event-binding-3" header="src/app/app.component.html"></code-example>
This code sets the `<input>` `value` property by binding to the `name` property.
To listen for changes to the value, the code binds to the `input`
event of the `<input>` element.
When the user makes changes, the `input` event is raised, and the binding executes
the statement within a context that includes the DOM event object, `$event`.
To update the `name` property, the changed text is retrieved by following the path `$event.target.value`.
If the event belongs to a directive&mdash;recall that components
are directives&mdash;`$event` has whatever shape the directive produces.
## Custom events with `EventEmitter`
Directives typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter).
The directive creates an `EventEmitter` and exposes it as a property.
The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything.
Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object.
[Directives](guide/built-in-directives) typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter) as follows.
1. The directive creates an `EventEmitter` and exposes it as a property.
1. The directive then calls `EventEmitter.emit(data)` to emit an event, passing in message data, which can be anything.
1. Parent directives listen for the event by binding to this property and accessing the data through the `$event` object.
Consider an `ItemDetailComponent` that presents item information and responds to user actions.
Although the `ItemDetailComponent` has a delete button, it doesn't know how to delete the hero. It can only raise an event reporting the user's delete request.
Although the `ItemDetailComponent` has a delete button, it doesn't contain the functionality to delete the hero.
It can only raise an event reporting the user's delete request.
Here are the pertinent excerpts from that `ItemDetailComponent`:
<code-example path="event-binding/src/app/item-detail/item-detail.component.html" header="src/app/item-detail/item-detail.component.html (template)" region="line-through"></code-example>
The component defines a `deleteRequest` property that returns an `EventEmitter`.
When the user clicks **Delete**, the component invokes the `delete()` method, telling the `EventEmitter` to emit an `Item` object.
<code-example path="event-binding/src/app/item-detail/item-detail.component.ts" header="src/app/item-detail/item-detail.component.ts (deleteRequest)" region="deleteRequest"></code-example>
The component defines a `deleteRequest` property that returns an `EventEmitter`.
When the user clicks *delete*, the component invokes the `delete()` method,
telling the `EventEmitter` to emit an `Item` object.
Now imagine a hosting parent component that binds to the `deleteRequest` event
of the `ItemDetailComponent`.
The hosting parent component binds to the `deleteRequest` event of the `ItemDetailComponent` as follows.
<code-example path="event-binding/src/app/app.component.html" header="src/app/app.component.html (event-binding-to-component)" region="event-binding-to-component"></code-example>
When the `deleteRequest` event fires, Angular calls the parent component's
`deleteItem()` method, passing the *item-to-delete* (emitted by `ItemDetail`)
in the `$event` variable.
When the `deleteRequest` event fires, Angular calls the parent component's `deleteItem()` method with the item.
## Template statements have side effects
### Determining an event target
Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding-best-practices#avoid-side-effects), template
statements usually do. The `deleteItem()` method does have
a side effect: it deletes an item.
To determine an event target, Angular checks if the name of the target event matches an event property of a known directive.
In the following example, Angular checks to see if `myClick` is an event on the custom `ClickDirective`.
Deleting an item updates the model, and depending on your code, triggers
other changes including queries and saving to a remote server.
These changes propagate through the system and ultimately display in this and other views.
<code-example path="event-binding/src/app/app.component.html" region="custom-directive" header="src/app/app.component.html"></code-example>
If the target event name, `myClick` fails to match an element event or an output property of `ClickDirective`, Angular reports an "unknown directive" error.
<hr />
## What's next
For more information on how event binding works, see [How event binding works](guide/event-binding-concepts).

5
aio/content/navigation.json
View File

@ -777,6 +777,11 @@
"url": "guide/architecture-next-steps",
"title": "Next Steps",
"tooltip": "Beyond the basics."
},
{
"url": "guide/event-binding-concepts",
"title": "How event binding works",
"tooltip": "About event binding."
}
]
},