5 lines
14 KiB
JSON
5 lines
14 KiB
JSON
{
|
||
"id": "guide/binding-syntax",
|
||
"title": "Binding syntax",
|
||
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/binding-syntax.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=\"binding-syntax\">Binding syntax<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#binding-syntax\"><i class=\"material-icons\">link</i></a></h1>\n<p>Data binding automatically keeps your page up-to-date based on your application's state.\nYou use data binding to specify things such as the source of an image, the state of a button, or data for a particular user.</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=\"data-binding-and-html\">Data binding and HTML<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#data-binding-and-html\"><i class=\"material-icons\">link</i></a></h2>\n<p>Developers can customize HTML by specifying attributes with string values.\nIn the following example, <code>class</code>, <code>src</code>, and <code>disabled</code> modify the <code><div></code>, <code><img></code>, and <code><button></code> elements respectively.</p>\n<code-example language=\"html\">\n<div class=\"special\">Plain old HTML</div>\n<img src=\"images/item.png\">\n<button disabled>Save</button>\n</code-example>\n<p>Use data binding to control things like the state of a button:</p>\n<code-example path=\"binding-syntax/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\">Save</button>\n\n</code-example>\n<p>Notice that the binding is to the <code>disabled</code> property of the button's DOM element, not the attribute.\nData binding works with properties of DOM elements, components, and directives, not HTML attributes.</p>\n<a id=\"html-attribute-vs-dom-property\"></a>\n<h3 id=\"html-attributes-and-dom-properties\">HTML attributes and DOM properties<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#html-attributes-and-dom-properties\"><i class=\"material-icons\">link</i></a></h3>\n<p>Angular binding distinguishes between HTML attributes and DOM properties.</p>\n<p>Attributes initialize DOM properties and you can configure them to modify an element's behavior.\nProperties are features of DOM nodes.</p>\n<ul>\n<li>\n<p>A few HTML attributes have 1:1 mapping to properties; for example, <code>id</code>.</p>\n</li>\n<li>\n<p>Some HTML attributes don't have corresponding properties; for example, <code>aria-*</code>.</p>\n</li>\n<li>\n<p>Some DOM properties don't have corresponding attributes; for example, <code>textContent</code>.</p>\n</li>\n</ul>\n<div class=\"alert is-important\">\n<p>Remember that HTML attributes and DOM properties are different things, even when they have the same name.</p>\n</div>\n<p>In Angular, the only role of HTML attributes is to initialize element and directive state.</p>\n<p>When you write a data binding, you're dealing exclusively with the DOM properties and events of the target object.</p>\n<h4 id=\"example-1-an-input\">Example 1: an <code><input></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#example-1-an-input\"><i class=\"material-icons\">link</i></a></h4>\n<p>When the browser renders <code><input type=\"text\" value=\"Sarah\"></code>, it creates a\ncorresponding DOM node with a <code>value</code> property and initializes that <code>value</code> to \"Sarah\".</p>\n<code-example language=\"html\">\n<input type=\"text\" value=\"Sarah\">\n</code-example>\n<p>When the user enters <code>Sally</code> into the <code><input></code>, the DOM element <code>value</code> property becomes <code>Sally</code>.\nHowever, if you look at the HTML attribute <code>value</code> using <code>input.getAttribute('value')</code>, you can see that the attribute remains unchanged—it returns \"Sarah\".</p>\n<p>The HTML attribute <code>value</code> specifies the initial value; the DOM <code>value</code> property is the current value.</p>\n<p>To see attributes versus DOM properties in a functioning app, see the <live-example name=\"binding-syntax\"></live-example> especially for binding syntax.</p>\n<h4 id=\"example-2-a-disabled-button\">Example 2: a disabled button<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#example-2-a-disabled-button\"><i class=\"material-icons\">link</i></a></h4>\n<p>A button's <code>disabled</code> property is <code>false</code> by default so the button is enabled.</p>\n<p>When you add the <code>disabled</code> attribute, you are initializing the button's <code>disabled</code> property to <code>true</code> which disables the button.</p>\n<code-example language=\"html\">\n<button disabled>Test Button</button>\n</code-example>\n<p>Adding and removing the <code>disabled</code> attribute disables and enables the button.\nHowever, the value of the attribute is irrelevant, which is why you cannot enable a button by writing <code><button disabled=\"false\">Still Disabled</button></code>.</p>\n<p>To control the state of the button, set the <code>disabled</code> property instead.</p>\n<h4 id=\"property-and-attribute-comparison\">Property and attribute comparison<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#property-and-attribute-comparison\"><i class=\"material-icons\">link</i></a></h4>\n<p>Though you could technically set the <code>[attr.disabled]</code> attribute binding, the values are different in that the property binding must be a boolean value, while its corresponding attribute binding relies on whether the value is <code>null</code> or not.\nConsider the following:</p>\n<code-example language=\"html\">\n<input [disabled]=\"condition ? true : false\">\n<input [attr.disabled]=\"condition ? 'disabled' : null\">\n</code-example>\n<p>The first line, which uses the <code>disabled</code> property, uses a boolean value.\nThe second line, which uses the disabled attribute checks for <code>null</code>.</p>\n<p>Generally, use property binding over attribute binding as a boolean value is easy to read, the syntax is shorter, and a property is more performant.</p>\n<p>To see the <code>disabled</code> button example in a functioning application, see the <live-example></live-example>.\nThis example shows you how to toggle the disabled property from the component.</p>\n<h2 id=\"types-of-data-binding\">Types of data binding<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#types-of-data-binding\"><i class=\"material-icons\">link</i></a></h2>\n<p>Angular provides three categories of data binding according to the direction of data flow:</p>\n<ul>\n<li>From the source to view</li>\n<li>From view to source</li>\n<li>In a two way sequence of view to source to view</li>\n</ul>\n<style>\n td, th {vertical-align: top}\n</style>\n<table width=\"100%\">\n <colgroup><col width=\"30%\">\n \n <col width=\"50%\">\n \n <col width=\"20%\">\n \n </colgroup><tbody><tr>\n <th>\n Type\n </th>\n <th>\n Syntax\n </th>\n <th>\n Category\n </th>\n </tr>\n <tr>\n <td>\n Interpolation<br>\n Property<br>\n Attribute<br>\n Class<br>\n Style\n </td>\n <td>\n <code-example>\n {{expression}}\n [target]=\"expression\"\n bind-target=\"expression\"\n </code-example>\n </td>\n <td>\n One-way<br>from data source<br>to view target\n </td>\n </tr><tr>\n <td>\n Event\n </td>\n <td>\n <code-example>\n (target)=\"statement\"\n on-target=\"statement\"\n </code-example>\n </td>\n <td>\n One-way<br>from view target<br>to data source\n </td>\n </tr>\n <tr>\n <td>\n Two-way\n </td>\n <td>\n <code-example>\n [(target)]=\"expression\"\n bindon-target=\"expression\"\n </code-example>\n </td>\n <td>\n Two-way\n </td>\n </tr>\n \n</tbody></table>\n<p>Binding types other than interpolation have a target name to the left of the equal sign.\nThe target of a binding is a property or event, which you surround with square brackets, <code>[]</code>, parentheses, <code>()</code>, or both, <code>[()]</code>.</p>\n<p>The binding punctuation of <code>[]</code>, <code>()</code>, <code>[()]</code>, and the prefix specify the direction of data flow.</p>\n<ul>\n<li>Use <code>[]</code> to bind from source to view.</li>\n<li>Use <code>()</code> to bind from view to source.</li>\n<li>Use <code>[()]</code> to bind in a two way sequence of view to source to view.</li>\n</ul>\n<p>Place the expression or statement to the right of the equal sign within double quotes, <code>\"\"</code>.\nFor more information see <a href=\"guide/interpolation\">Interpolation</a> and <a href=\"guide/template-statements\">Template statements</a>.</p>\n<h2 id=\"binding-types-and-targets\">Binding types and targets<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/binding-syntax#binding-types-and-targets\"><i class=\"material-icons\">link</i></a></h2>\n<p>The target of a data binding can be a property, an event, or an attribute name.\nEvery public member of a source directive is automatically available for binding in a template expression or statement.\nThe following table summarizes the targets for the different binding types.</p>\n<style>\n td, th {vertical-align: top}\n</style>\n<table width=\"100%\">\n <colgroup><col width=\"10%\">\n \n <col width=\"15%\">\n \n <col width=\"75%\">\n \n </colgroup><tbody><tr>\n <th>\n Type\n </th>\n <th>\n Target\n </th>\n <th>\n Examples\n </th>\n </tr>\n <tr>\n <td>\n Property\n </td>\n <td>\n Element property<br>\n Component property<br>\n Directive property\n </td>\n <td>\n <code>src</code>, <code>hero</code>, and <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code> in the following:\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"property-binding-syntax-1\">\n<img [src]=\"heroImageUrl\">\n<app-hero-detail [hero]=\"currentHero\"></app-hero-detail>\n<div [<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]=\"{'special': isSpecial}\"></div>\n\n</code-example>\n <!-- For more information, see [Property Binding](guide/property-binding). -->\n </td>\n </tr>\n <tr>\n <td>\n Event\n </td>\n <td>\n Element event<br>\n Component event<br>\n Directive event\n </td>\n <td>\n <code>click</code>, <code>deleteRequest</code>, and <code>myClick</code> in the following:\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"event-binding-syntax-1\">\n<button (click)=\"onSave()\">Save</button>\n<app-hero-detail (deleteRequest)=\"deleteHero()\"></app-hero-detail>\n<div (myClick)=\"clicked=$event\" clickable>click me</div>\n\n</code-example>\n </td>\n </tr>\n <tr>\n <td>\n Two-way\n </td>\n <td>\n Event and property\n </td>\n <td>\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"2-way-binding-syntax-1\">\n<input [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"name\">\n\n</code-example>\n </td>\n </tr>\n <tr>\n <td>\n Attribute\n </td>\n <td>\n Attribute\n (the exception)\n </td>\n <td>\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"attribute-binding-syntax-1\">\n<button [attr.aria-label]=\"help\">help</button>\n\n</code-example>\n </td>\n </tr>\n <tr>\n <td>\n Class\n </td>\n <td>\n <code>class</code> property\n </td>\n <td>\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"class-binding-syntax-1\">\n<div [class.special]=\"isSpecial\">Special</div>\n\n</code-example>\n </td>\n </tr>\n <tr>\n <td>\n Style\n </td>\n <td>\n <code><a href=\"api/animations/style\" class=\"code-anchor\">style</a></code> property\n </td>\n <td>\n <code-example path=\"template-syntax/src/app/app.component.html\" region=\"style-binding-syntax-1\">\n<button [style.color]=\"isSpecial ? 'red' : 'green'\">\n\n</code-example>\n </td>\n </tr>\n</tbody></table>\n\n \n</div>\n\n<!-- links to this doc:\n - errors/NG8002\n - guide/accessibility\n - guide/example-apps-list\n - guide/property-binding\n - guide/styleguide\n - guide/template-syntax\n-->\n<!-- links from this doc:\n - api/animations/state\n - api/animations/style\n - api/common/NgClass\n - api/forms/NgModel\n - guide/binding-syntax#binding-syntax\n - guide/binding-syntax#binding-types-and-targets\n - guide/binding-syntax#data-binding-and-html\n - guide/binding-syntax#example-1-an-input\n - guide/binding-syntax#example-2-a-disabled-button\n - guide/binding-syntax#html-attributes-and-dom-properties\n - guide/binding-syntax#property-and-attribute-comparison\n - guide/binding-syntax#types-of-data-binding\n - guide/interpolation\n - guide/template-statements\n - https://github.com/angular/angular/edit/master/aio/content/guide/binding-syntax.md?message=docs%3A%20describe%20your%20change...\n-->"
|
||
} |