5 lines
38 KiB
JSON
5 lines
38 KiB
JSON
{
|
|
"id": "guide/built-in-directives",
|
|
"title": "Built-in directives",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/built-in-directives.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=\"built-in-directives\">Built-in directives<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#built-in-directives\"><i class=\"material-icons\">link</i></a></h1>\n<p>Directives are classes that add additional behavior to elements\nin your Angular applications.\nWith Angular's built-in directives, you can manage forms, lists, styles, and what users see.</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<p>The different types of Angular directives are as follows:</p>\n<ol>\n<li><a href=\"guide/component-overview\">Components</a>—directives with a template.\nThis type of directive is the most common directive type.</li>\n<li><a href=\"guide/built-in-directives#built-in-attribute-directives\">Attribute directives</a>—directives that change the appearance or behavior of an element, component, or another directive.</li>\n<li><a href=\"guide/built-in-directives#built-in-structural-directives\">Structural directives</a>—directives that change the DOM layout by adding and removing DOM elements.</li>\n</ol>\n<p>This guide covers built-in <a href=\"guide/built-in-directives#built-in-attribute-directives\">attribute directives</a> and <a href=\"guide/built-in-directives#built-in-structural-directives\">structural directives</a>.</p>\n<a id=\"attribute-directives\"></a>\n<h2 id=\"built-in-attribute-directives\">Built-in attribute directives<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#built-in-attribute-directives\"><i class=\"material-icons\">link</i></a></h2>\n<p>Attribute directives listen to and modify the behavior of other HTML elements, attributes, properties, and components.</p>\n<p>Many NgModules such as the <a href=\"guide/router\" title=\"Routing and Navigation\"><code>RouterModule</code></a> and the <a href=\"guide/forms\" title=\"Forms\"><code>FormsModule</code></a> define their own attribute directives.\nThe most common attribute directives are as follows:</p>\n<ul>\n<li><a href=\"guide/built-in-directives#ngClass\"><code>NgClass</code></a>—adds and removes a set of CSS classes.</li>\n<li><a href=\"guide/built-in-directives#ngstyle\"><code>NgStyle</code></a>—adds and removes a set of HTML styles.</li>\n<li><a href=\"guide/built-in-directives#ngModel\"><code>NgModel</code></a>—adds two-way data binding to an HTML form element.</li>\n</ul>\n<a id=\"ngClass\"></a>\n<h2 id=\"adding-and-removing-classes-with-ngclass\">Adding and removing classes with <code><a href=\"api/common/NgClass\" class=\"code-anchor\">NgClass</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#adding-and-removing-classes-with-ngclass\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can add or remove multiple CSS classes simultaneously with <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code>.</p>\n<div class=\"alert is-helpful\">\n<p>To add or remove a <em>single</em> class, use <a href=\"guide/attribute-binding#class-binding\">class binding</a> rather than <code><a href=\"api/common/NgClass\" class=\"code-anchor\">NgClass</a></code>.</p>\n</div>\n<h3 id=\"using-ngclass-with-an-expression\">Using <code><a href=\"api/common/NgClass\" class=\"code-anchor\">NgClass</a></code> with an expression<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#using-ngclass-with-an-expression\"><i class=\"material-icons\">link</i></a></h3>\n<p>On the element you'd like to style, add <code>[<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]</code> and set it equal to an expression.\nIn this case, <code>isSpecial</code> is a boolean set to <code>true</code> in <code>app.component.ts</code>.\nBecause <code>isSpecial</code> is true, <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code> applies the class of <code>special</code> to the <code><div></code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"special-div\" header=\"src/app/app.component.html\">\n<!-- toggle the \"special\" class on/off with a property -->\n<div [<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]=\"isSpecial ? 'special' : ''\">This div is special</div>\n\n</code-example>\n<h3 id=\"using-ngclass-with-a-method\">Using <code><a href=\"api/common/NgClass\" class=\"code-anchor\">NgClass</a></code> with a method<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#using-ngclass-with-a-method\"><i class=\"material-icons\">link</i></a></h3>\n<ol>\n<li>\n<p>To use <code><a href=\"api/common/NgClass\" class=\"code-anchor\">NgClass</a></code> with a method, add the method to the component class.\nIn the following example, <code>setCurrentClasses()</code> sets the property <code>currentClasses</code> with an object that adds or removes three classes based on the <code>true</code> or <code>false</code> state of three other component properties.</p>\n<p>Each key of the object is a CSS class name.\nIf a key is <code>true</code>, <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code> adds the class.\nIf a key is <code>false</code>, <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code> removes the class.</p>\n<code-example path=\"built-in-directives/src/app/app.component.ts\" region=\"setClasses\" header=\"src/app/app.component.ts\">\n currentClasses: {};\n/* . . . */\n setCurrentClasses() {\n // CSS classes: added/removed per current <a href=\"api/animations/state\" class=\"code-anchor\">state</a> of component properties\n this.currentClasses = {\n saveable: this.canSave,\n modified: !this.isUnchanged,\n special: this.isSpecial\n };\n }\n\n</code-example>\n</li>\n<li>\n<p>In the template, add the <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code> property binding to <code>currentClasses</code> to set the element's classes:</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgClass-1\" header=\"src/app/app.component.html\">\n<div [<a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a>]=\"currentClasses\">This div is initially saveable, unchanged, and special.</div>\n\n</code-example>\n</li>\n</ol>\n<p>For this use case, Angular applies the classes on initialization and in case of changes.\nThe full example calls <code>setCurrentClasses()</code> initially with <code>ngOnInit()</code> and when the dependent properties change through a button click.\nThese steps are not necessary to implement <code><a href=\"api/common/NgClass\" class=\"code-anchor\">ngClass</a></code>.\nFor more information, see the <live-example></live-example> <code>app.component.ts</code> and <code>app.component.html</code>.</p>\n<a id=\"ngstyle\"></a>\n<h2 id=\"setting-inline-styles-with-ngstyle\">Setting inline styles with <code><a href=\"api/common/NgStyle\" class=\"code-anchor\">NgStyle</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#setting-inline-styles-with-ngstyle\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can use <code><a href=\"api/common/NgStyle\" class=\"code-anchor\">NgStyle</a></code> to set multiple inline styles simultaneously, based on the state of the component.</p>\n<ol>\n<li>\n<p>To use <code><a href=\"api/common/NgStyle\" class=\"code-anchor\">NgStyle</a></code>, add a method to the component class.</p>\n<p>In the following example, <code>setCurrentStyles()</code> sets the property <code>currentStyles</code> with an object that defines three styles, based on the state of three other component properties.</p>\n<code-example path=\"built-in-directives/src/app/app.component.ts\" region=\"setStyles\" header=\"src/app/app.component.ts\">\n currentStyles: {};\n/* . . . */\n setCurrentStyles() {\n // CSS styles: set per current <a href=\"api/animations/state\" class=\"code-anchor\">state</a> of component properties\n this.currentStyles = {\n 'font-style': this.canSave ? 'italic' : 'normal',\n 'font-weight': !this.isUnchanged ? 'bold' : 'normal',\n 'font-size': this.isSpecial ? '24px' : '12px'\n };\n }\n\n</code-example>\n</li>\n<li>\n<p>To set the element's styles, add an <code><a href=\"api/common/NgStyle\" class=\"code-anchor\">ngStyle</a></code> property binding to <code>currentStyles</code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgStyle-2\" header=\"src/app/app.component.html\">\n<div [<a href=\"api/common/NgStyle\" class=\"code-anchor\">ngStyle</a>]=\"currentStyles\">\n This div is initially italic, normal weight, and extra large (24px).\n</div>\n\n</code-example>\n</li>\n</ol>\n<p>For this use case, Angular applies the styles upon initialization and in case of changes.\nTo do this, the full example calls <code>setCurrentStyles()</code> initially with <code>ngOnInit()</code> and when the dependent properties change through a button click.\nHowever, these steps are not necessary to implement <code><a href=\"api/common/NgStyle\" class=\"code-anchor\">ngStyle</a></code> on its own.\nSee the <live-example></live-example> <code>app.component.ts</code> and <code>app.component.html</code> for this optional implementation.</p>\n<a id=\"ngModel\"></a>\n<h2 id=\"displaying-and-updating-properties-with-ngmodel\">Displaying and updating properties with <code><a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#displaying-and-updating-properties-with-ngmodel\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can use the <code><a href=\"api/forms/NgModel\" class=\"code-anchor\">NgModel</a></code> directive to display a data property and update that property when the user makes changes.</p>\n<ol>\n<li>\n<p>Import <code><a href=\"api/forms/FormsModule\" class=\"code-anchor\">FormsModule</a></code> and add it to the NgModule's <code>imports</code> list.</p>\n<code-example path=\"built-in-directives/src/app/app.module.ts\" header=\"src/app/app.module.ts (FormsModule import)\" region=\"import-forms-module\">\nimport { <a href=\"api/forms/FormsModule\" class=\"code-anchor\">FormsModule</a> } from '@angular/forms'; // <--- JavaScript import from Angular\n/* . . . */\n@<a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a>({\n/* . . . */\n\n imports: [\n <a href=\"api/platform-browser/BrowserModule\" class=\"code-anchor\">BrowserModule</a>,\n <a href=\"api/forms/FormsModule\" class=\"code-anchor\">FormsModule</a> // <--- import into the <a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a>\n ],\n/* . . . */\n})\nexport class AppModule { }\n\n</code-example>\n</li>\n<li>\n<p>Add an <code>[(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]</code> binding on an HTML <code><form></code> element and set it equal to the property, here <code>name</code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" header=\"src/app/app.component.html (NgModel example)\" region=\"NgModel-1\">\n<label for=\"example-ngModel\">[(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]:</label>\n<input [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"currentItem.name\" id=\"example-ngModel\">\n\n</code-example>\n<p>This <code>[(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]</code> syntax can only set a data-bound property.</p>\n</li>\n</ol>\n<p>To customize your configuration, you can write the expanded form, which separates the property and event binding.\nUse <a href=\"guide/property-binding\">property binding</a> to set the property and <a href=\"guide/event-binding\">event binding</a> to respond to changes.\nThe following example changes the <code><input></code> value to uppercase:</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"uppercase\" header=\"src/app/app.component.html\">\n<input [<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>]=\"currentItem.name\" (ngModelChange)=\"setUppercaseName($event)\" id=\"example-uppercase\">\n\n</code-example>\n<p>Here are all variations in action, including the uppercase version:</p>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/built-in-directives/ng-model-anim.gif\" alt=\"NgModel variations\" width=\"540\" height=\"264\">\n</div>\n<h3 id=\"ngmodel-and-value-accessors\"><code><a href=\"api/forms/NgModel\" class=\"code-anchor\">NgModel</a></code> and value accessors<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#ngmodel-and-value-accessors\"><i class=\"material-icons\">link</i></a></h3>\n<p>The <code><a href=\"api/forms/NgModel\" class=\"code-anchor\">NgModel</a></code> directive works for an element supported by a <a href=\"api/forms/ControlValueAccessor\">ControlValueAccessor</a>.\nAngular provides <em>value accessors</em> for all of the basic HTML form elements.\nFor more information, see <a href=\"guide/forms\">Forms</a>.</p>\n<p>To apply <code>[(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]</code> to a non-form native element or a third-party custom component, you have to write a value accessor.\nFor more information, see the API documentation on <a href=\"api/forms/DefaultValueAccessor\">DefaultValueAccessor</a>.</p>\n<div class=\"alert is-helpful\">\n<p>When you write an Angular component, you don't need a value accessor or <code><a href=\"api/forms/NgModel\" class=\"code-anchor\">NgModel</a></code> if you name the value and event properties according to Angular's <a href=\"guide/two-way-binding#how-two-way-binding-works\">two-way binding syntax</a>.</p>\n</div>\n<a id=\"structural-directives\"></a>\n<h2 id=\"built-in-structural-directives\">Built-in structural directives<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#built-in-structural-directives\"><i class=\"material-icons\">link</i></a></h2>\n<p>Structural directives are responsible for HTML layout.\nThey shape or reshape the DOM's structure, typically by adding, removing, and manipulating the host elements to which they are attached.</p>\n<p>This section introduces the most common built-in structural directives:</p>\n<ul>\n<li><a href=\"guide/built-in-directives#ngIf\"><code>NgIf</code></a>—conditionally creates or disposes of subviews from the template.</li>\n<li><a href=\"guide/built-in-directives#ngFor\"><code>NgFor</code></a>—repeat a node for each item in a list.</li>\n<li><a href=\"guide/built-in-directives#ngSwitch\"><code>NgSwitch</code></a>—a set of directives that switch among alternative views.</li>\n</ul>\n<p>For more information, see <a href=\"guide/structural-directives\">Structural Directives</a>.</p>\n<a id=\"ngIf\"></a>\n<h2 id=\"adding-or-removing-an-element-with-ngif\">Adding or removing an element with <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#adding-or-removing-an-element-with-ngif\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can add or remove an element by applying an <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> directive to a host element.</p>\n<p>When <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> is <code>false</code>, Angular removes an element and its descendants from the DOM.\nAngular then disposes of their components, which frees up memory and resources.</p>\n<p>To add or remove an element, bind <code>*<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a></code> to a condition expression such as <code>isActive</code> in the following example.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgIf-1\" header=\"src/app/app.component.html\">\n<app-item-detail *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"isActive\" [item]=\"item\"></app-item-detail>\n\n</code-example>\n<p>When the <code>isActive</code> expression returns a truthy value, <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> adds the <code>ItemDetailComponent</code> to the DOM.\nWhen the expression is falsy, <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> removes the <code>ItemDetailComponent</code> from the DOM and disposes of the component and all of its sub-components.</p>\n<p>For more information on <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> and <code>NgIfElse</code>, see the <a href=\"api/common/NgIf\">NgIf API documentation</a>.</p>\n<h3 id=\"guarding-against-null\">Guarding against <code>null</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#guarding-against-null\"><i class=\"material-icons\">link</i></a></h3>\n<p>By default, <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> prevents display of an element bound to a null value.</p>\n<p>To use <code><a href=\"api/common/NgIf\" class=\"code-anchor\">NgIf</a></code> to guard a <code><div></code>, add <code>*<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"yourProperty\"</code> to the <code><div></code>.\nIn the following example, the <code>currentCustomer</code> name appears because there is a <code>currentCustomer</code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgIf-2\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"currentCustomer\">Hello, {{currentCustomer.name}}</div>\n\n</code-example>\n<p>However, if the property is <code>null</code>, Angular does not display the <code><div></code>.\nIn this example, Angular does not display the <code>nullCustomer</code> because it is <code>null</code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgIf-2b\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"nullCustomer\">Hello, <span>{{nullCustomer}}</span></div>\n\n</code-example>\n<a id=\"ngFor\"></a>\n<h2 id=\"listing-items-with-ngfor\">Listing items with <code>NgFor</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#listing-items-with-ngfor\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can use the <code>NgFor</code> directive to present a list of items.</p>\n<ol>\n<li>\n<p>Define a block of HTML that determines how Angular renders a single item.</p>\n</li>\n<li>\n<p>To list your items, assign the short hand <code>let item of items</code> to <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code>.</p>\n</li>\n</ol>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgFor-1\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items\">{{item.name}}</div>\n\n</code-example>\n<p>The string <code>\"let item of items\"</code> instructs Angular to do the following:</p>\n<ul>\n<li>Store each item in the <code>items</code> array in the local <code>item</code> looping variable</li>\n<li>Make each item available to the templated HTML for each iteration</li>\n<li>Translate <code>\"let item of items\"</code> into an <code><ng-template></code> around the host element</li>\n<li>Repeat the <code><ng-template></code> for each <code>item</code> in the list</li>\n</ul>\n<p>For more information see the <a href=\"guide/structural-directives#shorthand\">Structural directive shorthand</a> section of <a href=\"guide/structural-directives\">Structural directives</a>.</p>\n<h3 id=\"repeating-a-component-view\">Repeating a component view<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#repeating-a-component-view\"><i class=\"material-icons\">link</i></a></h3>\n<p>To repeat a component element, apply <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> to the selector.\nIn the following example, the selector is <code><app-item-detail></code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgFor-2\" header=\"src/app/app.component.html\">\n<app-item-detail *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items\" [item]=\"item\"></app-item-detail>\n\n</code-example>\n<p>You can reference a template input variable, such as <code>item</code>, in the following locations:</p>\n<ul>\n<li>within the <code><a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> host element</li>\n<li>within the host element descendants to access the item's properties</li>\n</ul>\n<p>The following example references <code>item</code> first in an interpolation and then passes in a binding to the <code>item</code> property of the <code><app-item-detail></code> component.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgFor-1-2\" header=\"src/app/app.component.html\">\n <div *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items\">{{item.name}}</div>\n<!-- . . . -->\n <app-item-detail *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items\" [item]=\"item\"></app-item-detail>\n\n</code-example>\n<p>For more information about template input variables, see <a href=\"guide/structural-directives#shorthand\">Structural directive shorthand</a>.</p>\n<h3 id=\"getting-the-index-of-ngfor\">Getting the <code>index</code> of <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#getting-the-index-of-ngfor\"><i class=\"material-icons\">link</i></a></h3>\n<p>You can get the <code>index</code> of <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> in a template input variable and use it in the template.</p>\n<p>In the <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code>, add a semicolon and <code>let i=index</code> to the short hand.\nThe following example gets the <code>index</code> in a variable named <code>i</code> and displays it with the item name.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgFor-3\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items; let i=index\">{{i + 1}} - {{item.name}}</div>\n\n</code-example>\n<p>The index property of the <code>NgFor</code> directive context returns the zero-based index of the item in each iteration.</p>\n<p>Angular translates this instruction into an <code><ng-template></code> around the host element,\nthen uses this template repeatedly to create a new set of elements and bindings for each <code>item</code>\nin the list.\nFor more information about shorthand, see the <a href=\"guide/structural-directives#shorthand\">Structural Directives</a> guide.</p>\n<a id=\"one-per-element\"></a>\n<h2 id=\"repeating-elements-when-a-condition-is-true\">Repeating elements when a condition is true<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#repeating-elements-when-a-condition-is-true\"><i class=\"material-icons\">link</i></a></h2>\n<p>To repeat a block of HTML when a particular condition is true, put the <code>*<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a></code> on a container element that wraps an <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> element.\nOne or both elements can be an <code><ng-container></code> so you don't have to introduce extra levels of HTML.</p>\n<p>Because structural directives add and remove nodes from the DOM, apply only one structural directive per element.</p>\n<p>For more information about <code>NgFor</code> see the <a href=\"api/common/NgForOf\">NgForOf API reference</a>.</p>\n<a id=\"ngfor-with-trackby\"></a>\n<h3 id=\"tracking-items-with-ngfor-trackby\">Tracking items with <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> <code>trackBy</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#tracking-items-with-ngfor-trackby\"><i class=\"material-icons\">link</i></a></h3>\n<p>By tracking changes to an item list, you can reduce the number of calls your application makes to the server.\nWith the <code>*<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a></code> <code>trackBy</code> property, Angular can change and re-render only those items that have changed, rather than reloading the entire list of items.</p>\n<ol>\n<li>\n<p>Add a method to the component that returns the value <code>NgFor</code> should track.\nIn this example, the value to track is the item's <code>id</code>.\nIf the browser has already rendered <code>id</code>, Angular keeps track of it and doesn't re-query the server for the same <code>id</code>.</p>\n<code-example path=\"built-in-directives/src/app/app.component.ts\" region=\"trackByItems\" header=\"src/app/app.component.ts\">\ntrackByItems(index: number, item: Item): number { return item.id; }\n\n</code-example>\n</li>\n<li>\n<p>In the short hand expression, set <code>trackBy</code> to the <code>trackByItems()</code> method.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"trackBy\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let item of items; trackBy: trackByItems\">\n ({{item.id}}) {{item.name}}\n</div>\n\n</code-example>\n</li>\n</ol>\n<p><strong>Change ids</strong> creates new items with new <code>item.id</code>s.\nIn the following illustration of the <code>trackBy</code> effect, <strong>Reset items</strong> creates new items with the same <code>item.id</code>s.</p>\n<ul>\n<li>With no <code>trackBy</code>, both buttons trigger complete DOM element replacement.</li>\n<li>With <code>trackBy</code>, only changing the <code>id</code> triggers element replacement.</li>\n</ul>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/built-in-directives/ngfor-trackby.gif\" alt=\"Animation of trackBy\" width=\"492\" height=\"442\">\n</div>\n<div class=\"alert is-helpful\">\n<p>Built-in directives use only public APIs.\nThey do not have special access to any private APIs that other directives can't access.</p>\n</div>\n<a id=\"ngcontainer\"></a>\n<h2 id=\"hosting-a-directive-without-a-dom-element\">Hosting a directive without a DOM element<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#hosting-a-directive-without-a-dom-element\"><i class=\"material-icons\">link</i></a></h2>\n<p>The Angular <code><ng-container></code> is a grouping element that doesn't interfere with styles or layout because Angular doesn't put it in the DOM.</p>\n<p>You can use <code><ng-container></code> when there's no single element to host the directive.</p>\n<p>Here's a conditional paragraph using <code><ng-container></code>.</p>\n<code-example path=\"structural-directives/src/app/app.component.html\" header=\"src/app/app.component.html (ngif-ngcontainer)\" region=\"ngif-ngcontainer\">\n<p>\n I turned the corner\n <ng-container *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"hero\">\n and saw {{hero.name}}. I waved\n </ng-container>\n and continued on my way.\n</p>\n\n</code-example>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/structural-directives/good-paragraph.png\" alt=\"ngcontainer paragraph with proper style\" width=\"509\" height=\"15\">\n</div>\n<ol>\n<li>\n<p>Import the <code><a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a></code> directive from <code><a href=\"api/forms/FormsModule\" class=\"code-anchor\">FormsModule</a></code>.</p>\n</li>\n<li>\n<p>Add <code><a href=\"api/forms/FormsModule\" class=\"code-anchor\">FormsModule</a></code> to the imports section of the relevant Angular module.</p>\n</li>\n<li>\n<p>To conditionally exclude an <code><option></code>, wrap the <code><option></code> in an <code><ng-container></code>.</p>\n<code-example path=\"structural-directives/src/app/app.component.html\" header=\"src/app/app.component.html (select-ngcontainer)\" region=\"select-ngcontainer\">\n<div>\n Pick your favorite hero\n (<label><input type=\"checkbox\" checked (change)=\"showSad = !showSad\">show sad</label>)\n</div>\n<select [(<a href=\"api/forms/NgModel\" class=\"code-anchor\">ngModel</a>)]=\"hero\">\n <ng-container *<a href=\"api/common/NgForOf\" class=\"code-anchor\">ngFor</a>=\"let h of heroes\">\n <ng-container *<a href=\"api/common/NgIf\" class=\"code-anchor\">ngIf</a>=\"showSad || h.emotion !== 'sad'\">\n <option [ngValue]=\"h\">{{h.name}} ({{h.emotion}})</option>\n </ng-container>\n </ng-container>\n</select>\n\n</code-example>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/structural-directives/select-ngcontainer-anim.gif\" alt=\"ngcontainer options work properly\" width=\"312\" height=\"100\">\n</div>\n</li>\n</ol>\n<a id=\"ngSwitch\"></a>\n<h2 id=\"switching-cases-with-ngswitch\">Switching cases with <code><a href=\"api/common/NgSwitch\" class=\"code-anchor\">NgSwitch</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#switching-cases-with-ngswitch\"><i class=\"material-icons\">link</i></a></h2>\n<p>Like the JavaScript <code>switch</code> statement, <code><a href=\"api/common/NgSwitch\" class=\"code-anchor\">NgSwitch</a></code> displays one element from among several possible elements, based on a switch condition.\nAngular puts only the selected element into the DOM.</p>\n<!-- API Flagged -->\n<p><code><a href=\"api/common/NgSwitch\" class=\"code-anchor\">NgSwitch</a></code> is a set of three directives:</p>\n<ul>\n<li><code><a href=\"api/common/NgSwitch\" class=\"code-anchor\">NgSwitch</a></code>—an attribute directive that changes the behavior of its companion directives.</li>\n<li><code><a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">NgSwitchCase</a></code>—structural directive that adds its element to the DOM when its bound value equals the switch value and removes its bound value when it doesn't equal the switch value.</li>\n<li><code><a href=\"api/common/NgSwitchDefault\" class=\"code-anchor\">NgSwitchDefault</a></code>—structural directive that adds its element to the DOM when there is no selected <code><a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">NgSwitchCase</a></code>.</li>\n</ul>\n<ol>\n<li>\n<p>On an element, such as a <code><div></code>, add <code>[<a href=\"api/common/NgSwitch\" class=\"code-anchor\">ngSwitch</a>]</code> bound to an expression that returns the switch value, such as <code>feature</code>.\nThough the <code>feature</code> value in this example is a string, the switch value can be of any type.</p>\n</li>\n<li>\n<p>Bind to <code>*<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a></code> and <code>*<a href=\"api/common/NgSwitchDefault\" class=\"code-anchor\">ngSwitchDefault</a></code> on the elements for the cases.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgSwitch\" header=\"src/app/app.component.html\">\n<div [<a href=\"api/common/NgSwitch\" class=\"code-anchor\">ngSwitch</a>]=\"currentItem.feature\">\n <app-stout-item *<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a>=\"'stout'\" [item]=\"currentItem\"></app-stout-item>\n <app-device-item *<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a>=\"'slim'\" [item]=\"currentItem\"></app-device-item>\n <app-lost-item *<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a>=\"'vintage'\" [item]=\"currentItem\"></app-lost-item>\n <app-best-item *<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a>=\"'bright'\" [item]=\"currentItem\"></app-best-item>\n<!-- . . . -->\n <app-unknown-item *<a href=\"api/common/NgSwitchDefault\" class=\"code-anchor\">ngSwitchDefault</a> [item]=\"currentItem\"></app-unknown-item>\n</div>\n\n</code-example>\n</li>\n<li>\n<p>In the parent component, define <code>currentItem</code> so you can use it in the <code>[<a href=\"api/common/NgSwitch\" class=\"code-anchor\">ngSwitch</a>]</code> expression.</p>\n<code-example path=\"built-in-directives/src/app/app.component.ts\" region=\"item\" header=\"src/app/app.component.ts\">\ncurrentItem: Item;\n\n</code-example>\n</li>\n<li>\n<p>In each child component, add an <code>item</code> <a href=\"guide/inputs-outputs#input\" title=\"Input property\">input property</a> which is bound to the <code>currentItem</code> of the parent component.\nThe following two snippets show the parent component and one of the child components.\nThe other child components are identical to <code>StoutItemComponent</code>.</p>\n<code-example path=\"built-in-directives/src/app/item-switch.component.ts\" region=\"input\" header=\"In each child component, here StoutItemComponent\">\nexport class StoutItemComponent {\n @<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>() item: Item;\n}\n\n</code-example>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/built-in-directives/ngswitch.gif\" alt=\"Animation of NgSwitch\" width=\"370\" height=\"256\">\n</div>\n</li>\n</ol>\n<p>Switch directives also work with native HTML elements and web components.\nFor example, you could replace the <code><app-best-item></code> switch case with a <code><div></code> as follows.</p>\n<code-example path=\"built-in-directives/src/app/app.component.html\" region=\"NgSwitch-div\" header=\"src/app/app.component.html\">\n<div *<a href=\"api/common/NgSwitchCase\" class=\"code-anchor\">ngSwitchCase</a>=\"'bright'\"> Are you as bright as {{currentItem.name}}?</div>\n\n</code-example>\n<h2 id=\"whats-next\">What's next<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/built-in-directives#whats-next\"><i class=\"material-icons\">link</i></a></h2>\n<p>For information on how to build your own custom directives, see <a href=\"guide/attribute-directives\">Attribute Directives</a> and <a href=\"guide/structural-directives\">Structural Directives</a>.</p>\n\n \n</div>\n\n<!-- links to this doc:\n - api/common/NgForOf\n - guide/ajs-quick-reference\n - guide/architecture-components\n - guide/event-binding\n - guide/example-apps-list\n - guide/glossary\n - guide/interpolation\n - guide/structural-directives\n - guide/template-reference-variables\n - guide/template-syntax\n - guide/two-way-binding\n - guide/upgrade\n - guide/what-is-angular\n - tutorial/toh-pt2\n-->\n<!-- links from this doc:\n - api/animations/state\n - api/common/NgClass\n - api/common/NgForOf\n - api/common/NgIf\n - api/common/NgStyle\n - api/common/NgSwitch\n - api/common/NgSwitchCase\n - api/common/NgSwitchDefault\n - api/core/Input\n - api/core/NgModule\n - api/forms/ControlValueAccessor\n - api/forms/DefaultValueAccessor\n - api/forms/FormsModule\n - api/forms/NgModel\n - api/platform-browser/BrowserModule\n - guide/attribute-binding#class-binding\n - guide/attribute-directives\n - guide/built-in-directives#adding-and-removing-classes-with-ngclass\n - guide/built-in-directives#adding-or-removing-an-element-with-ngif\n - guide/built-in-directives#built-in-attribute-directives\n - guide/built-in-directives#built-in-directives\n - guide/built-in-directives#built-in-structural-directives\n - guide/built-in-directives#displaying-and-updating-properties-with-ngmodel\n - guide/built-in-directives#getting-the-index-of-ngfor\n - guide/built-in-directives#guarding-against-null\n - guide/built-in-directives#hosting-a-directive-without-a-dom-element\n - guide/built-in-directives#listing-items-with-ngfor\n - guide/built-in-directives#ngClass\n - guide/built-in-directives#ngFor\n - guide/built-in-directives#ngIf\n - guide/built-in-directives#ngModel\n - guide/built-in-directives#ngSwitch\n - guide/built-in-directives#ngmodel-and-value-accessors\n - guide/built-in-directives#ngstyle\n - guide/built-in-directives#repeating-a-component-view\n - guide/built-in-directives#repeating-elements-when-a-condition-is-true\n - guide/built-in-directives#setting-inline-styles-with-ngstyle\n - guide/built-in-directives#switching-cases-with-ngswitch\n - guide/built-in-directives#tracking-items-with-ngfor-trackby\n - guide/built-in-directives#using-ngclass-with-a-method\n - guide/built-in-directives#using-ngclass-with-an-expression\n - guide/built-in-directives#whats-next\n - guide/component-overview\n - guide/event-binding\n - guide/forms\n - guide/inputs-outputs#input\n - guide/property-binding\n - guide/router\n - guide/structural-directives\n - guide/structural-directives#shorthand\n - guide/two-way-binding#how-two-way-binding-works\n - https://github.com/angular/angular/edit/master/aio/content/guide/built-in-directives.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |