内置指令link

Built-in directiveslink

Angular 提供了两种内置指令属性型指令和结构型指令。

Angular offers two kinds of built-in directives: attribute directives and structural directives.

欲知详情，包括如何构建你自己的自定义指令，请参阅属性型指令和结构型指令。

For more detail, including how to build your own custom directives, see Attribute Directives and Structural Directives.

内置属性型指令link

Built-in attribute directiveslink

属性型指令会监听并修改其它 HTML 元素和组件的行为、Attribute 和 Property。 它们通常被应用在元素上，就好像它们是 HTML 属性一样，因此得名属性型指令。

Attribute directives listen to and modify the behavior of other HTML elements, attributes, properties, and components. You usually apply them to elements as if they were HTML attributes, hence the name.

许多 NgModule（例如 RouterModule和 FormsModule都定义了自己的属性型指令。最常见的属性型指令如下：

Many NgModules such as the RouterModuleand the FormsModuledefine their own attribute directives. The most common attribute directives are as follows:

• NgClass—— 添加和删除一组 CSS 类。

  NgClass—adds and removes a set of CSS classes.

• NgStyle—— 添加和删除一组 HTML 样式。

  NgStyle—adds and removes a set of HTML styles.

• NgModel—— 将数据双向绑定添加到 HTML 表单元素。

  NgModel—adds two-way data binding to an HTML form element.

NgClasslink

用 ngClass 同时添加或删除几个 CSS 类。

Add or remove several CSS classes simultaneously with ngClass.

      
        content_copy
      
      <!-- toggle the "special" class on/off with a property -->
<div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>
    

考虑一个 setCurrentClasses() 组件方法，该方法设置一个组件属性 currentClasses，该对象具有一个根据其它三个组件属性的 true / false 状态来添加或删除三个 CSS 类的对象。该对象的每个键(key)都是一个 CSS 类名。如果要添加上该类，则其值为 true，反之则为 false。

Consider a setCurrentClasses() component method that sets a component property, currentClasses, with an object that adds or removes three classes based on the true/false state of three other component properties. Each key of the object is a CSS class name; its value is true if the class should be added, false if it should be removed.

      
        content_copy
      
      currentClasses: {};
/* . . . */
  setCurrentClasses() {
    // CSS classes: added/removed per current state of component properties
    this.currentClasses =  {
      saveable: this.canSave,
      modified: !this.isUnchanged,
      special:  this.isSpecial
    };
  }
    

把 NgClass 属性绑定到 currentClasses，根据它来设置此元素的 CSS 类：

Adding an ngClass property binding to currentClasses sets the element's classes accordingly:

      
        content_copy
      
      <div [ngClass]="currentClasses">This div is initially saveable, unchanged, and special.</div>
    

NgStylelink

使用 NgStyle 根据组件的状态同时动态设置多个内联样式。

Use NgStyle to set many inline styles simultaneously and dynamically, based on the state of the component.

不用 NgStylelink

Without NgStylelink

有些情况下，要考虑使用样式绑定来设置单个样式值，而不使用 NgStyle。

For context, consider setting a single style value with style binding, without NgStyle.

      
        content_copy
      
      <div [style.font-size]="isSpecial ? 'x-large' : 'smaller'">
  This div is x-large or smaller.
</div>
    

但是，如果要同时设置多个内联样式，请使用 NgStyle 指令。

However, to set many inline styles at the same time, use the NgStyle directive.

下面的例子是一个 setCurrentStyles() 方法，它基于该组件另外三个属性的状态，用一个定义了三个样式的对象设置了 currentStyles 属性。

The following is a setCurrentStyles() method that sets a component property, currentStyles, with an object that defines three styles, based on the state of three other component properties:

      
        content_copy
      
      currentStyles: {};
/* . . . */
  setCurrentStyles() {
    // CSS styles: set per current state of component properties
    this.currentStyles = {
      'font-style':  this.canSave      ? 'italic' : 'normal',
      'font-weight': !this.isUnchanged ? 'bold'   : 'normal',
      'font-size':   this.isSpecial    ? '24px'   : '12px'
    };
  }
    

把 ngStyle 属性绑定到 currentStyles，来根据它设置此元素的样式：

Adding an ngStyle property binding to currentStyles sets the element's styles accordingly:

      
        content_copy
      
      <div [ngStyle]="currentStyles">
  This div is initially italic, normal weight, and extra large (24px).
</div>
    

[(ngModel)] ：双向绑定link

[(ngModel)]: Two-way bindinglink

NgModel 指令允许你显示数据属性并在用户进行更改时更新该属性。这是一个例子：

The NgModel directive allows you to display a data property and update that property when the user makes changes. Here's an example:

      
        content_copy
      
      <label for="example-ngModel">[(ngModel)]:</label>
<input [(ngModel)]="currentItem.name" id="example-ngModel">
    

导入 FormsModule 以使用 ngModellink

Import FormsModule to use ngModellink

要想在双向数据绑定中使用 ngModel 指令，必须先导入 FormsModule 并将其添加到 NgModule 的 imports 列表中。要了解关于 FormsModule 和 ngModel 的更多信息，参阅表单一章。

Before using the ngModel directive in a two-way data binding, you must import the FormsModule and add it to the NgModule's imports list. Learn more about the FormsModule and ngModel in Forms.

记住，要导入 FormsModule 才能让 [(ngModel)] 可用，如下所示：

Remember to import the FormsModule to make [(ngModel)] available as follows:

      
        content_copy
      
      import { FormsModule } from '@angular/forms'; // <--- JavaScript import from Angular
/* . . . */
@NgModule({
/* . . . */

  imports: [
    BrowserModule,
    FormsModule // <--- import into the NgModule
  ],
/* . . . */
})
export class AppModule { }
    

通过分别绑定到 <input> 元素的 value 属性和 input 事件，可以达到同样的效果：

You could achieve the same result with separate bindings to the <input> element's value property and input event:

      
        content_copy
      
      <label for="without">without NgModel:</label>
<input [value]="currentItem.name" (input)="currentItem.name=$event.target.value" id="without">
    

为了简化语法，ngModel 指令把技术细节隐藏在其输入属性 ngModel 和输出属性 ngModelChange 的后面：

To streamline the syntax, the ngModel directive hides the details behind its own ngModel input and ngModelChange output properties:

      
        content_copy
      
      <label for="example-change">(ngModelChange)="...name=$event":</label>
<input [ngModel]="currentItem.name" (ngModelChange)="currentItem.name=$event" id="example-change">
    

ngModel 输入属性会设置该元素的值，并通过 ngModelChange 的输出属性来监听元素值的变化。

The ngModel data property sets the element's value property and the ngModelChange event property listens for changes to the element's value.

NgModel 和值访问器link

NgModel and value accessorslink

这些技术细节是针对每种具体元素的，因此 NgModel 指令仅适用于通过 ControlValueAccessor 适配过这种协议的元素。Angular 已经为所有基本的 HTML 表单元素提供了值访问器，表单一章示范了如何绑定到它们。

The details are specific to each kind of element and therefore the NgModel directive only works for an element supported by a ControlValueAccessor that adapts an element to this protocol. Angular provides value accessors for all of the basic HTML form elements and the Forms guide shows how to bind to them.

在编写适当的值访问器之前，不能将 [(ngModel)] 应用于非表单的原生元素或第三方自定义组件。欲知详情，参阅DefaultValueAccessor上的 API 文档。

You can't apply [(ngModel)] to a non-form native element or a third-party custom component until you write a suitable value accessor. For more information, see the API documentation on DefaultValueAccessor.

你不一定非用为所编写的 Angular 组件提供值访问器，因为你还可以把值属性和事件属性命名为符合 Angular 的基本双向绑定语法的形式，并完全跳过 NgModel。双向绑定部分的 sizer 是此技术的一个范例。

You don't need a value accessor for an Angular component that you write because you can name the value and event properties to suit Angular's basic two-way binding syntax and skip NgModel altogether. The sizer in the Two-way Binding section is an example of this technique.

单独的 ngModel 绑定是对绑定到元素的原生属性方式的一种改进，但你可以使用 [(ngModel)] 语法来通过单个声明简化绑定：

Separate ngModel bindings are an improvement over binding to the element's native properties, but you can streamline the binding with a single declaration using the [(ngModel)] syntax:

      
        content_copy
      
      <label for="example-ngModel">[(ngModel)]:</label>
<input [(ngModel)]="currentItem.name" id="example-ngModel">
    

此 [(ngModel)] 语法只能设置数据绑定属性。如果你要做得更多，可以编写扩展表单。例如，下面的代码将 <input> 值更改为大写：

This [(ngModel)] syntax can only set a data-bound property. If you need to do something more, you can write the expanded form; for example, the following changes the <input> value to uppercase:

      
        content_copy
      
      <input [ngModel]="currentItem.name" (ngModelChange)="setUppercaseName($event)" id="example-uppercase">
    

这里是所有这些变体的动画，包括这个大写转换的版本：

Here are all variations in action, including the uppercase version:

内置结构型指令link

Built-in structural directiveslink

结构型指令的职责是 HTML 布局。 它们塑造或重塑 DOM 的结构，这通常是通过添加、移除和操纵它们所附加到的宿主元素来实现的。

Structural directives are responsible for HTML layout. They shape or reshape the DOM's structure, typically by adding, removing, and manipulating the host elements to which they are attached.

本节会介绍常见的内置结构型指令：

This section is an introduction to the common built-in structural directives:

• NgIf—— 从模板中创建或销毁子视图。

  NgIf—conditionally creates or destroys subviews from the template.

• NgFor—— 为列表中的每个条目重复渲染一个节点。

  NgFor—repeat a node for each item in a list.

• NgSwitch—— 一组在备用视图之间切换的指令。

  NgSwitch—a set of directives that switch among alternative views.

NgIflink

你可以通过将 NgIf 指令应用在宿主元素上来从 DOM 中添加或删除元素。在此范例中，将指令绑定到了条件表达式，例如 isActive。

You can add or remove an element from the DOM by applying an NgIf directive to a host element. Bind the directive to a condition expression like isActive in this example.

      
        content_copy
      
      <app-item-detail *ngIf="isActive" [item]="item"></app-item-detail>
    

当 isActive 表达式返回真值时，NgIf 会把 ItemDetailComponent 添加到 DOM 中。当表达式为假值时，NgIf 将从 DOM 中删除 ItemDetailComponent，从而销毁该组件及其所有子组件。

When the isActive expression returns a truthy value, NgIf adds the ItemDetailComponent to the DOM. When the expression is falsy, NgIf removes the ItemDetailComponent from the DOM, destroying that component and all of its sub-components.

显示/隐藏与 NgIflink

Show/hide vs. NgIflink

隐藏元素与使用 NgIf 删除元素不同。为了进行比较，下面的范例演示如何使用类或样式绑定来控制元素的可见性。

Hiding an element is different from removing it with NgIf. For comparison, the following example shows how to control the visibility of an element with a class or style binding.

      
        content_copy
      
      <!-- isSpecial is true -->
<div [class.hidden]="!isSpecial">Show with class</div>
<div [class.hidden]="isSpecial">Hide with class</div>

<p>ItemDetail is in the DOM but hidden</p>
<app-item-detail [class.hidden]="isSpecial"></app-item-detail>

<div [style.display]="isSpecial ? 'block' : 'none'">Show with style</div>
<div [style.display]="isSpecial ? 'none'  : 'block'">Hide with style</div>
    

隐藏元素时，该元素及其所有后代仍保留在 DOM 中。这些元素的所有组件都保留在内存中，Angular 会继续做变更检查。它可能会占用大量计算资源，并且会不必要地降低性能。

When you hide an element, that element and all of its descendants remain in the DOM. All components for those elements stay in memory and Angular may continue to check for changes. You could be holding onto considerable computing resources and degrading performance unnecessarily.

NgIf 工作方式有所不同。如果 NgIf 为 false，则 Angular 将从 DOM 中删除该元素及其后代。这销毁了它们的组件，释放了资源，从而带来更好的用户体验。

NgIf works differently. When NgIf is false, Angular removes the element and its descendants from the DOM. It destroys their components, freeing up resources, which results in a better user experience.

如果要隐藏大型组件树，请考虑使用 NgIf 作为显示/隐藏的更有效替代方法。

If you are hiding large component trees, consider NgIf as a more efficient alternative to showing/hiding.

防范空指针错误link

Guard against nulllink

ngIf 另一个优点是你可以使用它来防范空指针错误。显示/隐藏就是最合适的极简用例，当你需要防范时，请改用 ngIf 代替。如果其中嵌套的表达式尝试访问 null 的属性，Angular 将引发错误。

Another advantage of ngIf is that you can use it to guard against null. Show/hide is best suited for very simple use cases, so when you need a guard, opt instead for ngIf. Angular will throw an error if a nested expression tries to access a property of null.

下面的例子中 NgIf 保护着两个 <div>。仅当存在 currentCustomer 时，才会显示 currentCustomer 名称。除非它为 null 否则不会显示 nullCustomer。

The following shows NgIf guarding two <div>s. The currentCustomer name appears only when there is a currentCustomer. The nullCustomer will not be displayed as long as it is null.

      
        content_copy
      
      <div *ngIf="currentCustomer">Hello, {{currentCustomer.name}}</div>
    

      
        content_copy
      
      <div *ngIf="nullCustomer">Hello, <span>{{nullCustomer}}</span></div>
    

NgForlink

NgFor 是一个重复器指令 —— 一种用来显示条目列表的方法。你定义了一个 HTML 块，该 HTML 块定义了应如何显示单个条目，然后告诉 Angular 以该块为模板来渲染列表中的每个条目。赋值给 *ngFor 的文本是用来指导重复器工作过程的指令。

NgFor is a repeater directive—a way to present a list of items. You define a block of HTML that defines how a single item should be displayed and then you tell Angular to use that block as a template for rendering each item in the list. The text assigned to *ngFor is the instruction that guides the repeater process.

以下范例显示了如何将 NgFor 应用于简单的 <div>。

The following example shows NgFor applied to a simple <div>.

      
        content_copy
      
      <div *ngFor="let item of items">{{item.name}}</div>
    

你还可以将 NgFor 应用于组件元素，如以下范例所示。

You can also apply an NgFor to a component element, as in the following example.

      
        content_copy
      
      <app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>
    

模板输入变量link

Template input variableslink

item 前面的 let 关键字创建了一个名为 item 的模板输入变量。ngFor 指令迭代父组件的 items 属性所返回的 items 数组，并在每次迭代期间将 item 设置为该数组中的当前条目。

The let keyword before item creates a template input variable called item. The ngFor directive iterates over the items array returned by the parent component's items property and sets item to the current item from the array during each iteration.

ngFor 的宿主元素及其后代中可引用 item，来访问该条目的属性。以下范例首先在插值中引用 item，然后把一个绑定表达式传入 <app-item-detail> 组件的 item 属性。

Reference item within the ngFor host element as well as within its descendants to access the item's properties. The following example references item first in an interpolation and then passes in a binding to the item property of the <app-item-detail> component.

      
        content_copy
      
      <div *ngFor="let item of items">{{item.name}}</div>
<!-- . . . -->
  <app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>
    

关于模板输入变量的更多信息，请参阅结构型指令。

For more information about template input variables, see Structural Directives.

*ngFor 与 indexlink

*ngFor with indexlink

NgFor 指令上下文中的 index 属性在每次迭代中返回该条目的从零开始的索引。 你可以在模板输入变量中捕获 index，并在模板中使用它。

The index property of the NgFor directive context returns the zero-based index of the item in each iteration. You can capture the index in a template input variable and use it in the template.

下面的例子在名为 i 的变量中捕获 index，并将其与条目名称一起显示。

The next example captures the index in a variable named i and displays it with the item name.

      
        content_copy
      
      <div *ngFor="let item of items; let i=index">{{i + 1}} - {{item.name}}</div>
    

带 trackBy 的 *ngForlink

*ngFor with trackBylink

如果将 NgFor 与大型列表一起使用，则对某个条目的较小更改（例如删除或添加一项）就会触发一系列 DOM 操作。 例如，重新查询服务器可能会重置包含所有新条目对象的列表，即使先前已显示这些条目也是如此。在这种情况下，Angular 只能看到由新的对象引用组成的新列表，它别无选择，只能用所有新的 DOM 元素替换旧的 DOM 元素。

If you use NgFor with large lists, a small change to one item, such as removing or adding an item, can trigger a cascade of DOM manipulations. For example, re-querying the server could reset a list with all new item objects, even when those items were previously displayed. In this case, Angular sees only a fresh list of new object references and has no choice but to replace the old DOM elements with all new DOM elements.

你可以使用 trackBy 来让它更加高效。向该组件添加一个方法，该方法返回 NgFor 应该跟踪的值。这个例子中，该值是英雄的 id。如果 id 已经被渲染，Angular 就会跟踪它，而不会重新向服务器查询相同的 id。

You can make this more efficient with trackBy. Add a method to the component that returns the value NgFor should track. In this case, that value is the hero's id. If the id has already been rendered, Angular keeps track of it and doesn't re-query the server for the same id.

      
        content_copy
      
      trackByItems(index: number, item: Item): number { return item.id; }
    

在微语法表达式中，将 trackBy 设置为 trackByItems() 方法。

In the microsyntax expression, set trackBy to the trackByItems() method.

      
        content_copy
      
      <div *ngFor="let item of items; trackBy: trackByItems">
  ({{item.id}}) {{item.name}}
</div>
    

这就是 trackBy 效果的说明。“Reset items” 将创建具有相同 item.id 的新条目。“Change ids” 将使用新的 item.id 创建新条目。

Here is an illustration of the trackBy effect. "Reset items" creates new items with the same item.ids. "Change ids" creates new items with new item.ids.

• 如果没有 trackBy，这些按钮都会触发完全的 DOM 元素替换。

  With no trackBy, both buttons trigger complete DOM element replacement.

• 有了 trackBy，则只有修改了 id 的按钮才会触发元素替换。

  With trackBy, only changing the id triggers element replacement.

NgSwitch 指令link

The NgSwitch directiveslink

NgSwitch 类似于 JavaScript switch 语句。它根据切换条件显示几个可能的元素中的一个。Angular 只会将选定的元素放入 DOM。

NgSwitch is like the JavaScript switch statement. It displays one element from among several possible elements, based on a switch condition. Angular puts only the selected element into the DOM.

NgSwitch 实际上是三个协作指令的集合： NgSwitch，NgSwitchCase 和 NgSwitchDefault，如以下范例所示。

NgSwitch is actually a set of three, cooperating directives: NgSwitch, NgSwitchCase, and NgSwitchDefault as in the following example.

      
        content_copy
      
      <div [ngSwitch]="currentItem.feature">
  <app-stout-item    *ngSwitchCase="'stout'"    [item]="currentItem"></app-stout-item>
  <app-device-item   *ngSwitchCase="'slim'"     [item]="currentItem"></app-device-item>
  <app-lost-item     *ngSwitchCase="'vintage'"  [item]="currentItem"></app-lost-item>
  <app-best-item     *ngSwitchCase="'bright'"   [item]="currentItem"></app-best-item>
<!-- . . . -->
  <app-unknown-item  *ngSwitchDefault           [item]="currentItem"></app-unknown-item>
</div>
    

NgSwitch 是控制器指令。把它绑定到一个返回开关值的表达式，例如 feature。尽管此范例中的 feature 值是字符串，但开关值可以是任何类型。

NgSwitch is the controller directive. Bind it to an expression that returns the switch value, such as feature. Though the feature value in this example is a string, the switch value can be of any type.

绑定到 [ngSwitch]。如果试图写成 *ngSwitch，就会出现错误，因为 NgSwitch 是属性型指令，而不是结构型指令。它不会直接接触 DOM，而是会更改与之相伴的指令的行为。

Bind to [ngSwitch]. You'll get an error if you try to set *ngSwitch because NgSwitch is an attribute directive, not a structural directive. Rather than touching the DOM directly, it changes the behavior of its companion directives.

绑定到 *ngSwitchCase 和 *ngSwitchDefault NgSwitchCase 和 NgSwitchDefault 指令都是结构型指令，因为它们会从 DOM 中添加或移除元素。

Bind to *ngSwitchCase and *ngSwitchDefault. The NgSwitchCase and NgSwitchDefault directives are structural directives because they add or remove elements from the DOM.

• 当 NgSwitchCase 的绑定值等于开关值时，就将其元素添加到 DOM 中；否则从 DOM 中删除。

  NgSwitchCase 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.

• NgSwitchDefault 会在没有任何一个 NgSwitchCase 被选中时把它所在的元素加入 DOM 中。

  NgSwitchDefault adds its element to the DOM when there is no selected NgSwitchCase.

开关指令对于添加和删除组件元素特别有用。本范例在 item-switch.components.ts 文件中定义的四个 item 组件之间切换。每个组件都有一个名叫 item 的输入属性，它会绑定到父组件的 currentItem。

The switch directives are particularly useful for adding and removing component elements. This example switches among four item components defined in the item-switch.components.ts file. Each component has an item input property which is bound to the currentItem of the parent component.

开关指令也同样适用于原生元素和 Web Component。 比如，你可以把 <app-best-item> 分支替换为如下代码。

Switch directives work as well with native elements and web components too. For example, you could replace the <app-best-item> switch case with the following.

      
        content_copy
      
      <div *ngSwitchCase="'bright'"> Are you as bright as {{currentItem.name}}?</div>