5b31a0a294
This is part of a re-factor of template syntax and structure. The first phase breaks out template syntax into multiple documents. The second phase will be a rewrite of each doc. Specifically, this PR does the following: - Breaks sections of the current template syntax document each into their own page. - Corrects the links to and from these new pages. - Adds template syntax subsection to the left side NAV which contains all the new pages. - Adds the new files to pullapprove. PR Close #36954
109 lines
5.3 KiB
Markdown
109 lines
5.3 KiB
Markdown
# Event binding `(event)`
|
|
|
|
Event binding allows you to listen for certain events such as
|
|
keystrokes, mouse movements, clicks, and touches.
|
|
|
|
<div class="alert is-helpful">
|
|
|
|
See the <live-example></live-example> for a working example containing the code snippets in this guide.
|
|
|
|
</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:
|
|
|
|
<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—recall that components
|
|
are directives—`$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.
|
|
|
|
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.
|
|
|
|
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>
|
|
|
|
<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`.
|
|
|
|
<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.
|
|
|
|
## Template statements have side effects
|
|
|
|
Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding#avoid-side-effects), template
|
|
statements usually do. The `deleteItem()` method does have
|
|
a side effect: it deletes an item.
|
|
|
|
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.
|