内置指令
Built-in directives
Angular offers two kinds of built-in directives: attribute directives and structural directives.
要查看包含本指南中代码的可工作范例,请参阅
See the
欲知详情,包括如何构建你自己的自定义指令,请参阅属性型指令和结构型指令。
For more detail, including how to build your own custom directives, see Attribute Directives and Structural Directives.
内置属性型指令
Built-in attribute directives
属性型指令会监听并修改其它 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 RouterModule
and the FormsModule
define 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.
NgClass
用 ngClass
同时添加或删除几个 CSS 类。
Add or remove several CSS classes simultaneously with ngClass
.
<!-- toggle the "special" class on/off with a property -->
<div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>
To add or remove a single class, use class binding rather than NgClass
.
考虑一个 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.
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:
<div [ngClass]="currentClasses">This div is initially saveable, unchanged, and special.</div>
请记住,在这种情况下,你要在初始化时和它依赖的属性发生变化时调用 setCurrentClasses()
。
Remember that in this situation you'd call setCurrentClasses()
, both initially and when the dependent properties change.
NgStyle
使用 NgStyle
根据组件的状态同时动态设置多个内联样式。
Use NgStyle
to set many inline styles simultaneously and dynamically, based on the state of the component.
不用 NgStyle
Without NgStyle
有些情况下,要考虑使用样式绑定来设置单个样式值,而不使用 NgStyle
。
For context, consider setting a single style value with style binding, without NgStyle
.
<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:
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:
<div [ngStyle]="currentStyles">
This div is initially italic, normal weight, and extra large (24px).
</div>
请记住,无论是在初始时还是其依赖的属性发生变化时,都要调用 setCurrentStyles()
。
Remember to call setCurrentStyles()
, both initially and when the dependent properties change.
[(ngModel)]
:双向绑定
[(ngModel)]
: Two-way binding
NgModel
指令允许你显示数据属性并在用户进行更改时更新该属性。这是一个例子:
The NgModel
directive allows you to display a data property and update that property when the user makes changes. Here's an example:
<label for="example-ngModel">[(ngModel)]:</label>
<input [(ngModel)]="currentItem.name" id="example-ngModel">
导入 FormsModule
以使用 ngModel
Import FormsModule
to use ngModel
要想在双向数据绑定中使用 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:
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:
<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:
<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
和值访问器
NgModel
and value accessors
这些技术细节是针对每种具体元素的,因此 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:
<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:
<input [ngModel]="currentItem.name" (ngModelChange)="setUppercaseName($event)" id="example-uppercase">
这里是所有这些变体的动画,包括这个大写转换的版本:
Here are all variations in action, including the uppercase version:

内置结构型指令
Built-in structural directives
结构型指令的职责是 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.
结构型指令一章涵盖了结构型指令的详细内容,它解释了以下内容:
The deep details of structural directives are covered in the Structural Directives guide, which explains the following:
为什么在要指令名称前加上星号(*)。
当指令没有合适的宿主元素时,使用
<ng-container>
对元素进行分组。Using
<ng-container>
to group elements when there is no suitable host element for the directive.如何写自己的结构型指令。
How to write your own structural directive.
为什么你只能往一个元素上应用一个结构型指令。
Why you can only apply one structural directive to an element.
NgIf
你可以通过将 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.
<app-item-detail *ngIf="isActive" [item]="item"></app-item-detail>
不要忘了 ngIf
前面的星号(*
)。关于星号的更多信息,请参阅 结构型指令中的星号(*)前缀部分。
Don't forget the asterisk (*
) in front of ngIf
. For more information on the asterisk, see the asterisk (*) prefix section of Structural Directives.
当 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.
显示/隐藏与 NgIf
Show/hide vs. NgIf
隐藏元素与使用 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.
<!-- 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.
关于 NgIf
和 ngIfElse
的更多信息,请参阅 关于 NgIf 的 API 文档。
For more information on NgIf
and ngIfElse
, see the API documentation about NgIf.
防范空指针错误
Guard against null
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
.
<div *ngIf="currentCustomer">Hello, {{currentCustomer.name}}</div>
<div *ngIf="nullCustomer">Hello, <span>{{nullCustomer}}</span></div>
NgFor
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>
.
<div *ngFor="let item of items">{{item.name}}</div>
不要忘了 ngFor
前面的星号(*
)。关于星号的更多信息,请参阅结构型指令中的星号(*)前缀部分。
Don't forget the asterisk (*
) in front of ngFor
. For more information on the asterisk, see the asterisk (*) prefix section of Structural Directives.
你还可以将 NgFor
应用于组件元素,如以下范例所示。
You can also apply an NgFor
to a component element, as in the following example.
<app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>
赋值给 *ngFor
的字符串不是模板表达式。而是一个微语法 —— 由 Angular 解释的一种小型语言。字符串 "let item of items"
的意思是:
The string assigned to *ngFor
is not a template expression. Rather, it's a microsyntax—a little language of its own that Angular interprets. The string "let item of items"
means:
将
items
数组中的每个条目存储在局部循环变量item
中,并使其可用于每次迭代的模板 HTML 中。Take each item in the
items
array, store it in the localitem
looping variable, and make it available to the templated HTML for each iteration.
Angular 将该指令转换为包裹着宿主元素的 <ng-template>
,然后反复使用此模板为列表中的每个 item
创建一组新的元素和绑定。关于微语法的更多信息,请参阅结构型指令一章。
Angular translates this instruction into an <ng-template>
around the host element, then uses this template repeatedly to create a new set of elements and bindings for each item
in the list. For more information about microsyntax, see the Structural Directives guide.
模板输入变量
Template input variables
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.
<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
与 index
*ngFor
with index
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.
<div *ngFor="let item of items; let i=index">{{i + 1}} - {{item.name}}</div>
要学习更多的类似 index 的值,例如 last
、even
和 odd
,请参阅 NgFor API 参考。
NgFor
is implemented by the NgForOf
directive. Read more about the other NgForOf
context values such as last
, even
, and odd
in the NgForOf API reference.
带 trackBy
的 *ngFor
*ngFor with trackBy
如果将 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
.
trackByItems(index: number, item: Item): number { return item.id; }
在微语法表达式中,将 trackBy
设置为 trackByItems()
方法。
In the microsyntax expression, set trackBy
to the trackByItems()
method.
<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.id
s. "Change ids" creates new items with new item.id
s.
如果没有
trackBy
,这些按钮都会触发完全的 DOM 元素替换。With no
trackBy
, both buttons trigger complete DOM element replacement.有了
trackBy
,则只有修改了id
的按钮才会触发元素替换。With
trackBy
, only changing theid
triggers element replacement.

内置指令仅仅使用了公共 API。也就是说,它们没有用到任何其它指令无权访问的私有 API。
Built-in directives use only public APIs; that is, they do not have special access to any private APIs that other directives can't access.
NgSwitch
指令
The NgSwitch
directives
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.
<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 selectedNgSwitchCase
.
开关指令对于添加和删除组件元素特别有用。本范例在 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.
<div *ngSwitchCase="'bright'"> Are you as bright as {{currentItem.name}}?</div>