Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: updated Event binding doc (#45897)

Browse source 
Document updated with the assistance of the SME.
Add missing prerequisites and what's next sections
Make suggested changes to Event binding doc.

PR Close #45897
This commit is contained in:
Virginia Dooley 2022-04-14 21:48:51 +00:00 committed by Jessica Janiuk
parent 4eb529e601
commit 429ebd2558
1 changed files with 36 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
aio/content/guide/event-binding.md
View file

@ -8,91 +8,62 @@ See the <live-example></live-example> for a working example containing the code
</div>
## Prerequisites
* [Basics of components](guide/architecture-components)
* [Basics of templates](guide/glossary#template)
* [Binding syntax](guide/binding-syntax)
* [Template statements](guide/template-statements)
## 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()`.
Create 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 alt="Syntax diagram" src="generated/images/guide/template-syntax/syntax-diagram.svg">
<img src='generated/images/guide/template-syntax/syntax-diagram.svg' alt="Syntax diagram">
</div>
## Binding to passive events
Angular also supports passive event listeners.
For example, use the following steps to make a scroll event passive.
1. Create a file `zone-flags.ts` under `src` directory.
1. Add the following line into this file.
<code-example format="typescript" language="typescript">
(window as any)['__zone_symbol__PASSIVE_EVENTS'] = ['scroll'];
</code-example>
1. In the `src/polyfills.ts` file, before importing `zone.js`, import the newly created `zone-flags`.
<code-example format="typescript" language="typescript">
import './zone-flags';
import 'zone.js'; // Included with Angular CLI.
</code-example>
After those steps, if you add event listeners for the `scroll` event, the listeners will be `passive`.
## Custom events with `EventEmitter`
[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 contain the functionality to delete the hero.
It can only raise an event reporting the user's delete request.
<code-example header="src/app/item-detail/item-detail.component.html (template)" path="event-binding/src/app/item-detail/item-detail.component.html" 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 header="src/app/item-detail/item-detail.component.ts (deleteRequest)" path="event-binding/src/app/item-detail/item-detail.component.ts" region="deleteRequest"></code-example>
The hosting parent component binds to the `deleteRequest` event of the `ItemDetailComponent` as follows.
<code-example header="src/app/app.component.html (event-binding-to-component)" path="event-binding/src/app/app.component.html" region="event-binding-to-component"></code-example>
When the `deleteRequest` event fires, Angular calls the parent component's `deleteItem()` method with the item.
### Determining an event target
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`.
<code-example header="src/app/app.component.html" path="event-binding/src/app/app.component.html" region="custom-directive"></code-example>
Create the following example: (Angular checks to see if `myClick` is an event on the custom `ClickDirective`)
If the target event name, `myClick` fails to match an element event or an output property of `ClickDirective`, Angular reports an "unknown directive" error.
<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 output property of `ClickDirective`, Angular will instead bind to the `myClick` event on the underlying DOM element.
## Binding to passive events
This is an advanced technique that is not necessary for most applications. You may find this useful if you want to optimize frequently occurring events that are causing performance problems.
Angular also supports passive event listeners. For example, use the following steps to make a scroll event passive.
1. Create a file `zone-flags.ts` under `src` directory.
2. Add the following line into this file.
3. In the `src/polyfills.ts` file, before importing zone.js, import the newly created `zone-flags`.
```
import './zone-flags';
import 'zone.js'; // Included with Angular CLI.
```
After those steps, if you add event listeners for the `scroll` event, the listeners will be `passive`.
## What's next
For more information on how event binding works, see [How event binding works](guide/event-binding-concepts).
* For more information on how event binding works, see [How event binding works](guide/event-binding-concepts).
* [Property binding](guide/property-binding)
* [Text interpolation](guide/interpolation)
* [Two-way binding](guide/two-way-binding)
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-02-28
@reviewed 2022-05-10