skills/angular__angular
1
0
Fork 0
mirror of https://github.com/angular/angular.git synced 2026-09-14 13:54:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: updated Property binding doc (#45897)

Browse Source 
Refined and edited as a task-based document with the assistance
of the SME
Add missing prerequisites and what's next sections

PR Close #45897
This commit is contained in:
Virginia Dooley
2022-04-14 22:05:34 +00:00
committed by Jessica Janiuk
parent 429ebd2558
commit 6276bed4ab
1 changed files with 44 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
aio/content/guide/property-binding.md
+44 -147
View File
@@ -1,8 +1,6 @@
# Property binding
Property binding in Angular helps you set values for properties of HTML elements or directives.
Use property binding to do things such as toggle button functionality, set paths programmatically, and share values between components.
Property binding in Angular helps you set values for properties of HTML elements or directives. Use property binding to do things such as toggle button functionality, set paths programmatically, and share values between components.
<div class="alert is-helpful">
@@ -12,11 +10,9 @@ See the <live-example></live-example> for a working example containing the code
## Prerequisites
To get the most out of property binding, you should be familiar with the following:
* [Basics of components](guide/architecture-components)
* [Basics of templates](guide/glossary#template)
* [Binding syntax](guide/binding-syntax)
* [Basics of components](guide/architecture-components)
* [Basics of templates](guide/glossary#template)
* [Binding syntax](guide/binding-syntax)
## Understanding the flow of data
@@ -32,178 +28,79 @@ To read a target element property or call one of its methods, see the API refere
## Binding to a property
To bind to an element's property, enclose it in square bracket \(`[]`\) characters, which identifies the property as a target property.
A target property is the DOM property to which you want to assign a value.
For example, the target property in the following code is the image element's `src` property.
To bind to an element's property, enclose it in square brackets, '[]', which identifies the property as a target property.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="property-binding"></code-example>
A target property is the DOM property to which you want to assign a value.
To assign a value to a target property for the image element's 'src' property, type the following code:
<code-example path="property-binding/src/app/app.component.html" region="property-binding" header="src/app/app.component.html"></code-example>
In most cases, the target name is the name of a property, even when it appears to be the name of an attribute.
In this example, `src` is the name of the `<img>` element property.
The square bracket \(`[]`\) characters cause Angular to evaluate the right-hand side of the assignment as a dynamic expression.
In this example, 'src' is the name of the '<img>' element property.
The brackets, '[]', cause Angular to evaluate the right-hand side of the assignment as a dynamic expression.
Without the brackets, Angular treats the right-hand side as a string literal and sets the property to that static value.
<code-example header="src/app.component.html" path="property-binding/src/app/app.component.html" region="no-evaluation"></code-example>
To assign a string to a property, type the following code:
Omitting the brackets renders the string `parentItem`, not the value of `parentItem`.
<code-example path="property-binding/src/app/app.component.html" region="no-evaluation" header="src/app.component.html"></code-example>
Omitting the brackets renders the string 'parentItem', not the value of 'parentItem'.
## Setting an element property to a component property value
To bind the `src` property of an `<img>` element to a component's property, place the target, `src`, in square brackets followed by an equal sign and then the property.
The property here is `itemImageUrl`.
To bind the ‘src’ property of an '<img>' element to a component's property, place the target, ‘src', in square brackets followed by an equal sign and then the property.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="property-binding"></code-example>
Using the property 'itemImageUrl', type the following code:
Declare the `itemImageUrl` property in the class, in this case `AppComponent`.
<code-example path="property-binding/src/app/app.component.html" region="property-binding" header="src/app/app.component.html"></code-example>
<code-example header="src/app/app.component.ts" path="property-binding/src/app/app.component.ts" region="item-image"></code-example>
Declare the 'itemImageUrl' property in the class, in this case 'AppComponent'.
<a id="colspan"></a>
<code-example path="property-binding/src/app/app.component.ts" region="item-image" header="src/app/app.component.ts"></code-example>
#### `colspan` and `colSpan`
{@a colspan}
A common point of confusion is between the attribute, `colspan`, and the property, `colSpan`.
Notice that these two names differ by only a single letter.
#### 'colspan' and 'colSpan'
If you wrote something like this:
A common point of confusion is between the attribute, 'colspan', and the property, 'colSpan'. Notice that these two names differ by only a single letter.
<code-example format="html" language="html">
To use property binding using colSpan, type the following:
&lt;tr&gt;&lt;td colspan="{{1 + 1}}"&gt;Three-Four&lt;/td&gt;&lt;/tr&gt;
<code-example path="attribute-binding/src/app/app.component.html" region="colSpan" header="src/app/app.component.html"></code-example>
</code-example>
To disable a button when the component says that it 'isUnchanged', type the following:
You'd get this error:
<code-example path="property-binding/src/app/app.component.html" region="disabled-button" header="src/app/app.component.html"></code-example>
<code-example format="shell" hideCopy language="shell">
To set a property of a directive, type the following:
Template parse errors:
Can't bind to 'colspan' because it isn't a known built-in property
<code-example path="property-binding/src/app/app.component.html" region="class-binding" header="src/app/app.component.html"></code-example>
</code-example>
To set the model property of a custom component for parent and child components to communicated, type the following:
As the message says, the `<td>` element does not have a `colspan` property.
This is true because `colspan` is an attribute &mdash;`colSpan`, with a capital `S`, is the corresponding property.
Interpolation and property binding can set only *properties*, not attributes.
<code-example path="property-binding/src/app/app.component.html" region="model-property-binding" header="src/app/app.component.html"></code-example>
Instead, you'd use property binding and write it like this:
<code-example header="src/app/app.component.html" path="attribute-binding/src/app/app.component.html" region="colSpan"></code-example>
Another example is disabling a button when the component says that it `isUnchanged`:
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="disabled-button"></code-example>
Another is setting a property of a directive:
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="class-binding"></code-example>
Yet another is setting the model property of a custom component &mdash;a great way for parent and child components to communicate:
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="model-property-binding"></code-example>
## Toggling button functionality
To disable a button's functionality depending on a Boolean value, bind the DOM `disabled` property to a property in the class that is `true` or `false`.
To disable a button's functionality depending on a Boolean value, bind the DOM 'disabled' property to a property in the class that is 'true' or 'false'.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="disabled-button"></code-example>
<code-example path="property-binding/src/app/app.component.html" region="disabled-button" header="src/app/app.component.html"></code-example>
Because the value of the property `isUnchanged` is `true` in the `AppComponent`, Angular disables the button.
Because the value of the property 'isUnchanged' is 'true' in the 'AppComponent', Angular disables the button.
<code-example header="src/app/app.component.ts" path="property-binding/src/app/app.component.ts" region="boolean"></code-example>
## Setting a directive property
To set a property of a directive, place the directive within square brackets , such as `[ngClass]`, followed by an equal sign and the property.
Here, the property is `classes`.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="class-binding"></code-example>
To use the property, you must declare it in the class, which in this example is `AppComponent`.
The value of `classes` is `special`.
<code-example header="src/app/app.component.ts" path="property-binding/src/app/app.component.ts" region="directive-property"></code-example>
Angular applies the class `special` to the `<p>` element so that you can use `special` to apply CSS styles.
## Bind values between components
To set the model property of a custom component, place the target, here `childItem`, between square bracket \(`[]`\) characters followed by an equal sign and the property.
Here, the property is `parentItem`.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="model-property-binding"></code-example>
To use the target and the property, you must declare them in their respective classes.
Declare the target of `childItem` in its component class, in this case `ItemDetailComponent`.
For example, the following code declares the target of `childItem` in its component class, in this case `ItemDetailComponent`.
Then, the code contains an `@Input()` decorator with the `childItem` property so data can flow into it.
<code-example header="src/app/item-detail/item-detail.component.ts" path="property-binding/src/app/item-detail/item-detail.component.ts" region="input-type"></code-example>
Next, the code declares the property of `parentItem` in its component class, in this case `AppComponent`.
In this example the type of `childItem` is `string`, so `parentItem` needs to be a string.
Here, `parentItem` has the string value of `lamp`.
<code-example header="src/app/app.component.ts" path="property-binding/src/app/app.component.ts" region="parent-data-type"></code-example>
With this configuration, the view of `<app-item-detail>` uses the value of `lamp` for `childItem`.
## Property binding and security
Property binding can help keep content secure.
For example, consider the following malicious content.
<code-example header="src/app/app.component.ts" path="property-binding/src/app/app.component.ts" region="malicious-content"></code-example>
The component template interpolates the content as follows:
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="malicious-interpolated"></code-example>
The browser doesn't process the HTML and instead displays it raw, as follows.
<code-example format="shell" language="shell">
"Template &lt;script&gt;alert("evil never sleeps")&lt;/script&gt; Syntax" is the interpolated evil title.
</code-example>
Angular does not allow HTML with `<script>` tags, neither with [interpolation](guide/interpolation) nor property binding, which prevents the JavaScript from running.
In the following example, however, Angular [sanitizes](guide/security#sanitization-and-security-contexts) the values before displaying them.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="malicious-content"></code-example>
Interpolation handles the `<script>` tags differently than property binding, but both approaches render the content harmlessly.
The following is the browser output of the sanitized `evilTitle` example.
<code-example format="shell" language="shell">
"Template Syntax" is the property bound evil title.
</code-example>
## Property binding and interpolation
Often [interpolation](guide/interpolation) and property binding can achieve the same results.
The following binding pairs do the same thing.
<code-example header="src/app/app.component.html" path="property-binding/src/app/app.component.html" region="property-binding-interpolation"></code-example>
Use either form when rendering data values as strings, though interpolation is preferable for readability.
However, when setting an element property to a non-string data value, you must use property binding.
<code-example path="property-binding/src/app/app.component.ts" region="boolean" header="src/app/app.component.ts"></code-example>
## What's next
* [Property binding best practices](guide/property-binding-best-practices)
* [Property binding best practices](guide/property-binding-best-practices)
* [Event binding](guide/event-binding)
* [Text Interpolation](guide/interpolation)
* [Class & Style Binding](guide/class-binding)
* [Attribute Binding](guide/attribute-binding)
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-02-28
@reviewed 2022-04-14