5 lines
17 KiB
JSON
5 lines
17 KiB
JSON
{
|
|
"id": "guide/property-binding",
|
|
"title": "Property binding",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/property-binding.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"property-binding\">Property binding<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#property-binding\"><i class=\"material-icons\">link</i></a></h1>\n<p>Property binding in Angular helps you set values for properties of HTML elements or directives.\nWith property binding, you can do things such as toggle button functionality, set paths programmatically, and share values between components.</p>\n<div class=\"alert is-helpful\">\n<p>See the <live-example></live-example> for a working example containing the code snippets in this guide.</p>\n</div>\n<h2 id=\"prerequisites\">Prerequisites<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#prerequisites\"><i class=\"material-icons\">link</i></a></h2>\n<p>To get the most out of property binding, you should be familiar with the following:</p>\n<ul>\n<li><a href=\"guide/architecture-components\">Basics of components</a></li>\n<li><a href=\"guide/glossary#template\">Basics of templates</a></li>\n<li><a href=\"guide/binding-syntax\">Binding syntax</a></li>\n</ul>\n<h2 id=\"understanding-the-flow-of-data\">Understanding the flow of data<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#understanding-the-flow-of-data\"><i class=\"material-icons\">link</i></a></h2>\n<p>Property binding moves a value in one direction, from a component's property into a target element property.</p>\n<div class=\"alert is-helpful\">\n<p>For more information on listening for events, see <a href=\"guide/event-binding\">Event binding</a>.</p>\n</div>\n<p>To read a target element property or call one of its methods, see the API reference for <a href=\"api/core/ViewChild\">ViewChild</a> and <a href=\"api/core/ContentChild\">ContentChild</a>.</p>\n<h2 id=\"binding-to-a-property\">Binding to a property<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#binding-to-a-property\"><i class=\"material-icons\">link</i></a></h2>\n<p>To bind to an element's property, enclose it in square brackets, <code>[]</code>, which identifies the property as a target property.\nA target property is the DOM property to which you want to assign a value.\nFor example, the target property in the following code is the image element's <code>src</code> property.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"property-binding\" header=\"src/app/app.component.html\">\n<img [src]=\"itemImageUrl\">\n\n</code-example>\n<p>In most cases, the target name is the name of a property, even when it appears to be the name of an attribute.\nIn this example, <code>src</code> is the name of the <code><img></code> element property.</p>\n<p>The brackets, <code>[]</code>, cause Angular to evaluate the right-hand side of the assignment as a dynamic expression.\nWithout the brackets, Angular treats the right-hand side as a string literal and sets the property to that static value.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"no-evaluation\" header=\"src/app.component.html\">\n<app-item-detail childItem=\"parentItem\"></app-item-detail>\n\n</code-example>\n<p>Omitting the brackets renders the string <code>parentItem</code>, not the value of <code>parentItem</code>.</p>\n<h2 id=\"setting-an-element-property-to-a-component-property-value\">Setting an element property to a component property value<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#setting-an-element-property-to-a-component-property-value\"><i class=\"material-icons\">link</i></a></h2>\n<p>To bind the <code>src</code> property of an <code><img></code> element to a component's property, place the target, <code>src</code>, in square brackets followed by an equal sign and then the property.\nThe property here is <code>itemImageUrl</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"property-binding\" header=\"src/app/app.component.html\">\n<img [src]=\"itemImageUrl\">\n\n</code-example>\n<p>Declare the <code>itemImageUrl</code> property in the class, in this case <code>AppComponent</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.ts\" region=\"item-image\" header=\"src/app/app.component.ts\">\nitemImageUrl = '../assets/phone.png';\n\n</code-example>\n<a id=\"colspan\"></a>\n<h4 id=\"colspan-and-colspan\"><code>colspan</code> and <code>colSpan</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#colspan-and-colspan\"><i class=\"material-icons\">link</i></a></h4>\n<p>A common point of confusion is between the attribute, <code>colspan</code>, and the property, <code>colSpan</code>.\nNotice that these two names differ by only a single letter.</p>\n<p>If you wrote something like this:</p>\n<code-example language=\"html\">\n <tr><td colspan=\"{{1 + 1}}\">Three-Four</td></tr>\n</code-example>\n<p>You'd get this error:</p>\n<code-example language=\"bash\">\n Template parse errors:\n Can't bind to 'colspan' since it isn't a known native property\n</code-example>\n<p>As the message says, the <code><td></code> element does not have a <code>colspan</code> property. This is true\nbecause <code>colspan</code> is an attribute—<code>colSpan</code>, with a capital <code>S</code>, is the\ncorresponding property. Interpolation and property binding can set only <em>properties</em>, not attributes.</p>\n<p>Instead, you'd use property binding and write it like this:</p>\n<code-example path=\"attribute-binding/src/app/app.component.html\" region=\"colSpan\" header=\"src/app/app.component.html\">\n<!-- Notice the colSpan property is camel case -->\n<tr><td [colSpan]=\"1 + 1\">Three-Four</td></tr>\n\n</code-example>\n<p>Another example is disabling a button when the component says that it <code>isUnchanged</code>:</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"disabled-button\" header=\"src/app/app.component.html\">\n<!-- Bind button disabled <a href=\"api/animations/state\" class=\"code-anchor\">state</a> to `isUnchanged` property -->\n<button [disabled]=\"isUnchanged\">Disabled Button</button>\n\n</code-example>\n<p>Another is setting a property of a directive:</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"class-binding\" header=\"src/app/app.component.html\">\n<p [<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]=\"classes\">[<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>] binding to the classes property making this blue</p>\n\n</code-example>\n<p>Yet another is setting the model property of a custom component—a great way\nfor parent and child components to communicate:</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"model-property-binding\" header=\"src/app/app.component.html\">\n<app-item-detail [childItem]=\"parentItem\"></app-item-detail>\n\n</code-example>\n<h2 id=\"toggling-button-functionality\">Toggling button functionality<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#toggling-button-functionality\"><i class=\"material-icons\">link</i></a></h2>\n<p>To disable a button's functionality depending on a Boolean value, bind the DOM <code>disabled</code> property to a property in the class that is <code>true</code> or <code>false</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"disabled-button\" header=\"src/app/app.component.html\">\n<!-- Bind button disabled <a href=\"api/animations/state\" class=\"code-anchor\">state</a> to `isUnchanged` property -->\n<button [disabled]=\"isUnchanged\">Disabled Button</button>\n\n</code-example>\n<p>Because the value of the property <code>isUnchanged</code> is <code>true</code> in the <code>AppComponent</code>, Angular disables the button.</p>\n<code-example path=\"property-binding/src/app/app.component.ts\" region=\"boolean\" header=\"src/app/app.component.ts\">\nisUnchanged = true;\n\n</code-example>\n<h2 id=\"setting-a-directive-property\">Setting a directive property<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#setting-a-directive-property\"><i class=\"material-icons\">link</i></a></h2>\n<p>To set a property of a directive, place the directive within square brackets , such as <code>[<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]</code>, followed by an equal sign and the property.\nHere, the property is <code>classes</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"class-binding\" header=\"src/app/app.component.html\">\n<p [<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]=\"classes\">[<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>] binding to the classes property making this blue</p>\n\n</code-example>\n<p>To use the property, you must declare it in the class, which in this example is <code>AppComponent</code>.\nThe value of <code>classes</code> is <code>special</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.ts\" region=\"directive-property\" header=\"src/app/app.component.ts\">\nclasses = 'special';\n\n</code-example>\n<p>Angular applies the class <code>special</code> to the <code><p></code> element so that you can use <code>special</code> to apply CSS styles.</p>\n<h2 id=\"bind-values-between-components\">Bind values between components<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#bind-values-between-components\"><i class=\"material-icons\">link</i></a></h2>\n<p>To set the model property of a custom component, place the target, here <code>childItem</code>, between square brackets <code>[]</code> followed by an equal sign and the property.\nHere, the property is <code>parentItem</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"model-property-binding\" header=\"src/app/app.component.html\">\n<app-item-detail [childItem]=\"parentItem\"></app-item-detail>\n\n</code-example>\n<p>To use the target and the property, you must declare them in their respective classes.</p>\n<p>Declare the target of <code>childItem</code> in its component class, in this case <code>ItemDetailComponent</code>.</p>\n<p>For example, the following code declares the target of <code>childItem</code> in its component class, in this case <code>ItemDetailComponent</code>.</p>\n<p>Then, the code contains an <code>@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>()</code> decorator with the <code>childItem</code> property so data can flow into it.</p>\n<code-example path=\"property-binding/src/app/item-detail/item-detail.component.ts\" region=\"input-type\" header=\"src/app/item-detail/item-detail.component.ts\">\n@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>() childItem: string;\n\n</code-example>\n<p>Next, the code declares the property of <code>parentItem</code> in its component class, in this case <code>AppComponent</code>.\nIn this example the type of <code>childItem</code> is <code>string</code>, so <code>parentItem</code> needs to be a string.\nHere, <code>parentItem</code> has the string value of <code>lamp</code>.</p>\n<code-example path=\"property-binding/src/app/app.component.ts\" region=\"parent-data-type\" header=\"src/app/app.component.ts\">\nparentItem = 'lamp';\n\n</code-example>\n<p>With this configuration, the view of <code><app-item-detail></code> uses the value of <code>lamp</code> for <code>childItem</code>.</p>\n<h2 id=\"property-binding-and-security\">Property binding and security<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#property-binding-and-security\"><i class=\"material-icons\">link</i></a></h2>\n<p>Property binding can help keep content secure.\nFor example, consider the following malicious content.</p>\n<code-example path=\"property-binding/src/app/app.component.ts\" region=\"malicious-content\" header=\"src/app/app.component.ts\">\nevilTitle = 'Template <script>alert(\"evil never sleeps\")</script> Syntax';\n\n</code-example>\n<p>The component template interpolates the content as follows:</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"malicious-interpolated\" header=\"src/app/app.component.html\">\n<p><span>\"{{evilTitle}}\" is the <i>interpolated</i> evil title.</span></p>\n\n</code-example>\n<p>The browser doesn't process the HTML and instead displays it raw, as follows.</p>\n<code-example language=\"bash\">\n\"Template <script>alert(\"evil never sleeps\")</script> Syntax\" is the interpolated evil title.\n</code-example>\n<p>Angular does not allow HTML with <code><script></code> tags, neither with <a href=\"guide/interpolation\">interpolation</a> nor property binding, which prevents the JavaScript from running.</p>\n<p>In the following example, however, Angular <a href=\"guide/security#sanitization-and-security-contexts\">sanitizes</a> the values before displaying them.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"malicious-content\" header=\"src/app/app.component.html\">\n <!--\n Angular generates a warning for the following line as it sanitizes them\n WARNING: sanitizing HTML stripped some content (see https://g.co/ng/security#xss).\n-->\n <p>\"<span [innerHTML]=\"evilTitle\"></span>\" is the <i>property bound</i> evil title.</p>\n\n</code-example>\n<p>Interpolation handles the <code><script></code> tags differently than property binding, but both approaches render the content harmlessly.\nThe following is the browser output of the sanitized <code>evilTitle</code> example.</p>\n<code-example language=\"bash\">\n\"Template Syntax\" is the property bound evil title.\n</code-example>\n<h2 id=\"property-binding-and-interpolation\">Property binding and interpolation<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#property-binding-and-interpolation\"><i class=\"material-icons\">link</i></a></h2>\n<p>Often <a href=\"guide/interpolation\">interpolation</a> and property binding can achieve the same results.\nThe following binding pairs do the same thing.</p>\n<code-example path=\"property-binding/src/app/app.component.html\" region=\"property-binding-interpolation\" header=\"src/app/app.component.html\">\n<p><img src=\"{{itemImageUrl}}\"> is the <i>interpolated</i> image.</p>\n<p><img [src]=\"itemImageUrl\"> is the <i>property bound</i> image.</p>\n\n<p><span>\"{{interpolationTitle}}\" is the <i>interpolated</i> title.</span></p>\n<p>\"<span [innerHTML]=\"propertyTitle\"></span>\" is the <i>property bound</i> title.</p>\n\n</code-example>\n<p>You can use either form when rendering data values as strings, though interpolation is preferable for readability.\nHowever, when setting an element property to a non-string data value, you must use property binding.</p>\n<h2 id=\"whats-next\">What's next<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/property-binding#whats-next\"><i class=\"material-icons\">link</i></a></h2>\n<ul>\n<li><a href=\"guide/property-binding-best-practices\">Property binding best practices</a></li>\n</ul>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/ajs-quick-reference\n - guide/architecture-components\n - guide/attribute-binding\n - guide/built-in-directives\n - guide/example-apps-list\n - guide/glossary\n - guide/inputs-outputs\n - guide/router\n - guide/template-syntax\n - guide/two-way-binding\n - tutorial/toh-pt3\n-->\n<!-- links from this doc:\n - api/animations/state\n - api/common/NgClass\n - api/core/ContentChild\n - api/core/Input\n - api/core/ViewChild\n - guide/architecture-components\n - guide/binding-syntax\n - guide/event-binding\n - guide/glossary#template\n - guide/interpolation\n - guide/property-binding#bind-values-between-components\n - guide/property-binding#binding-to-a-property\n - guide/property-binding#colspan-and-colspan\n - guide/property-binding#prerequisites\n - guide/property-binding#property-binding\n - guide/property-binding#property-binding-and-interpolation\n - guide/property-binding#property-binding-and-security\n - guide/property-binding#setting-a-directive-property\n - guide/property-binding#setting-an-element-property-to-a-component-property-value\n - guide/property-binding#toggling-button-functionality\n - guide/property-binding#understanding-the-flow-of-data\n - guide/property-binding#whats-next\n - guide/property-binding-best-practices\n - guide/security#sanitization-and-security-contexts\n - https://github.com/angular/angular/edit/master/aio/content/guide/property-binding.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |