5 lines
14 KiB
JSON
5 lines
14 KiB
JSON
{
|
|
"id": "guide/interpolation",
|
|
"title": "Text interpolation",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/interpolation.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=\"text-interpolation\">Text interpolation<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#text-interpolation\"><i class=\"material-icons\">link</i></a></h1>\n<p>Text interpolation allows you to incorporate dynamic string values into your HTML templates.\nWith interpolation, you can dynamically change what appears in an application view, such as displaying a custom greeting that includes the user's name.</p>\n<div class=\"alert is-helpful\">\n<p>See the <live-example></live-example> for all of the syntax and code snippets in this guide.</p>\n</div>\n<h2 id=\"displaying-values-with-interpolation\">Displaying values with interpolation<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#displaying-values-with-interpolation\"><i class=\"material-icons\">link</i></a></h2>\n<p>Interpolation refers to embedding expressions into marked up text.\nBy default, interpolation uses the double curly braces <code>{{</code> and <code>}}</code> as delimiters.</p>\n<p>To illustrate how interpolation works, consider an Angular component that contains a <code>currentCustomer</code> variable:</p>\n<code-example path=\"interpolation/src/app/app.component.ts\" region=\"customer\" header=\"src/app/app.component.ts\">\ncurrentCustomer = 'Maria';\n\n</code-example>\n<p>You can use interpolation to display the value of this variable in the corresponding component template:</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"interpolation-example1\" header=\"src/app/app.component.html\">\n<h3>Current customer: {{ currentCustomer }}</h3>\n\n</code-example>\n<p>Angular replaces <code>currentCustomer</code> with the string value of the corresponding component property.\nIn this case, the value is <code>Maria</code>.</p>\n<p>In the following example, Angular evaluates the <code>title</code> and <code>itemImageUrl</code> properties to display some title text and an image.</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"component-property\" header=\"src/app/app.component.html\">\n<p>{{title}}</p>\n<div><img src=\"{{itemImageUrl}}\"></div>\n\n</code-example>\n<h2 id=\"template-expressions\">Template expressions<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#template-expressions\"><i class=\"material-icons\">link</i></a></h2>\n<p>A template <strong>expression</strong> produces a value and appears within double curly braces, <code>{{ }}</code>.\nAngular resolves the expression and assigns it to a property of a binding target.\nThe target could be an HTML element, a component, or a directive.</p>\n<h3 id=\"resolving-expressions-with-interpolation\">Resolving expressions with interpolation<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#resolving-expressions-with-interpolation\"><i class=\"material-icons\">link</i></a></h3>\n<p>More generally, the text between the braces is a template expression that Angular first evaluates and then converts to a string.\nThe following interpolation illustrates the point by adding two numbers:</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"convert-string\" header=\"src/app/app.component.html\">\n<!-- \"The sum of 1 + 1 is 2\" -->\n<p>The sum of 1 + 1 is {{1 + 1}}.</p>\n\n</code-example>\n<p>Expressions can also invoke methods of the host component such as <code>getVal()</code> in the following example:</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"invoke-method\" header=\"src/app/app.component.html\">\n<!-- \"The sum of 1 + 1 is not 4\" -->\n<p>The sum of 1 + 1 is not {{1 + 1 + getVal()}}.</p>\n\n</code-example>\n<p>With interpolation, Angular performs the following tasks:</p>\n<ol>\n<li>Evaluates all expressions in double curly braces.</li>\n<li>Converts the expression results to strings.</li>\n<li>Links the results to any adjacent literal strings.</li>\n<li>Assigns the composite to an element or directive property.</li>\n</ol>\n<div class=\"alert is-helpful\">\n<p>You can configure the interpolation delimiter with the <a href=\"api/core/Component#interpolation\">interpolation</a> option in the <code>@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a>()</code> metadata.</p>\n</div>\n<h3 id=\"syntax\">Syntax<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#syntax\"><i class=\"material-icons\">link</i></a></h3>\n<p>Template expressions are similar to JavaScript.\nMany JavaScript expressions are legal template expressions, with the following exceptions.</p>\n<p>You can't use JavaScript expressions that have or promote side effects, including:</p>\n<ul>\n<li>Assignments (<code>=</code>, <code>+=</code>, <code>-=</code>, <code>...</code>)</li>\n<li>Operators such as <code>new</code>, <code>typeof</code>, or <code>instanceof</code></li>\n<li>Chaining expressions with <code>;</code> or <code>,</code></li>\n<li>The increment and decrement operators <code>++</code> and <code>--</code></li>\n<li>Some of the ES2015+ operators</li>\n</ul>\n<p>Other notable differences from JavaScript syntax include:</p>\n<ul>\n<li>No support for the bitwise operators such as <code>|</code> and <code>&</code></li>\n<li>New <a href=\"guide/template-expression-operators\">template expression operators</a>, such as <code>|</code>, <code>?.</code> and <code>!</code></li>\n</ul>\n<h2 id=\"expression-context\">Expression context<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#expression-context\"><i class=\"material-icons\">link</i></a></h2>\n<p>Interpolated expressions have a context—a particular part of the application to which the expression belongs.\nTypically, this context is the component instance.</p>\n<p>In the following snippet, the expression <code>recommended</code> and the expression <code>itemImageUrl2</code> refer to properties of the <code>AppComponent</code>.</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"component-context\" header=\"src/app/app.component.html\">\n<h4>{{recommended}}</h4>\n<img [src]=\"itemImageUrl2\">\n\n</code-example>\n<p>An expression can also refer to properties of the <em>template's</em> context such as a <a href=\"guide/structural-directives#shorthand\">template input variable</a> or a <a href=\"guide/template-reference-variables\">template reference variable</a>.</p>\n<p>The following example uses a template input variable of <code>customer</code>.</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"template-input-variable\" header=\"src/app/app.component.html (template input variable)\">\n<ul>\n <li *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let customer of customers\">{{customer.name}}</li>\n</ul>\n\n</code-example>\n<p>This next example features a template reference variable, <code>#customerInput</code>.</p>\n<code-example path=\"interpolation/src/app/app.component.html\" region=\"template-reference-variable\" header=\"src/app/app.component.html (template reference variable)\">\n<label><a href=\"api/core/Type\" class=\"code-anchor\">Type</a> something:\n <input #customerInput>{{customerInput.value}}\n</label>\n\n</code-example>\n<div class=\"alert is-helpful\">\n<p>Template expressions cannot refer to anything in the global namespace, except <code>undefined</code>.\nThey can't refer to <code>window</code> or <code>document</code>.\nAdditionally, they can't call <code>console.log()</code> or <code>Math.max()</code> and they are restricted to referencing members of the expression context.</p>\n</div>\n<h3 id=\"preventing-name-collisions\">Preventing name collisions<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#preventing-name-collisions\"><i class=\"material-icons\">link</i></a></h3>\n<p>The context against which an expression evaluates is the union of the template variables, the directive's context object—if it has one—and the component's members.\nIf you reference a name that belongs to more than one of these namespaces, Angular applies the following logic to determine the context:</p>\n<ol>\n<li>The template variable name.</li>\n<li>A name in the directive's context.</li>\n<li>The component's member names.</li>\n</ol>\n<p>To avoid variables shadowing variables in another context, keep variable names unique.\nIn the following example, the <code>AppComponent</code> template greets the <code>customer</code>, Padma.</p>\n<p>An <code><a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> then lists each <code>customer</code> in the <code>customers</code> array.</p>\n<code-example path=\"interpolation/src/app/app.component.1.ts\" region=\"var-collision\" header=\"src/app/app.component.ts\">\n@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a>({\n template: `\n <div>\n <!-- Hello, Padma -->\n <h1>Hello, {{customer}}</h1>\n <ul>\n <!-- Ebony and Chiho in a list-->\n <li *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let customer of customers\">{{ customer.value }}</li>\n </ul>\n </div>\n `\n})\nclass AppComponent {\n customers = [{value: 'Ebony'}, {value: 'Chiho'}];\n customer = 'Padma';\n}\n\n</code-example>\n<p>The <code>customer</code> within the <code><a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> is in the context of an <code><ng-template></code> and so refers to the <code>customer</code> in the <code>customers</code> array, in this case Ebony and Chiho.\nThis list does not feature Padma because <code>customer</code> outside of the <code><a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> is in a different context.\nConversely, <code>customer</code> in the <code><h1></code> doesn't include Ebony or Chiho because the context for this <code>customer</code> is the class and the class value for <code>customer</code> is Padma.</p>\n<h2 id=\"expression-best-practices\">Expression best practices<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/interpolation#expression-best-practices\"><i class=\"material-icons\">link</i></a></h2>\n<p>When using template expressions, follow these best practices:</p>\n<ul>\n<li>\n<p><strong>Use short expressions</strong></p>\n<p>Use property names or method calls whenever possible.\nKeep application and business logic in the component, where it is easier to develop and test.</p>\n</li>\n<li>\n<p><strong>Quick execution</strong></p>\n<p>Angular executes template expressions after every <a href=\"guide/glossary#change-detection\">change detection</a> cycle.\nMany asynchronous activities trigger change detection cycles, such as promise resolutions, HTTP results, timer events, key presses and mouse moves.</p>\n<p>Expressions should finish quickly to keep the user experience as efficient as possible, especially on slower devices.\nConsider caching values when their computation requires greater resources.</p>\n</li>\n<li>\n<p><strong>No visible side effects</strong></p>\n<p>According to Angular's <a href=\"guide/glossary#unidirectional-data-flow\">unidirectional data flow model</a>, a template expression should not change any application state other than the value of the target property.\nReading a component value should not change some other displayed value.\nThe view should be stable throughout a single rendering pass.</p>\n<div class=\"callout is-important\">\n <header>Idempotent expressions reduce side effects</header>\n<p> An <a href=\"https://en.wikipedia.org/wiki/Idempotence\">idempotent</a> expression is free of side effects and improves Angular's change detection performance.\nIn Angular terms, an idempotent expression always returns <em>exactly the same thing</em> until one of its dependent values changes.</p>\n<p> Dependent values should not change during a single turn of the event loop.\nIf an idempotent expression returns a string or a number, it returns the same string or number if you call it twice consecutively.\nIf the expression returns an object, including an <code>array</code>, it returns the same object <em>reference</em> if you call it twice consecutively.</p>\n</div>\n<div class=\"alert is-important\">\n<p>There is one exception to this behavior that applies to <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code>.\n<code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> has <code>trackBy</code> functionality that can deal with changing values in objects when iterating over them.\nSee <a href=\"guide/built-in-directives#ngfor-with-trackby\">*ngFor with <code>trackBy</code></a> for details.</p>\n</div>\n</li>\n</ul>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/ajs-quick-reference\n - guide/architecture-components\n - guide/binding-syntax\n - guide/example-apps-list\n - guide/glossary\n - guide/property-binding\n - guide/template-statements\n - guide/template-syntax\n - guide/user-input\n - tutorial/toh-pt5\n-->\n<!-- links from this doc:\n - api/common/NgForOf\n - api/core/Component\n - api/core/Component#interpolation\n - api/core/Type\n - guide/built-in-directives#ngfor-with-trackby\n - guide/glossary#change-detection\n - guide/glossary#unidirectional-data-flow\n - guide/interpolation#displaying-values-with-interpolation\n - guide/interpolation#expression-best-practices\n - guide/interpolation#expression-context\n - guide/interpolation#preventing-name-collisions\n - guide/interpolation#resolving-expressions-with-interpolation\n - guide/interpolation#syntax\n - guide/interpolation#template-expressions\n - guide/interpolation#text-interpolation\n - guide/structural-directives#shorthand\n - guide/template-expression-operators\n - guide/template-reference-variables\n - https://en.wikipedia.org/wiki/Idempotence\n - https://github.com/angular/angular/edit/master/aio/content/guide/interpolation.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |