diff --git a/aio/content/examples/two-way-binding/src/app/app.component.html b/aio/content/examples/two-way-binding/src/app/app.component.html index f96bd38688..f6354df718 100644 --- a/aio/content/examples/two-way-binding/src/app/app.component.html +++ b/aio/content/examples/two-way-binding/src/app/app.component.html @@ -1,7 +1,9 @@

Two-way Binding

+ +
Resizable Text
diff --git a/aio/content/examples/two-way-binding/src/app/sizer/sizer.component.ts b/aio/content/examples/two-way-binding/src/app/sizer/sizer.component.ts index b9c8f670e2..51503f40d6 100644 --- a/aio/content/examples/two-way-binding/src/app/sizer/sizer.component.ts +++ b/aio/content/examples/two-way-binding/src/app/sizer/sizer.component.ts @@ -5,9 +5,9 @@ import { Component, Input, Output, EventEmitter } from '@angular/core'; templateUrl: './sizer.component.html', styleUrls: ['./sizer.component.css'] }) +// #docregion sizer-component export class SizerComponent { - @Input() size: number | string; @Output() sizeChange = new EventEmitter(); @@ -18,5 +18,5 @@ export class SizerComponent { this.size = Math.min(40, Math.max(8, +this.size + delta)); this.sizeChange.emit(this.size); } - } +// #enddocregion sizer-component diff --git a/aio/content/guide/two-way-binding.md b/aio/content/guide/two-way-binding.md index a824130c70..bfced73baa 100644 --- a/aio/content/guide/two-way-binding.md +++ b/aio/content/guide/two-way-binding.md @@ -1,7 +1,7 @@ -# Two-way binding `[(...)]` +# Two-way binding -Two-way binding gives your app a way to share data between a component class and -its template. +Two-way binding gives components in your application a way to share data. +Use two-way binding binding to listen for events and update values simultaneously between parent and child components.
@@ -9,68 +9,73 @@ See the for a working example containing the code
-## Basics of two-way binding +## Prerequisites -Two-way binding does two things: +To get the most out of two-way binding, you should have a basic understanding of the following concepts: -1. Sets a specific element property. -1. Listens for an element change event. +* [Property binding](guide/property-binding) +* [Event binding](guide/event-binding) +* [Inputs and Outputs](guide/inputs-outputs) -Angular offers a special _two-way data binding_ syntax for this purpose, `[()]`. -The `[()]` syntax combines the brackets -of property binding, `[]`, with the parentheses of event binding, `()`. +
-
+Two-way binding combines property binding with event binding: -
- [( )] = banana in a box -
+* [Property binding](guide/property-binding) sets a specific element property. +* [Event binding](guide/event-binding) listens for an element change event. -Visualize a *banana in a box* to remember that the parentheses go _inside_ the brackets. +## Adding two-way data binding -
+Angular's two-way binding syntax is a combination of square brackets and parentheses, `[()]`. +The `[()]` syntax combines the brackets of property binding, `[]`, with the parentheses of event binding, `()`, as follows. -The `[()]` syntax is easy to demonstrate when the element has a settable -property called `x` and a corresponding event named `xChange`. -Here's a `SizerComponent` that fits this pattern. -It has a `size` value property and a companion `sizeChange` event: + - +## How two-way binding works + +For two-way data binding to work, the `@Output()` property must use the pattern, `inputChange`, where `input` is the name of the `@Input()` property. +For example, if the `@Input()` property is `size`, the `@Output()` property must be `sizeChange`. + +The following `sizerComponent` has a `size` value property and a `sizeChange` event. +The `size` property is an `@Input()`, so data can flow into the `sizerComponent`. +The `sizeChange` event is an `@Output()`, which allows data to flow out of the `sizerComponent` to the parent component. + +Next, there are two methods, `dec()` to decrease the font size and `inc()` to increase the font size. +These two methods use `resize()` to change the value of the `size` property within min/max value constraints, and to emit an event that conveys the new `size` value. + + + +The `sizerComponent` template has two buttons that each bind the click event to the `inc()` and `dec()` methods. +When the user clicks one of the buttons, the `sizerComponent` calls the corresponding method. +Both methods, `inc()` and `dec()`, call the `resize()` method with a `+1` or `-1`, which in turn raises the `sizeChange` event with the new size value. -The initial `size` is an input value from a property binding. -Clicking the buttons increases or decreases the `size`, within -min/max value constraints, -and then raises, or emits, the `sizeChange` event with the adjusted size. -Here's an example in which the `AppComponent.fontSizePx` is two-way bound to the `SizerComponent`: +In the `AppComponent` template, `fontSizePx` is two-way bound to the `SizerComponent`. - + -The `AppComponent.fontSizePx` establishes the initial `SizerComponent.size` value. +In the `AppComponent`, `fontSizePx` establishes the initial `SizerComponent.size` value by setting the value to `16`. -Clicking the buttons updates the `AppComponent.fontSizePx` via the two-way binding. -The revised `AppComponent.fontSizePx` value flows through to the _style_ binding, -making the displayed text bigger or smaller. +Clicking the buttons updates the `AppComponent.fontSizePx`. +The revised `AppComponent.fontSizePx` value updates the style binding, which makes the displayed text bigger or smaller. -The two-way binding syntax is really just syntactic sugar for a _property_ binding and an _event_ binding. -Angular desugars the `SizerComponent` binding into this: +The two-way binding syntax is shorthand for a combination of property binding and event binding. +The `SizerComponent` binding as separate property binding and event binding is as follows. - + -The `$event` variable contains the payload of the `SizerComponent.sizeChange` event. +The `$event` variable contains the data of the `SizerComponent.sizeChange` event. Angular assigns the `$event` value to the `AppComponent.fontSizePx` when the user clicks the buttons. -## Two-way binding in forms +
-The two-way binding syntax is a great convenience compared to -separate property and event bindings. It would be convenient to -use two-way binding with HTML form elements like `` and -`