5 lines
16 KiB
JSON
5 lines
16 KiB
JSON
{
|
|
"id": "guide/template-reference-variables",
|
|
"title": "Template variables",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/template-reference-variables.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=\"template-variables\">Template variables<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#template-variables\"><i class=\"material-icons\">link</i></a></h1>\n<p>Template variables help you use data from one part of a template in another part of the template.\nWith template variables, you can perform tasks such as respond to user input or finely tune your application's forms.</p>\n<p>A template variable can refer to the following:</p>\n<ul>\n<li>a DOM element within a template</li>\n<li>a directive</li>\n<li>an element</li>\n<li><a href=\"api/core/TemplateRef\">TemplateRef</a></li>\n<li>a <a href=\"https://developer.mozilla.org/en-US/docs/Web/Web_Components\" title=\"MDN: Web Components\">web component</a></li>\n</ul>\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=\"syntax\">Syntax<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#syntax\"><i class=\"material-icons\">link</i></a></h2>\n<p>In the template, you use the hash symbol, <code>#</code>, to declare a template variable.\nThe following template variable, <code>#phone</code>, declares a <code>phone</code> variable on an <code><input></code> element.</p>\n<code-example path=\"template-reference-variables/src/app/app.component.html\" region=\"ref-var\" header=\"src/app/app.component.html\">\n<input #phone placeholder=\"phone number\" />\n\n</code-example>\n<p>You can refer to a template variable anywhere in the component's template.\nHere, a <code><button></code> further down the template refers to the <code>phone</code> variable.</p>\n<code-example path=\"template-reference-variables/src/app/app.component.html\" region=\"ref-phone\" header=\"src/app/app.component.html\">\n<input #phone placeholder=\"phone number\" />\n\n<!-- lots of other elements -->\n\n<!-- phone refers to the input element; pass its `value` to an event handler -->\n<button (click)=\"callPhone(phone.value)\">Call</button>\n\n</code-example>\n<h2 id=\"how-angular-assigns-values-to-template-variables\">How Angular assigns values to template variables<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#how-angular-assigns-values-to-template-variables\"><i class=\"material-icons\">link</i></a></h2>\n<p>Angular assigns a template variable a value based on where you declare the variable:</p>\n<ul>\n<li>If you declare the variable on a component, the variable refers to the component instance.</li>\n<li>If you declare the variable on a standard HTML tag, the variable refers to the element.</li>\n<li>If you declare the variable on an <code><ng-template></code> element, the variable refers to a <code><a href=\"api/core/TemplateRef\" class=\"code-anchor\">TemplateRef</a></code> instance, which represents the template.\nFor more information on <code><ng-template></code>, see <a href=\"guide/structural-directives#asterisk\">How Angular uses the asterisk, <code>*</code>, syntax</a> in <a href=\"guide/structural-directives\">Structural directives</a>.</li>\n<li>\n<p>If the variable specifies a name on the right-hand side, such as <code>#var=\"<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>\"</code>, the variable refers to the directive or component on the element with a matching <code>exportAs</code> name.</p>\n<!-- What does the second half of this mean?^^ Can we explain this more fully? Could I see a working example? -kw -->\n</li>\n</ul>\n<h3 id=\"using-ngform-with-template-variables\">Using <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">NgForm</a></code> with template variables<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#using-ngform-with-template-variables\"><i class=\"material-icons\">link</i></a></h3>\n<p>In most cases, Angular sets the template variable's value to the element on which it occurs.\nIn the previous example, <code>phone</code> refers to the phone number <code><input></code>.\nThe button's click handler passes the <code><input></code> value to the component's <code>callPhone()</code> method.</p>\n<p>The <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">NgForm</a></code> directive demonstrates getting a reference to a different value by reference a directive's <code>exportAs</code> name.\nIn the following example, the template variable, <code>itemForm</code>, appears three times separated by HTML.</p>\n<code-example path=\"template-reference-variables/src/app/app.component.html\" region=\"ngForm\" header=\"src/app/hero-form.component.html\">\n<form #itemForm=\"<a href=\"api/forms/NgForm\" class=\"code-anchor\">ngForm</a>\" (ngSubmit)=\"onSubmit(itemForm)\">\n <label for=\"name\">Name <input class=\"form-control\" name=\"name\" <a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a> required />\n </label>\n <button type=\"submit\">Submit</button>\n</form>\n\n<div [hidden]=\"!itemForm.form.valid\">\n <p>{{ submitMessage }}</p>\n</div>\n\n\n</code-example>\n<p>Without the <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">ngForm</a></code> attribute value, the reference value of <code>itemForm</code> would be\nthe <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement\">HTMLFormElement</a>, <code><form></code>.\nThere is, however, a difference between a <code><a href=\"api/core/Component\" class=\"code-anchor\">Component</a></code> and a <code><a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a></code> in that Angular references a <code><a href=\"api/core/Component\" class=\"code-anchor\">Component</a></code> without specifying the attribute value, and a <code><a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a></code> does not change the implicit reference, or the element.</p>\n<!-- What is the train of thought from talking about a form element to the difference between a component and a directive? Why is the component directive conversation relevant here? -kw -->\n<p>With <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">NgForm</a></code>, <code>itemForm</code> is a reference to the <a href=\"api/forms/NgForm\" title=\"API: NgForm\">NgForm</a> directive with the ability to track the value and validity of every control in the form.</p>\n<p>Unlike the native <code><form></code> element, the <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">NgForm</a></code> directive has a <code>form</code> property.\nThe <code><a href=\"api/forms/NgForm\" class=\"code-anchor\">NgForm</a></code> <code>form</code> property allows you to disable the submit button if the <code>itemForm.form.valid</code> is invalid.</p>\n<h2 id=\"template-variable-scope\">Template variable scope<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#template-variable-scope\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can refer to a template variable anywhere within its surrounding template.\n<a href=\"guide/built-in-directives\">Structural directives</a>, such as <code>*<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a></code> and <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code>, or <code><ng-template></code> act as a template boundary.\nYou cannot access template variables outside of these boundaries.</p>\n<div class=\"alert is-helpful\">\n<p>Define a variable only once in the template so the runtime value remains predictable.</p>\n</div>\n<h3 id=\"accessing-in-a-nested-template\">Accessing in a nested template<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#accessing-in-a-nested-template\"><i class=\"material-icons\">link</i></a></h3>\n<p>An inner template can access template variables that the outer template defines.</p>\n<p>In the following example, changing the text in the <code><input></code> changes the value in the <code><span></code> because Angular immediately updates changes through the template variable, <code>ref1</code>.</p>\n<code-example path=\"template-reference-variables/src/app/app.component.html\" region=\"template-ref-vars-scope1\" header=\"src/app/app.component.html\">\n<input #ref1 type=\"text\" [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"firstExample\" />\n<span *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"true\">Value: {{ ref1.value }}</span>\n\n</code-example>\n<p>In this case, there is an implied <code><ng-template></code> around the <code><span></code> and the definition of the variable is outside of it.\nAccessing a template variable from the parent template works because the child template inherits the context from the parent template.</p>\n<p>Rewriting the above code in a more verbose form explicitly shows the <code><ng-template></code>.</p>\n<code-example language=\"html\">\n<input #ref1 type=\"text\" [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"firstExample\" />\n\n<!-- New template -->\n<ng-template [<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>]=\"true\">\n <!-- Since the context is inherited, the value is available to the new template -->\n <span>Value: {{ ref1.value }}</span>\n</ng-template>\n</code-example>\n<p>However, accessing a template variable from outside the parent template doesn't work.</p>\n<code-example language=\"html\">\n <input *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"true\" #ref2 type=\"text\" [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"secondExample\" />\n <span>Value: {{ ref2?.value }}</span> <!-- doesn't work -->\n</code-example>\n<p>The verbose form shows that <code>ref2</code> is outside the parent template.</p>\n<code-example>\n<ng-template [<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>]=\"true\">\n <!-- The reference is defined within a template -->\n <input #ref2 type=\"text\" [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"secondExample\" />\n</ng-template>\n<!-- ref2 accessed from outside that template doesn't work -->\n<span>Value: {{ ref2?.value }}</span>\n</code-example>\n<p>Consider the following example that uses <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code>.</p>\n<code-example>\n<ng-container *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let i of [1,2]\">\n <input #ref type=\"text\" [value]=\"i\" />\n</ng-container>\n{{ ref.value }}\n</code-example>\n<p>Here, <code>ref.value</code> doesn't work.\nThe structural directive, <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> instantiates the template twice because <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> iterates over the two items in the array.\nIt is impossible to define what the <code>ref.value</code> reference signifies.</p>\n<p>With structural directives, such as <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> or <code>*<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a></code>, there is no way for Angular to know if a template is ever instantiated.</p>\n<p>As a result, Angular isn't able to access the value and returns an error.</p>\n<h3 id=\"accessing-a-template-variable-within-ng-template\">Accessing a template variable within <code><ng-template></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#accessing-a-template-variable-within-ng-template\"><i class=\"material-icons\">link</i></a></h3>\n<p>When you declare the variable on an <code><ng-template></code>, the variable refers to a <code><a href=\"api/core/TemplateRef\" class=\"code-anchor\">TemplateRef</a></code> instance, which represents the template.</p>\n<code-example path=\"template-reference-variables/src/app/app.component.html\" region=\"template-ref\" header=\"src/app/app.component.html\">\n<ng-template #ref3></ng-template>\n<button (click)=\"log(ref3)\">Log type of #ref</button>\n\n</code-example>\n<p>In this example, clicking the button calls the <code>log()</code> function, which outputs the value of <code>#ref3</code> to the console.\nBecause the <code>#ref</code> variable is on an <code><ng-template></code>, the value is <code><a href=\"api/core/TemplateRef\" class=\"code-anchor\">TemplateRef</a></code>.</p>\n<p>The following is the expanded browser console output of the <code><a href=\"api/core/TemplateRef\" class=\"code-anchor\">TemplateRef</a>()</code> function with the name of <code><a href=\"api/core/TemplateRef\" class=\"code-anchor\">TemplateRef</a></code>.</p>\n<code-example language=\"sh\">\n\n▼ ƒ TemplateRef()\nname: \"TemplateRef\"\n__proto__: Function\n\n</code-example>\n<a id=\"template-input-variable\"></a>\n<a id=\"template-input-variables\"></a>\n<h2 id=\"template-input-variable\">Template input variable<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/template-reference-variables#template-input-variable\"><i class=\"material-icons\">link</i></a></h2>\n<p>A <em>template input variable</em> is a variable you can reference within a single instance of the template.\nYou declare a template input variable using the <code>let</code> keyword as in <code>let hero</code>.</p>\n<p>There are several such variables in this example: <code>hero</code>, <code>i</code>, and <code>odd</code>.</p>\n<p>The variable's scope is limited to a single instance of the repeated template.\nYou can use the same variable name again in the definition of other structural directives.</p>\n<p>In contrast, you declare a template variable by prefixing the variable name with <code>#</code>, as in <code>#var</code>.\nA template variable refers to its attached element, component, or directive.</p>\n<p>Template input variables and template variables names have their own namespaces.\nThe template input variable <code>hero</code> in <code>let hero</code> is distinct from the template variable <code>hero</code> in <code>#hero</code>.</p>\n\n \n</div>\n\n<!-- links to this doc:\n - api/common/NgForOf\n - guide/example-apps-list\n - guide/forms\n - guide/glossary\n - guide/inputs-outputs\n - guide/interpolation\n - guide/template-statements\n - guide/template-syntax\n - guide/user-input\n-->\n<!-- links from this doc:\n - api/common/NgForOf\n - api/common/NgIf\n - api/core/Component\n - api/core/Directive\n - api/core/TemplateRef\n - api/forms/NgForm\n - api/forms/NgModel\n - guide/built-in-directives\n - guide/structural-directives\n - guide/structural-directives#asterisk\n - guide/template-reference-variables#accessing-a-template-variable-within-ng-template\n - guide/template-reference-variables#accessing-in-a-nested-template\n - guide/template-reference-variables#how-angular-assigns-values-to-template-variables\n - guide/template-reference-variables#syntax\n - guide/template-reference-variables#template-input-variable\n - guide/template-reference-variables#template-variable-scope\n - guide/template-reference-variables#template-variables\n - guide/template-reference-variables#using-ngform-with-template-variables\n - https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement\n - https://developer.mozilla.org/en-US/docs/Web/Web_Components\n - https://github.com/angular/angular/edit/master/aio/content/guide/template-reference-variables.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |