diff --git a/aio/content/file-not-found.md b/aio/content/file-not-found.md index 9371fe03bf..8bdba34990 100644 --- a/aio/content/file-not-found.md +++ b/aio/content/file-not-found.md @@ -1,10 +1,18 @@ @description
+ +
+

Page Not Found

+

We're sorry. The page you are looking for cannot be found.

+
+
+ + diff --git a/aio/content/guide/ajs-quick-reference.md b/aio/content/guide/ajs-quick-reference.md index c92f7d0883..02cb2af1a8 100644 --- a/aio/content/guide/ajs-quick-reference.md +++ b/aio/content/guide/ajs-quick-reference.md @@ -4,18 +4,16 @@ {@a top} - _Angular_ is the name for the Angular of today and tomorrow. _AngularJS_ is the name for all v1.x versions of Angular. -_Angular_ 是 Angular 现在以及未来的名字，而 _AngularJS_ 则用来专指所有 Angular 的 1.x 版本。 +*Angular*这个名字专指现在和未来的Angular版本，而*AngularJS*专指Angular的所有v1.x版本。 This guide helps you transition from AngularJS to Angular by mapping AngularJS syntax to the equivalent Angular syntax. 本章提供了一个快速的参考指南，指出一些常用的AngularJS语法及其在Angular中的等价物。 - **See the Angular syntax in this **. **参见 以学习 Angular 语法** @@ -29,7 +27,6 @@ The following table lists some of the key AngularJS template features with their 模板是Angular应用中的门面部分，它是用HTML写的。下表中是一些AngularJS中的关键模板特性及其在Angular中的等价语法。 - @@ -43,11 +40,15 @@ The following table lists some of the key AngularJS template features with their @@ -56,15 +57,15 @@ The following table lists some of the key AngularJS template features with their @@ -162,17 +160,17 @@ The following table lists some of the key AngularJS template features with their
+ AngularJS + + Angular +
- ### Bindings/interpolation ### 绑定/插值表达式 - Your favorite hero is: {{vm.favoriteHero}} - + Your favorite hero is: {{vm.favoriteHero}} + + In AngularJS, an expression in curly braces denotes one-way binding. This binds the value of the element to a property in the controller @@ -83,14 +84,12 @@ The following table lists some of the key AngularJS template features with their - ### Bindings/interpolation ### 绑定/插值表达式 - In Angular, a template expression in curly braces still denotes one-way binding. This binds the value of the element to a property of the component. The context of the binding is implied and is always the @@ -114,15 +113,15 @@ The following table lists some of the key AngularJS template features with their - ### Filters ### 过滤器 - <td>{{movie.title | uppercase}}</td> - + <td>{{movie.title | uppercase}}</td> + + To filter output in AngularJS templates, use the pipe character (|) and one or more filters. @@ -136,14 +135,12 @@ The following table lists some of the key AngularJS template features with their - ### Pipes ### 管道 - In Angular you use similar syntax with the pipe (|) character to filter output, but now you call them **pipes**. Many (but not all) of the built-in filters from AngularJS are built-in pipes in Angular. @@ -154,6 +151,7 @@ The following table lists some of the key AngularJS template features with their For more information, see [Filters/pipes](guide/ajs-quick-reference#filters-pipes) below. 请参见下面[过滤器/管道](guide/ajs-quick-reference#filters-pipes)了解更多信息。 +
- ### Local variables ### 局部变量 + <tr ng-repeat="movie in vm.movies"> <td>{{movie.title}}</td> </tr> - + Here, `movie` is a user-defined local variable. @@ -182,14 +180,12 @@ The following table lists some of the key AngularJS template features with their - ### Input variables ### 输入变量 - Angular has true template input variables that are explicitly defined using the `let` keyword. 在Angular中，我们有了真正的模板输入变量，它需要使用`let`关键字进行明确定义。 @@ -198,13 +194,13 @@ The following table lists some of the key AngularJS template features with their section of the [Template Syntax](guide/template-syntax) page. 要了解更多信息，请参见[模板语法](guide/template-syntax)中的[ngFor微语法](guide/template-syntax#microsyntax)部分。 +
- ## Template directives ## 模板指令 @@ -217,7 +213,6 @@ AngularJS 为模板提供了七十多个内置指令。 在 Angular 中，它们很多都已经不需要了，因为 Angular 有了一个更加强大、快捷的绑定系统。 下面是一些AngularJS 中的关键指令及其在 Angular 中的等价物。 - @@ -231,11 +226,15 @@ AngularJS 为模板提供了七十多个内置指令。 @@ -244,13 +243,13 @@ AngularJS 为模板提供了七十多个内置指令。 @@ -55,7 +69,9 @@ The following table summarizes the `@NgModule` metadata properties.
+ AngularJS + + Angular +
- ### ng-app - <body ng-app="movieHunter"> - + <body ng-app="movieHunter"> + + The application startup process is called **bootstrapping**. @@ -267,17 +266,16 @@ AngularJS 为模板提供了七十多个内置指令。 - ### Bootstrapping ### 引导 +
- Angular doesn't have a bootstrap directive. To launch the app in code, explicitly bootstrap the application's root module (`AppModule`) in `main.ts` @@ -294,15 +292,15 @@ AngularJS 为模板提供了七十多个内置指令。 		- ### ng-class + <div ng-class="{active: isActive}"> <div ng-class="{active: isActive, shazam: isImportant}"> - + In AngularJS, the `ng-class` directive includes/excludes CSS classes based on an expression. That expression is often a key-value control object with each @@ -314,22 +312,20 @@ AngularJS 为模板提供了七十多个内置指令。 In the first example, the `active` class is applied to the element if `isActive` is true. - 在第一个例子中，当`isActive`为真时，`active`类会被应用到元素上。 + 在第一个例子中，如果`isActive`为真，则`active`类被应用到那个元素上。 You can specify multiple classes, as shown in the second example. - 就像第二个例子中展示的，可以指定多个CSS类。 + 就像第二个例子中所展示的那样，可以同时指定多个类。 - ### ngClass - In Angular, the `ngClass` directive works similarly. It includes/excludes CSS classes based on an expression. @@ -362,14 +358,14 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-click + <button ng-click="vm.toggleImage()"> <button ng-click="vm.toggleImage($event)"> - + In AngularJS, the `ng-click` directive allows you to specify custom behavior when an element is clicked. @@ -388,14 +384,12 @@ AngularJS 为模板提供了七十多个内置指令。 - ### Bind to the `click` event ### 绑定到`click`事件 - AngularJS event-based directives do not exist in Angular. Rather, define one-way binding from the template view to the component using **event binding**. @@ -436,13 +430,13 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-controller - <div ng-controller="MovieListCtrl as vm"> - + <div ng-controller="MovieListCtrl as vm"> + + In AngularJS, the `ng-controller` directive attaches a controller to the view. Using the `ng-controller` (or defining the controller as part of the routing) ties the @@ -455,14 +449,12 @@ AngularJS 为模板提供了七十多个内置指令。 - ### Component decorator - ### Component装饰器 + ### 组件装饰器 - In Angular, the template no longer specifies its associated controller. Rather, the component specifies its associated template as part of the component class decorator. @@ -481,8 +473,8 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-hide + In AngularJS, the `ng-hide` directive shows or hides the associated HTML element based on an expression. For more information, see [ng-show](guide/ajs-quick-reference#ng-show). @@ -493,10 +485,9 @@ AngularJS 为模板提供了七十多个内置指令。 - ### Bind to the `hidden` property - ### 绑定`hidden`属性 + ### 绑定到`hidden`属性 In Angular, you use property binding; there is no built-in *hide* directive. For more information, see [ng-show](guide/ajs-quick-reference#ng-show). @@ -512,13 +503,13 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-href - <a ng-href="{{ angularDocsUrl }}">Angular Docs</a> - + <a ng-href="{{ angularDocsUrl }}">Angular Docs</a> + + The `ng-href` directive allows AngularJS to preprocess the `href` property so that it can replace the binding expression with the appropriate URL before the browser @@ -529,27 +520,27 @@ AngularJS 为模板提供了七十多个内置指令。 In AngularJS, the `ng-href` is often used to activate a route as part of navigation. 在AngularJS 中，`ng-href`通常用来作为导航的一部分，激活一个路由。 - - - <a ng-href="#{{ moviesHash }}">Movies</a> - + + + <a ng-href="#{{ moviesHash }}">Movies</a> + + Routing is handled differently in Angular. 路由在Angular中的处理方式不同。 + - ### Bind to the `href` property ### 绑定到`href`属性 - Angular uses property binding; there is no built-in *href* directive. Place the element's `href` property in square brackets and set it to a quoted template expression. @@ -567,7 +558,6 @@ AngularJS 为模板提供了七十多个内置指令。 - For more information on routing, see the [RouterLink binding](guide/router#router-link) section of the [Routing & Navigation](guide/router) page. @@ -581,13 +571,13 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-if - <table ng-if="movies.length"> - + <table ng-if="movies.length"> + + In AngularJS, the `ng-if` directive removes or recreates a portion of the DOM, based on an expression. If the expression is false, the element is removed from the DOM. @@ -597,16 +587,15 @@ AngularJS 为模板提供了七十多个内置指令。 In this example, the `` element is removed from the DOM unless the `movies` array has a length greater than zero. 在这个例子中，除非`movies`数组的长度大于0，否则`
`元素就会被从DOM中移除。 + `) element repeats for each movie object in the collection of movies. 在这个例子中，对`movies`集合中的每一个`movie`对象重复渲染了这个表格行元素(``)。 + ` in this example) and its contents into a template and @@ -721,6 +707,7 @@ AngularJS 为模板提供了七十多个内置指令。 For more information, see [Structural Directives](guide/structural-directives). 要了解更多信息，参见[结构性指令](guide/structural-directives)。 + @@ -729,15 +716,15 @@ AngularJS 为模板提供了七十多个内置指令。 @@ -787,15 +773,14 @@ AngularJS 为模板提供了七十多个内置指令。
- ### *ngIf - The `*ngIf` directive in Angular works the same as the `ng-if` directive in AngularJS. It removes or recreates a portion of the DOM based on an expression. @@ -631,13 +620,13 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-model - <input ng-model="vm.favoriteHero"/> - + <input ng-model="vm.favoriteHero"/> + + In AngularJS, the `ng-model` directive binds a form control to a property in the controller associated with the template. This provides **two-way binding**, whereby any change made to the value in the view is synchronized with the model, and any change to the model is synchronized with the value in the view. @@ -649,12 +638,10 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ngModel - In Angular, **two-way binding** is denoted by `[()]`, descriptively referred to as a "banana in a box". This syntax is a shortcut for defining both property binding (from the component to the view) and event binding (from the view to the component), thereby providing two-way binding. @@ -675,13 +662,13 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-repeat - <tr ng-repeat="movie in vm.movies"> - + <tr ng-repeat="movie in vm.movies"> + + In AngularJS, the `ng-repeat` directive repeats the associated DOM element for each item in the specified collection. @@ -691,16 +678,15 @@ AngularJS 为模板提供了七十多个内置指令。 In this example, the table row (`
- ### *ngFor - The `*ngFor` directive in Angular is similar to the `ng-repeat` directive in AngularJS. It repeats the associated DOM element for each item in the specified collection. More accurately, it turns the defined element (`
- ### ng-show + <h3 ng-show="vm.favoriteHero"> Your favorite hero is: {{vm.favoriteHero}} </h3> - + In AngularJS, the `ng-show` directive shows or hides the associated DOM element, based on an expression. @@ -747,18 +734,17 @@ AngularJS 为模板提供了七十多个内置指令。 In this example, the `
` element is shown if the `favoriteHero` variable is truthy. 在这个例子中，如果`favoriteHero`变量为真，`
`元素就会显示出来。 +
- ### Bind to the `hidden` property ### 绑定到`hidden`属性 - Angular uses property binding; there is no built-in *show* directive. For hiding and showing elements, bind to the HTML `hidden` property. @@ -777,7 +763,7 @@ AngularJS 为模板提供了七十多个内置指令。 For more information on property binding, see the [Property binding](guide/template-syntax#property-binding) section of the [Template Syntax](guide/template-syntax) page. - 要了解关于属性绑定的更多信息，参见[模板语法](guide/template-syntax)中的[模板表达式](guide/template-syntax#property-binding)部分。 + 要了解属性绑定的更多知识，参见[模板语法](guide/template-syntax)中的[属性绑定](guide/template-syntax#property-binding)部分。 - ### ng-src + <img ng-src="{{movie.imageurl}}"> - The `ng-src` directive allows AngularJS to preprocess the `src` property so that it can replace the binding expression with the appropriate URL before the browser fetches from that URL. @@ -806,14 +791,12 @@ AngularJS 为模板提供了七十多个内置指令。 - ### Bind to the `src` property ### 绑定到`src`属性 - Angular uses property binding; there is no built-in *src* directive. Place the `src` property in square brackets and set it to a quoted template expression. @@ -833,15 +816,14 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-style + <div ng-style="{color: colorPreference}"> - In AngularJS, the `ng-style` directive sets a CSS style on an HTML element based on an expression. That expression is often a key-value control object with each key of the object defined as a CSS property, and each value defined as an expression @@ -858,12 +840,10 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ngStyle - In Angular, the `ngStyle` directive works similarly. It sets a CSS style on an HTML element based on an expression. 在Angular中，`ngStyle`指令的工作方式与此类似。它根据一个表达式设置HTML元素上的CSS样式。 @@ -894,10 +874,10 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ng-switch + <div ng-switch="vm.favoriteHero && vm.checkMovieHero(vm.favoriteHero)"> <div ng-switch-when="true"> @@ -913,7 +893,6 @@ AngularJS 为模板提供了七十多个内置指令。 - In AngularJS, the `ng-switch` directive swaps the contents of an element by selecting one of the templates based on the current value of an expression. @@ -933,12 +912,10 @@ AngularJS 为模板提供了七十多个内置指令。 - ### ngSwitch - In Angular, the `ngSwitch` directive works similarly. It displays an element whose `*ngSwitchCase` matches the current `ngSwitch` expression value. @@ -972,11 +949,8 @@ AngularJS 为模板提供了七十多个内置指令。
- {@a filters-pipes} - - ## Filters/pipes ## 过滤器/管道 @@ -989,7 +963,6 @@ Angular中的**管道**为模板提供了格式化和数据转换功能，类似 AngularJS中的很多内置过滤器在Angular中都有对应的管道。 要了解管道的更多信息，参见[Pipes](guide/pipes)。 - @@ -1003,11 +976,15 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1016,13 +993,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1049,13 +1025,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1151,28 +1123,27 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1189,13 +1161,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1222,13 +1193,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 @@ -1263,28 +1233,28 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。
+ AngularJS + + Angular +
- ### currency - <td>{{movie.price | currency}}</td> - + <td>{{movie.price | currency}}</td> + + Formats a number as currency. @@ -1032,15 +1009,14 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### currency - The Angular `currency` pipe is similar although some of the parameters have changed. Angular的`currency`管道和1中很相似，只是有些参数变化了。 +
- ### date - <td>{{movie.releaseDate | date}}</td> - + <td>{{movie.releaseDate | date}}</td> + + Formats a date to a string based on the requested format. @@ -1065,12 +1041,10 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### date - The Angular `date` pipe is similar. Angular的`date`管道和它很相似。 @@ -1083,13 +1057,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### filter - <tr ng-repeat="movie in movieList | filter: {title:listFilter}"> - + <tr ng-repeat="movie in movieList | filter: {title:listFilter}"> + + Selects a subset of items from the defined collection, based on the filter criteria. @@ -1099,11 +1073,10 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### none - + ### 没了 - + For performance reasons, no comparable pipe exists in Angular. Do all your filtering in the component. If you need the same filtering code in several templates, consider building a custom pipe. 在Angular中，出于性能的考虑，并没有一个类似的管道。 @@ -1118,13 +1091,13 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### json - <pre>{{movie | json}}</pre> - + <pre>{{movie | json}}</pre> + + Converts a JavaScript object into a JSON string. This is useful for debugging. @@ -1134,15 +1107,14 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### json - The Angular `json` pipe does the same thing. Angular的`json`管道做完全相同的事。 +
- ### limitTo - <tr ng-repeat="movie in movieList | limitTo:2:0"> - + <tr ng-repeat="movie in movieList | limitTo:2:0"> + + Selects up to the first parameter (2) number of items from the collection starting (optionally) at the beginning index (0). 从集合中选择从(第二参数指定的)起始索引号(0)开始的最多(第一参数指定的)条目数(2)个条目。 + - ### slice - The `SlicePipe` does the same thing but the *order of the parameters is reversed*, in keeping with the JavaScript `Slice` method. The first parameter is the starting index; the second is the limit. @@ -1181,6 +1152,7 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 `SlicePipe`做同样的事，但是*两个参数的顺序是相反的*，以便于JavaScript中的`slice`方法保持一致。 第一个参数是起始索引号，第二个参数是限制的数量。 和AngularJS中一样，如果们改用组件中的代码实现此操作，性能将会提升。 +
- ### lowercase - <div>{{movie.title | lowercase}}</div> - + <div>{{movie.title | lowercase}}</div> + + Converts the string to lowercase. @@ -1205,15 +1177,14 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### lowercase - The Angular `lowercase` pipe does the same thing. Angular的`lowercase`管道和1中的功能完全相同。 +
- ### number - <td>{{movie.starRating | number}}</td> - + <td>{{movie.starRating | number}}</td> + + Formats a number as text. @@ -1238,12 +1209,10 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 - ### number - The Angular `number` pipe is similar. It provides more functionality when defining the decimal places, as shown in the second example above. @@ -1255,6 +1224,7 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。 as shown in the third example. Angular还有一个`percent`管道，它把一个数组格式化为本地化的(local)百分比格式，如第三个范例所示。 +
- ### orderBy - <tr ng-repeat="movie in movieList | orderBy : 'title'"> - + <tr ng-repeat="movie in movieList | orderBy : 'title'"> + + Displays the collection in the order specified by the expression. In this example, the movie title orders the `movieList`. 使用表达式中所指定的方式对集合进行排序。 在这个例子中，`movieList`被根据movie的title排序了。 + - ### none - + ### 没了 - + For performance reasons, no comparable pipe exists in Angular. Instead, use component code to order or sort results. If you need the same ordering or sorting code in several templates, consider building a custom pipe. @@ -1298,12 +1268,8 @@ AngularJS中的很多内置过滤器在Angular中都有对应的管道。
- - {@a controllers-components} - - ## Modules/controllers/components ## 模块/控制器/组件 @@ -1323,7 +1289,6 @@ The Angular code is shown using TypeScript. 因为很多AngularJS的代码是用JavaScript写的，所以在AngularJS列显示的是JavaScript代码，而Angular列显示的是TypeScript代码。 - @@ -1337,11 +1302,15 @@ The Angular code is shown using TypeScript. @@ -1350,17 +1319,17 @@ The Angular code is shown using TypeScript. @@ -1439,19 +1407,19 @@ The Angular code is shown using TypeScript. @@ -1499,32 +1465,31 @@ The Angular code is shown using TypeScript. @@ -1545,17 +1511,17 @@ The Angular code is shown using TypeScript. @@ -1600,8 +1565,6 @@ The Angular code is shown using TypeScript. {@a style-sheets} - - ## Style sheets ## 样式表 @@ -1618,7 +1581,6 @@ also encapsulate a style sheet within a specific component. 当应用程序成长一段时间之后，应用程序中很多部分的样式会被合并，导致无法预计的后果。 在Angular中，我们仍然会为整个应用程序定义样式，不过现在也可以把样式表封装在特定的组件中。 -
+ AngularJS + + Angular +
- ### IIFE + (function () { ... }()); + - - In AngularJS, an immediately invoked function expression (or IIFE) around controller code + In AngularJS, an immediately invoked function expression (or IIFE) around controller code keeps it out of the global namespace. 在AngularJS中，用立即调用的函数表达式(IIFE)来包裹控制器代码可以让控制器代码不会污染全局命名空间。 @@ -1369,7 +1338,6 @@ The Angular code is shown using TypeScript. - ### none ### 没了 @@ -1392,45 +1360,45 @@ The Angular code is shown using TypeScript. - ### Angular modules ### Angular模块 - angular.module("movieHunter", ["ngRoute"]); - + angular.module("movieHunter", ["ngRoute"]); + + In AngularJS, an Angular module keeps track of controllers, services, and other code. The second argument defines the list of other modules that this module depends upon. 在AngularJS中，Angular模块用来对控制器、服务和其它代码进行跟踪。第二个参数定义该模块依赖的其它模块列表。 + - ### NgModules - NgModules, defined with the `NgModule` decorator, serve the same purpose: Angular的模块用`NgModule`装饰器进行定义，有如下用途： * `imports`: specifies the list of other modules that this module depends upon - `imports`: 指定当前模块依赖的其它模块列表 + `imports`: 指定当前模块依赖的其它模块列表 * `declaration`: keeps track of your components, pipes, and directives. - `declaration`: 用于记录组件、管道和指令。 + `declaration`: 用于记录组件、管道和指令。 For more information on modules, see [NgModules](guide/ngmodules). 要了解关于模块的更多知识，参见[NgModules](guide/ngmodule)。 +
- ### Controller registration - - ### 控制器注册 + + ### 控制器注册 + angular .module("movieHunter") .controller("MovieListCtrl", ["movieService", MovieListCtrl]); - + AngularJS has code in each controller that looks up an appropriate Angular module and registers the controller with that module. @@ -1467,14 +1435,12 @@ The Angular code is shown using TypeScript. - ### Component decorator ### 组件装饰器 - Angular adds a decorator to the component class to provide any required metadata. The `@Component` decorator declares that the class is a component and provides metadata about that component such as its selector (or tag) and its template. @@ -1489,7 +1455,7 @@ The Angular code is shown using TypeScript. For more information, see the [Components](guide/architecture#components) section of the [Architecture Overview](guide/architecture) page. - 要了解关于模板的更多信息，参见[架构概览](guide/architecture)中的[组件](guide/architecture#components)部分。 + 要了解关于组件的更多信息，参见[架构概览](guide/architecture)中的[组件](guide/architecture#components)部分。 - ### Controller function ### 控制器函数 + function MovieListCtrl(movieService) { } - + In AngularJS, you write the code for the model and methods in a controller function. 在Angular1中，我们在控制器函数中写模型和方法的代码。 + - ### Component class ### 组件类 - In Angular, you create a component class. 在Angular中，我们写组件类。 @@ -1537,6 +1502,7 @@ The Angular code is shown using TypeScript. section of the [Architecture Overview](guide/architecture) page. 要了解关于组件的更多信息，参见[架构概览](guide/architecture)中的[组件](guide/architecture#components)部分。 +
- ### Dependency injection ### 依赖注入 + MovieListCtrl.$inject = ['MovieService']; function MovieListCtrl(movieService) { } - + In AngularJS, you pass in any dependencies as controller function arguments. This example injects a `MovieService`. @@ -1572,14 +1538,12 @@ The Angular code is shown using TypeScript. - ### Dependency injection ### 依赖注入 - In Angular, you pass in dependencies as arguments to the component class constructor. This example injects a `MovieService`. The first parameter's TypeScript type tells Angular what to inject, even after minification. @@ -1592,6 +1556,7 @@ The Angular code is shown using TypeScript. section of the [Architecture Overview](guide/architecture). 要了解关于依赖注入的更多信息，参见[架构概览](guide/architecture)中的[依赖注入](guide/architecture#dependency-injection)部分。 +
@@ -1632,11 +1594,15 @@ also encapsulate a style sheet within a specific component. @@ -1645,27 +1611,29 @@ also encapsulate a style sheet within a specific component. + + + +
+ AngularJS + + Angular +
- ### Link tag + + ### Link 标签 - <link href="styles.css" rel="stylesheet" /> - + <link href="styles.css" rel="stylesheet" /> + + AngularJS, uses a `link` tag in the head section of the `index.html` file to define the styles for the application. 在AngularJS中，我们在`index.html`的`head`区使用`link`标签来为应用程序定义样式。 + - ### Styles configuration - + ### 样式配置 - + With the Angular CLI, you can configure your global styles in the `.angular-cli.json` file. @@ -1674,9 +1642,8 @@ also encapsulate a style sheet within a specific component. 在Angular2中，我们可以继续在`index.html`中使用link标签来为应用程序定义样式。 但是也能在组件中封装样式。 - ### StyleUrls - + In Angular, you can use the `styles` or `styleUrls` property of the `@Component` metadata to define a style sheet for a particular component. @@ -1684,7 +1651,6 @@ also encapsulate a style sheet within a specific component. - This allows you to set appropriate styles for individual components that won’t leak into other parts of the application. diff --git a/aio/content/guide/animations.md b/aio/content/guide/animations.md index d421839c90..a51d15436d 100644 --- a/aio/content/guide/animations.md +++ b/aio/content/guide/animations.md @@ -12,7 +12,7 @@ more fun but also easier to use. ## Overview -## 概述 +## 概览 Angular's animation system lets you build animations that run with the same kind of native performance found in pure CSS animations. You can also tightly integrate your @@ -21,7 +21,6 @@ animation logic with the rest of your application code, for ease of control. Angular的动画系统赋予了制作各种动画效果的能力，以构建出与原生CSS动画性能相同的动画。 我们也获得了额外的让动画逻辑与其它应用代码紧紧集成在一起的能力，这让动画可以被更容易的触发与控制。 -
Angular animations are built on top of the standard [Web Animations API](https://w3c.github.io/web-animations/) @@ -33,6 +32,7 @@ As of Angular 6, If the Web Animations API is not supported natively by the brow keyframes as a fallback instead (automatically). This means that the polyfill is no longer required unless any code uses [AnimationBuilder](/api/animations/AnimationBuilder). If your code does use AnimationBuilder, then uncomment the `web-animations-js` polyfill from the `polyfills.ts` file generated by Angular CLI. +
@@ -41,11 +41,12 @@ The examples in this page are available as a . 本章中引用的这个例子可以到去体验。 -
## Setup +## 准备工作 + Before you can add animations to your application, you need to import a few animation-specific modules and functions to the root application module. @@ -70,7 +71,6 @@ The buttons trigger changes to the list that all of the example components see a ## 快速起步范例：在两个状态间转场 - A simple transition animation You can build a simple animation that transitions an element between two states @@ -78,7 +78,7 @@ driven by a model attribute. 我们来构建一个简单的动画，它会让一个元素用模型驱动的方式在两个状态之间转场。 -Animations can be defined inside `@Component` metadata. +Animations can be defined inside `@Component` metadata. 动画会被定义在`@Component`元数据中。 @@ -88,14 +88,10 @@ With these, you can define an *animation trigger* called `heroState` in the comp metadata. It uses animations to transition between two states: `active` and `inactive`. When a hero is active, the element appears in a slightly larger size and lighter color. - 通过这些，可以在组件元数据中定义一个名叫`heroState`的*动画触发器*。它在两个状态`active`和`inactive`之间进行转场。 当英雄处于激活状态时，它会把该元素显示得稍微大一点、亮一点。 - - - - +
@@ -104,19 +100,14 @@ animation metadata. 在这个例子中，我们在元数据中用内联的方式定义了动画样式(`color`和`transform`)。在即将到来的一个Angular版本中，还将支持从组件的CSS样式表中提取样式。 -
Now, using the `[@triggerName]` syntax, attach the animation that you just defined to one or more elements in the component's template. - 我们刚刚定义了一个动画，但它还没有被用到任何地方。要想使用它，可以在模板中用`[@triggerName]`语法来把它附加到一个或多个元素上。 - - - - + Here, the animation trigger applies to every element repeated by an `ngFor`. Each of the repeated elements animates independently. The value of the @@ -128,13 +119,9 @@ attribute is bound to the expression `hero.state` and is always either `active` With this setup, an animated transition appears whenever a hero object changes state. Here's the full component implementation: - 通过这些设置，一旦英雄对象的状态发生了变化，就会触发一个转场动画。下面是完整的组件实现： - - - - + ## States and transitions @@ -154,7 +141,7 @@ component's template. 动画状态是一个由程序代码中定义的字符串值。在上面的例子中，基于英雄对象的逻辑状态,我们使用了`'active'`和`'inactive'`这两种状态。 状态的来源可以是像本例中这样简单的对象属性，也可以是由方法计算出来的值。重点是，我们得能从组件模板中读取它。 -We can define *styles* for each animation state: +You can define *styles* for each animation state: 我们可以为每个动画状态定义了*一组样式*： @@ -175,30 +162,24 @@ controls the timing of switching between one set of styles and the next:
+ In Angular animations you define states and transitions between states +
If several transitions have the same timing configuration, you can combine them into the same `transition` definition: - 如果多个转场都有同样的时间线配置，就可以把它们合并进同一个`transition`定义中： - - - - + When both directions of a transition have the same timing, as in the previous example, you can use the shorthand syntax `<=>`: - 如果要对同一个转场的两个方向都使用相同的时间线（就像前面的例子中那样），就可以使用`<=>`这种简写语法： - - - - + You can also apply a style during an animation but not keep it around after the animation finishes. You can define such styles inline, in the `transition`. In this example, @@ -206,14 +187,10 @@ the element receives one set of styles immediately and is then animated to the n When the transition finishes, none of these styles are kept because they're not defined in a `state`. - 有时希望一些样式只在动画期间生效，但在结束后并不保留它们。这时可以把这些样式内联在`transition`中进行定义。 在这个例子中，该元素会立刻获得一组样式，然后动态转场到下一个状态。当转场结束时，这些样式并不会被保留，因为它们并没有被定义在`state`中。 - - - - + ### The wildcard state `*` @@ -226,14 +203,16 @@ transitions that apply regardless of which state the animation is in. For exampl * The `active => *` transition applies when the element's state changes from `active` to anything else. - 当该元素的状态从`active`变成任何其它状态时，`active => *`转场都会生效。 + 当该元素的状态从`active`变成任何其它状态时，`active => *`转场都会生效。 * The `* => *` transition applies when *any* change between two states takes place. - 当在*任意*两个状态之间切换时，`* => *`转场都会生效。 + 当在*任意*两个状态之间切换时，`* => *`转场都会生效。 + +
-
The wildcard state can be used to match many different transitions at once +
### The `void` state @@ -251,11 +230,12 @@ leave animations. For example the `* => void` transition applies when the element leaves the view, regardless of what state it was in before it left. - 比如当一个元素离开视图时，`* => void`转场就会生效，而不管它在离场以前是什么状态。 -
+
+ The void state can be used for enter and leave transitions +
The wildcard state `*` also matches `void`. @@ -264,8 +244,7 @@ The wildcard state `*` also matches `void`. ## Example: Entering and leaving -## 例子：进场与离场 - +## 例子：进场与离场 Enter and leave animations @@ -276,18 +255,17 @@ entering and leaving of elements: * Enter: `void => *` - 进场：`void => *` + 进场：`void => *` * Leave: `* => void` - 离场：`* => void` + 离场：`* => void` For example, in the `animations` array below there are two transitions that use the `void => *` and `* => void` syntax to animate the element in and out of the view. 例如，在下面的`animations`数组中，这两个转场语句使用`void => *`和`* => void`语法来让该元素以动画形式进入和离开当前视图。 - Note that in this case the styles are applied to the void state directly in the @@ -298,7 +276,6 @@ and leaves to the right. 注意，在这个例子中，这些样式在转场定义中被直接应用到了`void`状态，但并没有一个单独的`state(void)`定义。 这么做是因为希望在进场与离场时使用不一样的转换效果：元素从左侧进场，从右侧离开。 -
These two common animations have their own aliases: @@ -306,8 +283,10 @@ These two common animations have their own aliases: 这两个常见的动画有自己的别名： + transition(':enter', [ ... ]); // void => * transition(':leave', [ ... ]); // * => void +
@@ -316,7 +295,6 @@ These two common animations have their own aliases: ## 范例：从不同的状态下进场和离场 - Enter and leave animations combined with state animations You can also combine this animation with the earlier state transition animation by @@ -328,27 +306,28 @@ is: * Inactive hero enter: `void => inactive` - 非激活英雄进场：`void => inactive` + 非激活英雄进场：`void => inactive` * Active hero enter: `void => active` - 激活英雄进场：`void => active` + 激活英雄进场：`void => active` * Inactive hero leave: `inactive => void` - 非激活英雄离场：`inactive => void` + 非激活英雄离场：`inactive => void` * Active hero leave: `active => void` - 激活英雄离场：`active => void` + 激活英雄离场：`active => void` This gives you fine-grained control over each transition: - 现在就对每一种转场都有了细粒度的控制： -
+
+ This example transitions between active, inactive, and void states +
@@ -372,7 +351,9 @@ the value as a string with the appropriate suffix: 尺寸类属性(如位置、大小、边框等)包括一个数字值和一个用来定义长度单位的后缀： * `'50px'` + * `'3em'` + * `'100%'` If you don't provide a unit when specifying dimension, Angular assumes the default of `px`: @@ -381,11 +362,11 @@ If you don't provide a unit when specifying dimension, Angular assumes the defau * `50` is the same as saying `'50px'` - `50`相当于`'50px'` + `50`相当于`'50px'` ## Automatic property calculation -## 自动属性值计算 +## 自动属性值计算 Animation with automated height calculation @@ -404,13 +385,9 @@ property is computed at runtime and then plugged into the animation. In this example, the leave animation takes whatever height the element has before it leaves and animates from that height to zero: - 这个例子中的“离场”动画会取得该元素在离场前的高度，并且把它从这个高度用动画转场到0高度： - - - - + ## Animation timing @@ -433,15 +410,15 @@ You can define a duration in three ways: * As a plain number, in milliseconds: `100` - 作为一个普通数字，以毫秒为单位，如：`100` + 作为一个普通数字，以毫秒为单位，如：`100` * In a string, as milliseconds: `'100ms'` - 作为一个字符串，以毫秒为单位，如：`'100ms'` + 作为一个字符串，以毫秒为单位，如：`'100ms'` * In a string, as seconds: `'0.1s'` - 作为一个字符串，以秒为单位，如：`'0.1s'` + 作为一个字符串，以秒为单位，如：`'0.1s'` ### Delay @@ -455,7 +432,7 @@ following the duration. It also has the same format options as the duration: * Wait for 100ms and then run for 200ms: `'0.2s 100ms'` - 等待100毫秒，然后运行200毫秒：`'0.2s 100ms'`。 + 等待100毫秒，然后运行200毫秒：`'0.2s 100ms'`。 ### Easing @@ -471,12 +448,11 @@ and the delay (or as the *second* value when there is no delay): * Wait for 100ms and then run for 200ms, with easing: `'0.2s 100ms ease-out'` - 等待100毫秒，然后运行200毫秒，并且带缓动：`'0.2s 100ms ease-out'` + 等待100毫秒，然后运行200毫秒，并且带缓动：`'0.2s 100ms ease-out'` * Run for 200ms, with easing: `'0.2s ease-in-out'` - 运行200毫秒，并且带缓动：`'0.2s ease-in-out'` - + 运行200毫秒，并且带缓动：`'0.2s ease-in-out'` Animations with specific timings @@ -488,20 +464,14 @@ Here are a couple of custom timings in action. Both enter and leave last for 200 milliseconds, that is `0.2s`, but they have different easings. The leave begins after a slight delay of 10 milliseconds as specified in `'0.2s 10 ease-out'`: - - 这里是两个自定义时间线的动态演示。“进场”和“离场”都持续200毫秒，也就是`0.2s`，但它们有不同的缓动函数。“离场”动画会在100毫秒的延迟之后开始，也就是`'0.2s 10 ease-out'`： - - - - + ## Multi-step animations with keyframes ## 基于关键帧(Keyframes)的多阶段动画 - Animations with some bounce implemented with keyframes Animation *keyframes* go beyond a simple transition to a more intricate animation @@ -518,13 +488,9 @@ which marks the beginning of the animation, and one, which marks the end. This example adds some "bounce" to the enter and leave animations with keyframes: - 在这个例子中，我们使用关键帧来为进场和离场动画添加一些“反弹效果”： - - - - + Note that the offsets are *not* defined in terms of absolute time. They are relative measures from zero to one. The final timeline of the animation is based on the combination @@ -538,10 +504,9 @@ offsets receive offsets `0`, `0.5`, and `1`. 为关键帧定义偏移量是可选的。如果省略它们，偏移量会自动根据帧数平均分布出来。例如，三个未定义过偏移量的关键帧会分别获得偏移量：`0`、`0.5`和`1`。 - ## Parallel animation groups -## 并行动画组(Group) +## 并行动画组(Group) Parallel animations with different timings, implemented with groups @@ -560,20 +525,15 @@ For this you can use animation *groups*. In this example, using groups both on enter and leave allows for two different timing configurations. Both are applied to the same element in parallel, but run independently of each other: - 这种情况下就可以用动画*组*来解决了。在这个例子中，我们同时在进场和离场时使用了组，以便能让它们使用两种不同的时间线配置。 它们被同时应用到同一个元素上，但又彼此独立运行： - - - - + One group animates the element transform and width; the other group animates the opacity. 其中一个动画组对元素的`transform`和`width`做动画，另一个组则对`opacity`做动画。 - ## Animation callbacks ## 动画回调 @@ -585,7 +545,7 @@ A callback is fired when an animation is started and also when it is done. In the keyframes example, you have a `trigger` called `@flyInOut`. You can hook those callbacks like this: -对于例子中的这个关键帧，我们有一个叫做`@flyInOut`的`trigger`。在那里我们可以挂钩到那些回调，比如： +对于例子中的这个关键帧，我们有一个叫做`@flyInOut`的`trigger`。在那里我们可以挂钩到那些回调，比如： @@ -596,4 +556,5 @@ The callbacks receive an `AnimationEvent` that contains useful properties such a Those callbacks will fire whether or not an animation is picked up. -无论动画是否实际执行过，那些回调都会触发。 + +无论动画是否实际执行过，那些回调都会触发。 \ No newline at end of file diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md index 16ac355483..5db3fc288e 100644 --- a/aio/content/guide/aot-compiler.md +++ b/aio/content/guide/aot-compiler.md @@ -13,7 +13,7 @@ This guide explains how to build with the AOT compiler using different compiler Watch compiler author Tobias Bosch explain the Angular Compiler at AngularConnect 2016. 观看 Angular 编译器的作者Tobias Bosch 在 AngularConnect 2016 上对编译器的解释。 - + {@a overview} @@ -29,13 +29,16 @@ the components and templates must be converted to executable JavaScript by an _A Angular offers two ways to compile your application: 1. **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime + 1. **_Ahead-of-Time_ (AOT)**, which compiles your app at build time. JIT compilation is the default when you run the _build-only_ or the _build-and-serve-locally_ CLI commands: + ng build ng serve + {@a compile} @@ -43,8 +46,10 @@ JIT compilation is the default when you run the _build-only_ or the _build-and-s For AOT compilation, append the `--aot` flags to the _build-only_ or the _build-and-serve-locally_ CLI commands: + ng build --aot ng serve --aot +
@@ -288,7 +293,6 @@ rules. *Note*: Is it not recommended to use this option as it is not yet feature complete with the Render2 code generation. - ## Angular Metadata and AOT ## Angular 元数据与 AOT @@ -339,15 +343,15 @@ You write metadata in a _subset_ of TypeScript that must conform to the followin 1. Limit [expression syntax](#expression-syntax) to the supported subset of JavaScript. [表达式语法](#expression-syntax)只支持 JavaScript 的一个有限的子集。 - + 2. Only reference exported symbols after [code folding](#folding). 只能引用[代码收缩](#folding)后导出的符号。 - + 3. Only call [functions supported](#supported-functions) by the compiler. 只能调用编译器[支持的那些函数](#supported-functions)。 - + 4. Decorated and data-bound class members must be public. 被装饰和用于数据绑定的类成员必须是公共（public）的。 @@ -390,6 +394,7 @@ Angular 的 [schema.ts](https://github.com/angular/angular/blob/master/packages/
{@a expression-syntax} + ### Expression syntax The _collector_ only understands a subset of JavaScript. @@ -427,7 +432,7 @@ piece of metadata to generate the application code. If you want `ngc` to report syntax errors immediately rather than produce a `.metadata.json` file with errors, set the `strictMetadataEmit` option in `tsconfig`. -如果你希望`ngc`立即汇报这些语法错误，而不要生成带有错误信息的`.metadata.json`文件，可以到`tsconfig`中设置 `strictMetadataEmit` 选项。 + 如果你希望`ngc`立即汇报这些语法错误，而不要生成带有错误信息的`.metadata.json`文件，可以到`tsconfig`中设置 `strictMetadataEmit` 选项。 ``` "angularCompilerOptions": { @@ -444,6 +449,7 @@ Angular 库通过这个选项来确保所有的 `.metadata.json` 文件都是干 {@a function-expression} {@a arrow-functions} + ### No arrow functions The AOT compiler does not support [function expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function) @@ -479,6 +485,7 @@ export function serverFactory() { Beginning in version 5, the compiler automatically performs this rewritting while emitting the `.js` file. {@a function-calls} + ### Limited function calls The _collector_ can represent a function call or object creation with `new` as long as the syntax is valid. The _collector_ only cares about proper syntax. @@ -486,8 +493,8 @@ The _collector_ can represent a function call or object creation with `new` as l But beware. The compiler may later refuse to generate a call to a _particular_ function or creation of a _particular_ object. The compiler only supports calls to a small set of functions and will use `new` for only a few designated classes. These functions and classes are in a table of [below](#supported-functions). - ### Folding + {@a exported-symbols} The compiler can only resolve references to **_exported_** symbols. Fortunately, the _collector_ enables limited use of non-exported symbols through _folding_. @@ -578,7 +585,6 @@ Parentheses | yes, if the expression is foldable If an expression is not foldable, the collector writes it to `.metadata.json` as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) for the compiler to resolve. - ## Phase 2: code generation The _collector_ makes no attempt to understand the metadata that it collects and outputs to `.metadata.json`. It represents the metadata as best it can and records errors when it detects a metadata syntax violation. @@ -607,7 +613,6 @@ export class AppComponent { {@a supported-functions} Most importantly, the compiler only generates code to create instances of certain classes, support certain decorators, and call certain functions from the following lists. - ### New instances The compiler only allows metadata that create instances of the class `InjectionToken` from `@angular/core`. @@ -637,7 +642,6 @@ Decorator | Module `SkipSelf` | `@angular/core` `ViewChild` | `@angular/core` - ### Macro-functions and macro-static methods The compiler also supports _macros_ in the form of functions or static @@ -685,8 +689,6 @@ for these methods to see how macros can simplify configuration of complex [NgMod The compiler treats object literals containing the fields `useClass`, `useValue`, `useFactory`, and `data` specially. The compiler converts the expression initializing one of these fields into an exported variable, which replaces the expression. This process of rewriting these expressions removes all the restrictions on what can be in them because the compiler doesn't need to know the expression's value—it just needs to be able to generate a reference to the value. - - You might write something like: ```typescript @@ -722,7 +724,6 @@ factory without having to know what the value of `ɵ0` contains. The compiler does the rewriting during the emit of the `.js` file. This doesn't rewrite the `.d.ts` file, however, so TypeScript doesn't recognize it as being an export. Thus, it does not pollute the ES module's exported API. - ## Metadata Errors The following are metadata errors you may encounter, with explanations and suggested corrections. @@ -770,6 +771,7 @@ and be wary of new or unusual TypeScript features.
{@a reference-to-a-local-symbol} +

Reference to a local (non-exported) symbol

@@ -808,7 +810,8 @@ The compiler will [fold](#folding) the expression into the provider as if you ha ``` providers: [ { provide: Foo, useValue: 42 } - ]``` + ] +``` Alternatively, you can fix it by exporting `foo` with the expectation that `foo` will be assigned at runtime when you actually know its value. @@ -850,6 +853,7 @@ Prefixing the declaration with `export` merely produces a new error, "[`Only ini
{@a only-initialized-variables} +

Only initialized variables and constants

@@ -946,6 +950,7 @@ export abstract class MyStrategy { } ] ... ``` +

Reference to a non-exported function

@@ -979,9 +984,11 @@ export function myStrategy() { ... } ] ... ``` +
{@a function-calls-not-supported} +

Function calls are not supported

@@ -1017,6 +1024,7 @@ import { calculateValue } from './utilities'; To correct this error, export a function from the module and refer to the function in a `useFactory` provider instead. + // CORRECTED import { calculateValue } from './utilities'; @@ -1032,11 +1040,13 @@ export function someValueFactory() { { provide: SomeValue, useFactory: someValueFactory } ] ... +
{@a destructured-variable-not-supported} +

Destructured variable or constant not supported

@@ -1050,6 +1060,7 @@ The compiler does not support references to variables assigned by [destructuring For example, you cannot write something like this: + // ERROR import { configuration } from './configuration'; @@ -1061,11 +1072,13 @@ const {foo, bar} = configuration; {provide: Bar, useValue: bar}, ] ... + To correct this error, refer to non-destructured values. + // CORRECTED import { configuration } from './configuration'; ... @@ -1074,6 +1087,7 @@ import { configuration } from './configuration'; {provide: Bar, useValue: configuration.bar}, ] ... +
@@ -1106,13 +1120,17 @@ If you must inject an instance of an ambiant type, you can finesse the problem in four steps: 1. Create an injection token for an instance of the ambiant type. + 1. Create a factory function that returns that instance. + 1. Add a `useFactory` provider with that factory function. + 1. Use `@Inject` to inject the instance. Here's an illustrative example. + // CORRECTED import { Inject } from '@angular/core'; @@ -1128,6 +1146,7 @@ export function _window() { return window; } export class MyComponent { constructor (@Inject(WINDOW) private win: Window) { ... } } + The `Window` type in the constructor is no longer a problem for the compiler because it @@ -1136,14 +1155,17 @@ uses the `@Inject(WINDOW)` to generate the injection code. Angular does something similar with the `DOCUMENT` token so you can inject the browser's `document` object (or an abstraction of it, depending upon the platform in which the application runs). + import { Inject } from '@angular/core'; import { DOCUMENT } from '@angular/platform-browser'; @Component({ ... }) -export classMyComponent { +export class MyComponent { constructor (@Inject(DOCUMENT) private doc: Document) { ... } } + +

Name expected

@@ -1173,6 +1195,7 @@ that you referenced in metadata. The compiler can understand simple enum values but not complex values such as those derived from computed properties. + // ERROR enum Colors { Red = 1, @@ -1187,6 +1210,7 @@ enum Colors { { provide: StrongColor, useValue: Colors.Blue } // bad ] ... + Avoid referring to enums with complicated initializers or computed properties. @@ -1194,6 +1218,7 @@ Avoid referring to enums with complicated initializers or computed properties.
{@a tagged-template-expressions-not-supported} +

Tagged template expressions are not supported

@@ -1308,7 +1333,6 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there]( guard to the use of its template, implying that the template will only be instantiated if the `ngIf` input property is true. - ### Non-null type assertion operator Use the [non-null type assertion operator](guide/template-syntax#non-null-assertion-operator) @@ -1378,12 +1402,21 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there]( person?: Person; } ``` + ## Summary +## 小结 + * What the AOT compiler does and why it is important. + * Why metadata must be written in a subset of JavaScript. + * What that subset is. + * Other restrictions on metadata definition. + * Macro-functions and macro-static methods. + * Compiler errors related to metadata. + * Validation of binding expressions diff --git a/aio/content/guide/api-page-class.md b/aio/content/guide/api-page-class.md index 989bd0f327..58c413c75e 100644 --- a/aio/content/guide/api-page-class.md +++ b/aio/content/guide/api-page-class.md @@ -1,175 +1,349 @@ + +
+ API / @core +
+
+

Class Name

+
+
+ +
+

Class description goes here. This is a short and to the point one or two sentence description that easily introduces the reader to the class.

+
+
+

Overview

+ 
+
         class Compiler {
+
     compileModuleSync<T>(moduleType: Type<T>): NgModuleFactory<T>
+
     compileModuleAsync<T>(moduleType: Type<T>): Promise<NgModuleFactory<T>>
+
     compileModuleAndAllComponentsSync<T>(moduleType: Type<T>): ModuleWithComponentFactories<T>
+
     compileModuleAndAllComponentsAsync<T>(moduleType: Type<T>): Promise<ModuleWithComponentFactories<T>>
+
     clearCache(): void
+
     clearCacheFor(type: Type<any>)
+
     }
+
+
+
+

Description

+

The longer class description goes here which can include multiple paragraphs.

+

Bacon ipsum dolor amet pork belly capicola sirloin venison alcatra ground round ham hock jowl turkey picanha bresaola pancetta brisket chicken fatback. Burgdoggen kevin salami jowl shoulder jerky leberkas meatball. Ham hock picanha burgdoggen pork belly rump bacon cupim. Bacon kielbasa sirloin shank strip steak ground round. Bresaola cow salami meatloaf pork chop leberkas flank turducken biltong meatball chuck pork tri-tip chicken. Ribeye corned beef shoulder, meatloaf strip steak jerky porchetta capicola alcatra ham.

+

Subclasses

+ +

See Also

+ +
+
+

Constructor

+ + 
   
+
         constructor(element: any, keyframes: {
+
         [key: string]: string | number;
+
     }[], duration: number, delay: number, easing: string, previousPlayers: any[])
+
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
+ Property1 + Description goes here
+ Property2 + TypeDescription goes here
+ Property3 + TypeDescription goes here
+
+
+

Methods

+ + + + + + + + + + + +
Method1Name( )
+

Description goes here

+
+

Bacon ipsum dolor amet pork belly capicola sirloin venison alcatra ground round ham hock jowl turkey picanha bresaola pancetta brisket chicken fatback. Burgdoggen kevin salami jowl shoulder jerky leberkas meatball. Ham hock picanha burgdoggen pork belly rump bacon cupim. Bacon kielbasa sirloin shank strip steak ground round. Bresaola cow salami meatloaf pork chop leberkas flank turducken biltong meatball chuck pork tri-tip chicken. Ribeye corned beef shoulder, meatloaf strip steak jerky porchetta capicola alcatra ham.

+
+ + + + + + + + + + + +
Method2Name( )
+

Description goes here

+
+
Declaration
+ + 
+
                     class AnimationBuilder {build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory}
+ + +
Parameters
+
Returns
+

Returns information and results goes here.

+
Errors
+

Error information goes here

+
+

Further details provided as needed. Bacon ipsum dolor amet pork belly capicola sirloin venison alcatra ground round ham hock jowl turkey picanha bresaola pancetta brisket chicken fatback. Burgdoggen kevin salami jowl shoulder jerky leberkas meatball.

+
Overloads
+ + + + + + + + + + + +
+ + 
   
+
         constructor(element: any, keyframes: {
+
         [key: string]: string | number;
+
     }[], duration: number, delay: number, easing: string, previousPlayers: any[])
+
+ 		Description goes here
+ + 
   
+
         constructor(element: any, keyframes: {
+
         [key: string]: string | number;
+
     }[], duration: number, delay: number, easing: string, previousPlayers: any[])
+
+ 		Description goes here
+
+
Example: Descriptive Title of Method Example
+

Bacon ipsum dolor amet pork belly capicola sirloin venison alcatra ground round ham hock jowl turkey picanha bresaola pancetta brisket chicken fatback. Burgdoggen kevin salami jowl shoulder jerky leberkas meatball. Ham hock picanha burgdoggen pork belly rump bacon cupim. Bacon kielbasa sirloin shank strip steak ground round. Bresaola cow salami meatloaf pork chop leberkas flank turducken biltong meatball chuck pork tri-tip chicken. Ribeye corned beef shoulder, meatloaf strip steak jerky porchetta capicola alcatra ham.

+
+
+
+

Example: Descriptive Title of Combined Example Goes Here

+

Intro description text about what the example is and how it can be used.

+ + 
   
+
         constructor(element: any, keyframes: {
+
         [key: string]: string | number;
+
     }[], duration: number, delay: number, easing: string, previousPlayers: any[])
+
+

Further explanation provided as needed. Bacon ipsum dolor amet pork belly capicola sirloin venison alcatra ground round ham hock jowl turkey picanha bresaola pancetta brisket chicken fatback. Burgdoggen kevin salami jowl shoulder jerky leberkas meatball.

+
+
\ No newline at end of file diff --git a/aio/content/guide/architecture.md b/aio/content/guide/architecture.md index 5d16cf31db..20a2f9efa1 100644 --- a/aio/content/guide/architecture.md +++ b/aio/content/guide/architecture.md @@ -11,7 +11,6 @@ The framework consists of several libraries, some of them core and some optional 该框架包括一系列库，有些是核心库，有些是可选库。 - You write Angular applications by composing HTML *templates* with Angularized markup, writing *component* classes to manage those templates, adding application logic in *services*, and boxing components and services in *modules*. @@ -32,30 +31,25 @@ You'll learn the details in the pages that follow. For now, focus on the big pic 当然，这只是冰山一角。后面我们将学习更多的细节。不过，目前我们还是先关注全景图吧。 -
+ overview +
The code referenced on this page is available as a . -

本章所引用的代码见。 -

- - - +
## Modules ## 模块 - -模块 - +Component Angular apps are modular and Angular has its own modularity system called _NgModules_. @@ -69,7 +63,7 @@ _Angular 模块_很重要。这里只是简单介绍，在 [Angular 模块](guid
-Every Angular app has at least one NgModule class, [the _root module_](guide/bootstrapping "Bootstrapping"), +Every Angular app has at least one NgModule class, [the _root module_](guide/bootstrapping "Bootstrapping"), conventionally named `AppModule`. 每个 Angular 应用至少有一个模块（[_根模块_](guide/bootstrapping "引导启动")），习惯上命名为`AppModule`。 @@ -84,7 +78,6 @@ An NgModule, whether a _root_ or _feature_, is a class with an `@NgModule` decor Angular 模块（无论是_根模块_还是_特性模块_）都是一个带有`@NgModule`装饰器的类。 -
Decorators are functions that modify JavaScript classes. @@ -93,11 +86,10 @@ Angular 模块（无论是_根模块_还是_特性模块_）都是一个带有`@ Learn more about decorators on the web. -装饰器是用来修饰 JavaScript 类的函数。 + 装饰器是用来修饰 JavaScript 类的函数。 Angular 有很多装饰器，它们负责把元数据附加到类上，以了解那些类的设计意图以及它们应如何工作。 关于装饰器的更多信息。 -
`NgModule` is a decorator function that takes a single metadata object whose properties describe the module. @@ -108,30 +100,29 @@ The most important properties are: * `declarations` - the _view classes_ that belong to this module. Angular has three kinds of view classes: [components](guide/architecture#components), [directives](guide/architecture#directives), and [pipes](guide/pipes). - `declarations` - 声明本模块中拥有的_视图类_。Angular 有三种视图类：[组件](guide/architecture#components)、[指令](guide/architecture#directives)和[管道](guide/pipes)。 + `declarations` - 声明本模块中拥有的_视图类_。Angular 有三种视图类：[组件](guide/architecture#components)、[指令](guide/architecture#directives)和[管道](guide/pipes)。 * `exports` - the subset of declarations that should be visible and usable in the component [templates](guide/architecture#templates) of other modules. - `exports` - declarations 的子集，可用于其它模块的组件[模板](guide/architecture#templates)。 - + `exports` - declarations 的子集，可用于其它模块的组件[模板](guide/architecture#templates)。 + * `imports` - other modules whose exported classes are needed by component templates declared in _this_ module. - `imports` - _本_模块声明的组件模板需要的类所在的其它模块。 - + `imports` - _本_模块声明的组件模板需要的类所在的其它模块。 + * `providers` - creators of [services](guide/architecture#services) that this module contributes to - the global collection of services; they become accessible in all parts of the app. +the global collection of services; they become accessible in all parts of the app. + + `providers` - [服务](guide/architecture#services)的创建者，并加入到全局服务列表中，可用于应用任何部分。 - `providers` - [服务](guide/architecture#services)的创建者，并加入到全局服务列表中，可用于应用任何部分。 - * `bootstrap` - the main application view, called the _root component_, - that hosts all other app views. Only the _root module_ should set this `bootstrap` property. +that hosts all other app views. Only the _root module_ should set this `bootstrap` property. + + `bootstrap` - 指定应用的主视图（称为_根组件_），它是所有其它视图的宿主。只有_根模块_才能设置`bootstrap`属性。 - `bootstrap` - 指定应用的主视图（称为_根组件_），它是所有其它视图的宿主。只有_根模块_才能设置`bootstrap`属性。 - Here's a simple root module: 下面是一个简单的根模块： - @@ -139,8 +130,7 @@ Here's a simple root module: The `export` of `AppComponent` is just to show how to use the `exports` array to export a component; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module. -`AppComponent`的`export`语句只是用于演示如何导出的，它在这个例子中并不是必须的。根模块不需要_导出_任何东西，因为其它组件不需要导入根模块。 - + `AppComponent`的`export`语句只是用于演示如何导出的，它在这个例子中并不是必须的。根模块不需要_导出_任何东西，因为其它组件不需要导入根模块。
@@ -150,7 +140,6 @@ During development you're likely to bootstrap the `AppModule` in a `main.ts` fil 我们通过_引导_根模块来启动应用。 在开发期间，你通常在一个`main.ts`文件中引导`AppModule`，就像这样： - ### NgModules vs. JavaScript modules @@ -166,7 +155,7 @@ It's completely different and unrelated to the NgModule system. JavaScript 也有自己的模块系统，用来管理一组 JavaScript 对象。 它与 Angular 的模块系统完全不同且完全无关。 - + In JavaScript each _file_ is a module and all objects defined in the file belong to that module. The module declares some objects to be public by marking them with the `export` key word. Other JavaScript modules use *import statements* to access public objects from other modules. @@ -181,18 +170,16 @@ JavaScript 中，每个_文件_是一个模块，文件中定义的所有对象
+ Learn more about the JavaScript module system on the web. + 学习更多关于 JavaScript 模块的知识。 -Learn more about the JavaScript module system on the web. - -学习更多关于 JavaScript 模块的知识。
These are two different and _complementary_ module systems. Use them both to write your apps. 这两个模块化系统是互补的，我们在写程序时都会用到。 - ### Angular libraries ### Angular 模块库 @@ -204,18 +191,19 @@ Angular ships as a collection of JavaScript modules. You can think of them as li Angular 提供了一组 JavaScript 模块。可以把它们看做库模块。 Each Angular library name begins with the `@angular` prefix. - + 每个 Angular 库的名字都带有`@angular`前缀。 You install them with the **npm** package manager and import parts of them with JavaScript `import` statements. -用 **npm** 包管理工具安装它们，用 JavaScript 的`import`语句导入其中某些部件。
+用 **npm** 包管理工具安装它们，用 JavaScript 的`import`语句导入其中某些部件。 + +
For example, import Angular's `Component` decorator from the `@angular/core` library like this: 例如，象下面这样，从`@angular/core`库中导入`Component`装饰器： - You also import NgModules from Angular _libraries_ using JavaScript import statements: @@ -227,7 +215,6 @@ You also import NgModules from Angular _libraries_ using JavaScript import state In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this. 在上面那个简单的根模块的例子中，应用模块需要`BrowserModule`的某些素材。要访问这些素材，就得把它加入`@NgModule`元数据的`imports`中，就像这样： - @@ -240,14 +227,11 @@ Hang in there. The confusion yields to clarity with time and experience. 这两个系统比较容易混淆，因为它们共享相同的词汇 “imports” 和 “exports”。不过没关系，先放一放，随着时间和经验的增长，自然就清楚了。 -
+ Learn more from the [NgModules](guide/ngmodules) page. - -Learn more from the [NgModules](guide/ngmodules) page. - -更多信息，见 [Angular 模块](guide/ngmodule)。 + 更多信息，见 [Angular 模块](guide/ngmodule)。
@@ -269,15 +253,15 @@ For example, the following views are controlled by components: * The app root with the navigation links. - 带有导航链接的应用根组件。 + 带有导航链接的应用根组件。 * The list of heroes. - 英雄列表。 + 英雄列表。 * The hero editor. - 英雄编辑器。 + 英雄编辑器。 You define a component's application logic—what it does to support the view—inside a class. The class interacts with the view through an API of properties and methods. @@ -294,10 +278,7 @@ that it acquires from a service. 例如，`HeroListComponent`有一个`heroes`属性，它返回一个英雄数组，这个数组从一个服务获得。 `HeroListComponent`还有一个当用户从列表中点选一个英雄时设置`selectedHero`属性的`selectHero()`方法。 - - - - + Angular creates, updates, and destroys components as the user moves through the application. Your app can take action at each moment in this lifecycle through optional [lifecycle hooks](guide/lifecycle-hooks), like `ngOnInit()` declared above. @@ -305,15 +286,13 @@ Your app can take action at each moment in this lifecycle through optional [life 当用户在这个应用中漫游时， Angular 会创建、更新和销毁组件。 应用可以通过[生命周期钩子](guide/lifecycle-hooks)在组件生命周期的各个时间点上插入自己的操作，例如上面声明的`ngOnInit()`。 -
## Templates ## 模板 - -模板 +Template You define a component's view with its companion **template**. A template is a form of HTML that tells Angular how to render the component. @@ -323,13 +302,9 @@ that tells Angular how to render the component. A template looks like regular HTML, except for a few differences. Here is a template for our `HeroListComponent`: - 多数情况下，模板看起来很像标准 HTML，当然也有一点不同的地方。下面是`HeroListComponent`组件的一个模板： - - - - + Although this template uses typical HTML elements like `

` and `

`, it also has some differences. Code like `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `` uses Angular's [template syntax](guide/template-syntax). @@ -362,12 +337,12 @@ Notice how `` rests comfortably among native HTML elements. Cus ## 元数据 - -元数据 +Metadata Metadata tells Angular how to process a class. -

元数据告诉 Angular 如何处理一个类。

+元数据告诉 Angular 如何处理一个类。 +
[Looking back at the code](guide/architecture#component-code) for `HeroListComponent`, you can see that it's just a class. @@ -387,21 +362,16 @@ To tell Angular that `HeroListComponent` is a component, attach **metadata** to In TypeScript, you attach metadata by using a **decorator**. Here's some metadata for `HeroListComponent`: - 在TypeScript中，我们用**装饰器 (decorator) **来附加元数据。 下面就是`HeroListComponent`的一些元数据。 - - - - + Here is the `@Component` decorator, which identifies the class immediately below it as a component class. 这里看到`@Component`装饰器，它把紧随其后的类标记成了组件类。 - The `@Component` decorator takes a required configuration object with the information Angular needs to create and present the component and its view. @@ -411,25 +381,23 @@ Here are a few of the most useful `@Component` configuration options: `@Component`的配置项包括： - * `selector`: CSS selector that tells Angular to create and insert an instance of this component where it finds a `` tag in *parent* HTML. For example, if an app's HTML contains ``, then Angular inserts an instance of the `HeroListComponent` view between those tags. - `selector`： CSS 选择器，它告诉 Angular 在*父级* HTML 中查找``标签，创建并插入该组件。 + `selector`： CSS 选择器，它告诉 Angular 在*父级* HTML 中查找``标签，创建并插入该组件。 例如，如果应用的 HTML 包含``， Angular 就会把`HeroListComponent`的一个实例插入到这个标签中。 * `templateUrl`: module-relative address of this component's HTML template, shown [above](guide/architecture#templates). - `templateUrl`：组件 HTML 模板的模块相对地址，[如前所示](guide/architecture#templates)。 - + `templateUrl`：组件 HTML 模板的模块相对地址，[如前所示](guide/architecture#templates)。 * `providers`: array of **dependency injection providers** for services that the component requires. This is one way to tell Angular that the component's constructor requires a `HeroService` so it can get the list of heroes to display. - `providers` - 组件所需服务的*依赖注入提供商*数组。 + `providers` - 组件所需服务的*依赖注入提供商*数组。 这是在告诉 Angular：该组件的构造函数需要一个`HeroService`服务，这样组件就可以从服务中获得英雄数据。 Metadata @@ -455,12 +423,11 @@ so that Angular knows what to do. 这种架构处理方式是：你向代码中添加元数据，以便 Angular 知道该怎么做。 -
## Data binding -## 数据绑定 +## 数据绑定 (data binding) Without a framework, you would be responsible for pushing data values into the HTML controls and turning user responses into actions and value updates. Writing such push/pull logic by hand is tedious, error-prone, and a nightmare to @@ -469,8 +436,7 @@ read as any experienced jQuery programmer can attest. 如果没有框架，我们就得自己把数据值推送到 HTML 控件中，并把用户的反馈转换成动作和值更新。 如果手工写代码来实现这些推/拉逻辑，肯定会枯燥乏味、容易出错，读起来简直是噩梦 —— 写过 jQuery 的程序员大概都对此深有体会。 - -数据绑定 +Data Binding Angular supports **data binding**, a mechanism for coordinating parts of a template with parts of a component. @@ -487,40 +453,32 @@ As the diagram shows, there are four forms of data binding syntax. Each form has The `HeroListComponent` [example](guide/architecture#templates) template has three forms: - `HeroListComponent`[示例](guide/architecture#templates)模板中有三种形式： - - - - + * The `{{hero.name}}` [*interpolation*](guide/displaying-data#interpolation) displays the component's `hero.name` property value within the `
  • ` element. - `{{hero.name}}`[*插值表达式*](guide/displaying-data#interpolation)在`
  • `标签中显示组件的`hero.name`属性的值。 + `{{hero.name}}`[*插值表达式*](guide/displaying-data#interpolation)在`
  • `标签中显示组件的`hero.name`属性的值。 * The `[hero]` [*property binding*](guide/template-syntax#property-binding) passes the value of `selectedHero` from the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`. - `[hero]`[*属性绑定*](guide/template-syntax#property-binding)把父组件`HeroListComponent`的`selectedHero`的值传到子组件`HeroDetailComponent`的`hero`属性中。 + `[hero]`[*属性绑定*](guide/template-syntax#property-binding)把父组件`HeroListComponent`的`selectedHero`的值传到子组件`HeroDetailComponent`的`hero`属性中。 * The `(click)` [*event binding*](guide/user-input#click) calls the component's `selectHero` method when the user clicks a hero's name. - `(click)` [*事件绑定*](guide/user-input#click)在用户点击英雄的名字时调用组件的`selectHero`方法。 + `(click)` [*事件绑定*](guide/user-input#click)在用户点击英雄的名字时调用组件的`selectHero`方法。 **Two-way data binding** is an important fourth form that combines property and event binding in a single notation, using the `ngModel` directive. Here's an example from the `HeroDetailComponent` template: - **双向数据绑定**是重要的第四种绑定形式，它使用`ngModel`指令组合了属性绑定和事件绑定的功能。 下面是`HeroDetailComponent`模板的范例： - - - - + In two-way binding, a data property value flows to the input box from the component as with property binding. The user's changes also flow back to the component, resetting the property to the latest value, @@ -533,18 +491,20 @@ from the root of the application component tree through all child components. Angular 在每个 JavaScript 事件循环中处理*所有的*数据绑定，它会从组件树的根部开始，递归处理全部子组件。 -
    - 数据绑定 + + Data Binding +
    Data binding plays an important role in communication between a template and its component. 数据绑定在模板与对应组件的交互中扮演了重要的角色。 -
    - 父/子绑定 + + Parent/Child binding +
    Data binding is also important for communication between parent and child components. @@ -555,10 +515,9 @@ Data binding is also important for communication between parent and child compon ## Directives -## 指令 (directive) +## 指令 - -父与子 +Parent child Angular templates are *dynamic*. When Angular renders them, it transforms the DOM according to the instructions given by **directives**. @@ -571,14 +530,12 @@ a `@Component` decorator is actually a `@Directive` decorator extended with temp 组件是一个*带模板的指令*；`@Component`装饰器实际上就是一个`@Directive`装饰器，只是扩展了一些面向模板的特性。 -
    While **a component is technically a directive**, components are so distinctive and central to Angular applications that this architectural overview separates components from directives. -虽然**严格来说组件就是一个指令**，但是组件非常独特，并在 Angular 中位于中心地位，所以在架构概览中，我们把组件从指令中独立了出来。 - + 虽然**严格来说组件就是一个指令**，但是组件非常独特，并在 Angular 中位于中心地位，所以在架构概览中，我们把组件从指令中独立了出来。
    @@ -598,22 +555,17 @@ sometimes by name but more often as the target of an assignment or a binding. The [example template](guide/architecture#templates) uses two built-in structural directives: - 下面的[范例模板](guide/architecture#templates)中用到了两个内置的结构型指令： - - - - + * [`*ngFor`](guide/displaying-data#ngFor) tells Angular to stamp out one `
  • ` per hero in the `heroes` list. - [`*ngFor`](guide/displaying-data#ngFor)告诉 Angular 为`heroes`列表中的每个英雄生成一个`
  • `标签。 + [`*ngFor`](guide/displaying-data#ngFor)告诉 Angular 为`heroes`列表中的每个英雄生成一个`
  • `标签。 * [`*ngIf`](guide/displaying-data#ngIf) includes the `HeroDetail` component only if a selected hero exists. - [`*ngIf`](guide/displaying-data#ngIf)表示只有在选择的英雄存在时，才会包含`HeroDetail`组件。 - + [`*ngIf`](guide/displaying-data#ngIf)表示只有在选择的英雄存在时，才会包含`HeroDetail`组件。 **Attribute** directives alter the appearance or behavior of an existing element. In templates they look like regular HTML attributes, hence the name. @@ -626,14 +578,10 @@ an example of an attribute directive. `ngModel` modifies the behavior of an existing element (typically an ``) by setting its display value property and responding to change events. - `ngModel`指令就是属性型指令的一个例子，它实现了双向数据绑定。 `ngModel`修改现有元素（一般是``）的行为：设置其显示属性值，并响应 change 事件。 - - - - + Angular has a few more directives that either alter the layout structure (for example, [ngSwitch](guide/template-syntax#ngSwitch)) @@ -648,6 +596,7 @@ Of course, you can also write your own directives. Components such as 当然，我们也能编写自己的指令。像`HeroListComponent`这样的组件就是一种自定义指令。 +
    @@ -675,23 +624,23 @@ Examples include: * logging service - 日志服务 + 日志服务 * data service - 数据服务 + 数据服务 * message bus - 消息总线 + 消息总线 * tax calculator - 税款计算器 + 税款计算器 * application configuration - 应用程序配置 + 应用程序配置 There is nothing specifically _Angular_ about services. Angular has no definition of a service. There is no service base class, and no place to register a service. @@ -705,25 +654,17 @@ Yet services are fundamental to any Angular application. Components are big cons Here's an example of a service class that logs to the browser console: - 下面是一个服务类的范例，用于把日志记录到浏览器的控制台： - - - - + Here's a `HeroService` that uses a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to fetch heroes. The `HeroService` depends on the `Logger` service and another `BackendService` that handles the server communication grunt work. - 下面是`HeroService`类，用于获取英雄数据，并通过一个已解析的[承诺 (Promise)](http://exploringjs.com/es6/ch_promises.html) 返回它们。 `HeroService`还依赖于`Logger`服务和另一个用于处理服务器通讯的`BackendService`服务。 - - - - + Services are everywhere. @@ -755,12 +696,11 @@ application logic into services and make those services available to components Angular 帮助我们*遵循*这些原则 —— 它让我们能轻易地把应用逻辑拆分到服务，并通过*依赖注入*来在组件中使用这些服务。 -
    ## Dependency injection -## 依赖注入 +## 依赖注入（dependency injection） Service @@ -769,7 +709,9 @@ with the fully-formed dependencies it requires. Most dependencies are services. Angular uses dependency injection to provide new components with the services they need. “依赖注入”是提供类的新实例的一种方式，还负责处理好类所需的全部依赖。大多数依赖都是服务。 -Angular 使用依赖注入来提供新组件以及组件所需的服务。
    +Angular 使用依赖注入来提供新组件以及组件所需的服务。 + +
    Angular can tell which services a component needs by looking at the types of its constructor parameters. For example, the constructor of your `HeroListComponent` needs a `HeroService`: @@ -777,7 +719,6 @@ For example, the constructor of your `HeroListComponent` needs a `HeroService`: Angular 通过查看构造函数的参数类型得知组件需要哪些服务。 例如，`HeroListComponent`组件的构造函数需要一个`HeroService`服务： - When Angular creates a component, it first asks an **injector** for @@ -801,9 +742,10 @@ The process of `HeroService` injection looks a bit like this: `HeroService`注入的过程差不多是这样的： -
    - 服务 + + Service +
    If the injector doesn't have a `HeroService`, how does it know how to make one? @@ -816,8 +758,6 @@ A provider is something that can create or return a service, typically the servi 简单点说，我们必须先用注入器（injector）为`HeroService`注册一个**提供商（provider）**。 提供商用来创建或返回服务，通常就是这个服务类本身（相当于`new HeroService()`）。 - - You can register providers in modules or in components. 我们可以在模块中或组件中注册提供商。 @@ -825,23 +765,15 @@ You can register providers in modules or in components. In general, add providers to the [root module](guide/architecture#modules) so that the same instance of a service is available everywhere. - 但通常会把提供商添加到[根模块](guide/architecture#modules)上，以便在任何地方都使用服务的同一个实例。 - - - - + Alternatively, register at a component level in the `providers` property of the `@Component` metadata: - 或者，也可以在`@Component`元数据中的`providers`属性中把它注册在组件层： - - - - + Registering at a component level means you get a new instance of the service with each new instance of that component. @@ -860,28 +792,27 @@ Points to remember about dependency injection: * Dependency injection is wired into the Angular framework and used everywhere. - 依赖注入渗透在整个 Angular 框架中，被到处使用。 + 依赖注入渗透在整个 Angular 框架中，被到处使用。 * The *injector* is the main mechanism. - **注入器 (injector)** 是本机制的核心。 + **注入器 (injector)** 是本机制的核心。 * An injector maintains a *container* of service instances that it created. - 注入器负责维护一个*容器*，用于存放它创建过的服务实例。 + 注入器负责维护一个*容器*，用于存放它创建过的服务实例。 * An injector can create a new service instance from a *provider*. - 注入器能使用*提供商*创建一个新的服务实例。 + 注入器能使用*提供商*创建一个新的服务实例。 * A *provider* is a recipe for creating a service. - *提供商*是一个用于创建服务的配方。 + *提供商*是一个用于创建服务的配方。 * Register *providers* with injectors. - 把*提供商*注册到注入器。 - + 把*提供商*注册到注入器。
    @@ -895,35 +826,35 @@ You've learned the basics about the eight main building blocks of an Angular app * [Modules](guide/architecture#modules) - [模块](guide/architecture#modules) + [模块](guide/architecture#modules) * [Components](guide/architecture#components) - [组件](guide/architecture#components) + [组件](guide/architecture#components) * [Templates](guide/architecture#templates) - [模板](guide/architecture#templates) + [模板](guide/architecture#templates) * [Metadata](guide/architecture#metadata) - [元数据](guide/architecture#metadata) + [元数据](guide/architecture#metadata) * [Data binding](guide/architecture#data-binding) - [数据绑定](guide/architecture#data-binding) + [数据绑定](guide/architecture#data-binding) * [Directives](guide/architecture#directives) - [指令](guide/architecture#directives) + [指令](guide/architecture#directives) * [Services](guide/architecture#services) - [服务](guide/architecture#services) + [服务](guide/architecture#services) * [Dependency injection](guide/architecture#dependency-injection) - [依赖注入](guide/architecture#dependency-injection) + [依赖注入](guide/architecture#dependency-injection) That's a foundation for everything else in an Angular application, and it's more than enough to get going. @@ -968,18 +899,20 @@ by implementing the lifecycle hook interfaces. > [**生命周期钩子**](guide/lifecycle-hooks)：通过实现生命周期钩子接口，可以切入组件生命中的几个关键点：从创建到销毁。 > [**Pipes**](guide/pipes): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression: - -> [**管道**](guide/pipes)：在模板中使用管道转换成用于显示的值，以增强用户体验。例如，`currency`管道表达式： - ->> `price | currency:'USD':true` - +> +> > `price | currency:'USD':true` +> > It displays a price of 42.33 as `$42.33`. +> [**管道**](guide/pipes)：在模板中使用管道转换成用于显示的值，以增强用户体验。例如，`currency`管道表达式： +> +> > `price | currency:'USD':true` +> > 它把价格“42.33”显示为`$42.33`。 > [**Router**](guide/router): Navigate from page to page within the client application and never leave the browser. - + > [**路由器**](guide/router)：在应用程序客户端的页面间导航，并且不离开浏览器。 > [**Testing**](guide/testing): Run unit tests on your application parts as they interact with the Angular framework diff --git a/aio/content/guide/attribute-directives.md b/aio/content/guide/attribute-directives.md index 038298af45..819a74b7f1 100644 --- a/aio/content/guide/attribute-directives.md +++ b/aio/content/guide/attribute-directives.md @@ -23,11 +23,11 @@ There are three kinds of directives in Angular: 1. Components—directives with a template. 组件 — 拥有模板的指令 - + 1. Structural directives—change the DOM layout by adding and removing DOM elements. 结构型指令 — 通过添加和移除 DOM 元素改变 DOM 布局的指令 - + 1. Attribute directives—change the appearance or behavior of an element, component, or another directive. 属性型指令 — 改变元素、组件或其它指令的外观和行为的指令。 @@ -52,8 +52,6 @@ can change several element styles at the same time. *属性型*指令改变一个元素的外观或行为。例如，内置的 [NgStyle](guide/template-syntax#ngStyle) 指令可以同时修改元素的多个样式。 - - ## Build a simple attribute directive ## 创建一个简单的属性型指令 @@ -85,7 +83,9 @@ Create the directive class file in a terminal window with this CLI command. 在命令行窗口下用 CLI 命令创建指令类文件。 + ng generate directive highlight + The CLI creates `src/app/highlight.directive.ts`, a corresponding test file (`.../spec.ts`, and _declares_ the directive class in the root `AppModule`. @@ -147,7 +147,6 @@ that prefix is reserved for Angular and using it could cause bugs that are diffi 确认你**没有**给`highlight`指令添加**`ng`**前缀。 那个前缀属于 Angular，使用它可能导致难以诊断的 bug。例如，这个简短的前缀`my`可以帮助你区分自定义指令。 -

    • After the `@Directive` metadata comes the directive's controller class, @@ -192,7 +191,9 @@ Now run the application to see the `HighlightDirective` in action. 运行这个应用以查看`HighlightDirective`的实际效果。 + ng serve + To summarize, Angular found the `appHighlight` attribute on the **host** `

    ` element. @@ -204,7 +205,6 @@ which sets the `

    ` element's background style to yellow. 然后它创建了一个`HighlightDirective`类的实例，并把所在元素的引用注入到了指令的构造函数中。 在构造函数中，我们把`

    `元素的背景设置为了黄色。 - {@a respond-to-user} ## Respond to user-initiated events @@ -221,30 +221,22 @@ and respond by setting or clearing the highlight color. Begin by adding `HostListener` to the list of imported symbols. - 先把`HostListener`加进导入列表中，同时再添加`Input`符号，因为我们很快就要用到它。 - - - + Then add two eventhandlers that respond when the mouse enters or leaves, each adorned by the `HostListener` decorator. - 然后使用`HostListener`装饰器添加两个事件处理器，它们会在鼠标进入或离开时进行响应。 - - - - + The `@HostListener` decorator lets you subscribe to events of the DOM element that hosts an attribute directive, the `

    ` in this case. `@HostListener`装饰器引用属性型指令的宿主元素，在这个例子中就是`

    `。 -

    Of course you could reach into the DOM with standard JavaScript and attach event listeners manually. @@ -265,7 +257,6 @@ There are at least three problems with _that_ approach: 必须直接和 DOM API 打交道，应该避免这样做。 -
    The handlers delegate to a helper method that sets the color on the host DOM element, `el`. @@ -273,32 +264,25 @@ The handlers delegate to a helper method that sets the color on the host DOM ele The helper method, `highlight`, was extracted from the constructor. The revised constructor simply declares the injected `el: ElementRef`. - 这些处理器委托给了一个辅助方法，它用于为DOM元素设置颜色，`el`就是你在构造器中声明和初始化过的。 - - - - + Here's the updated directive in full: - 下面是修改后的指令代码： - + - - - -Run the app and confirm that the background color appears when the mouse hovers over the `p` and -disappears as it moves out.We run the app and confirm that the background color appears as we move the mouse over the `p` and -disappears as we move out. +Run the app and confirm that the background color appears when +the mouse hovers over the `p` and disappears as it moves out. 运行本应用并确认：当把鼠标移到`p`上的时候，背景色就出现了，而移开的时候，它消失了。
    + Second Highlight +
    {@a bindings} @@ -323,10 +307,7 @@ Add a `highlightColor` property to the directive class like this: 然后把`highlightColor`属性添加到指令类中，就像这样： - - - - + {@a input} @@ -346,43 +327,27 @@ Without that input metadata, Angular rejects the binding; see [below](guide/attr Try it by adding the following directive binding variations to the `AppComponent` template: - 试试把下列指令绑定变量添加到`AppComponent`的模板中： - - - - + Add a `color` property to the `AppComponent`. - 把`color`属性添加到`AppComponent`中： - - - - + Let it control the highlight color with a property binding. - 让它通过属性绑定来控制高亮颜色。 - - - - + That's good, but it would be nice to _simultaneously_ apply the directive and set the color _in the same attribute_ like this. - 很不错，但还可以更好。我们可以在应用该指令时在同一个属性中设置颜色，就像这样： - - - - + The `[appHighlight]` attribute binding both applies the highlighting directive to the `

    ` element and sets the directive's highlight color with a property binding. @@ -395,19 +360,14 @@ That's a crisp, compact syntax. You'll have to rename the directive's `highlightColor` property to `appHighlight` because that's now the color property binding name. - 我们还要把该指令的`highlightColor`改名为`myHighlight`，因为它是颜色属性目前的绑定名。 - - - - + This is disagreeable. The word, `appHighlight`, is a terrible property name and it doesn't convey the property's intent. 这可不好。因为`myHighlight`是一个糟糕的属性名，而且不能反映该属性的意图。 - {@a input-alias} ### Bind to an _@Input_ alias @@ -418,15 +378,11 @@ Fortunately you can name the directive property whatever you want _and_ **_alias 幸运的是，我们可以随意命名该指令的属性，并且**给它指定一个用于绑定的别名**。 -Restore the original property name and specify the selector as the alias in the argument to `@Input`. - +Restore the original property name and specify the selector as the alias in the argument to `@Input`. 恢复原始属性名，并在`@Input`的参数中把选择器`myHighlight`指定为别名。 - - - - + _Inside_ the directive the property is known as `highlightColor`. _Outside_ the directive, where you bind to it, it's known as `appHighlight`. @@ -435,41 +391,28 @@ _Outside_ the directive, where you bind to it, it's known as `appHighlight`. You get the best of both worlds: the property name you want and the binding syntax you want: - 这是最好的结果：理想的内部属性名，理想的绑定语法： - + - - - -Now that you're binding via the alias to the `highlightColor`, modify the `onMouseEnter()` method to use that property. +Now that you're binding via the alias to the `highlightColor`, modify the `onMouseEnter()` method to use that property. If someone neglects to bind to `appHighlightColor`, highlight the host element in red: - 现在，我们绑定到了`highlightColor`属性，并修改`onMouseEnter()`方法来使用它。 如果有人忘了绑定到`highlightColor`，那就用红色进行高亮。 - - - - + Here's the latest version of the directive class. - 这是最终版本的指令类。 - - - - + ## Write a harness to try it ## 写个测试程序试验下 - It may be difficult to imagine how this directive actually works. In this section, you'll turn `AppComponent` into a harness that lets you pick the highlight color with a radio button and bind your color choice to the directive. @@ -479,31 +422,24 @@ lets you pick the highlight color with a radio button and bind your color choice Update app.component.html as follows: - 把`app.component.html`修改成这样： - - - - + Revise the `AppComponent.color` so that it has no initial value. - 修改`AppComponent.color`，让它不再有初始值。 - - - - + Here are the harness and directive in action. - 下面是测试程序和指令的动图。 -

    +
    + Highlight v.2 +
    {@a second-property} @@ -524,24 +460,16 @@ Let the template developer set the default color. Add a second **input** property to `HighlightDirective` called `defaultColor`: - 把第二个名叫`defaultColor`的**输入**属性添加到`HighlightDirective`中： - - - - + Revise the directive's `onMouseEnter` so that it first tries to highlight with the `highlightColor`, then with the `defaultColor`, and falls back to "red" if both properties are undefined. - 修改该指令的`onMouseEnter`，让它首先尝试使用`highlightColor`进行高亮，然后用`defaultColor`，如果它们都没有指定，那就用红色作为后备。 - - - - + How do you bind to a second property when you're already binding to the `appHighlight` attribute name? @@ -551,14 +479,10 @@ As with components, you can add as many directive property bindings as you need The developer should be able to write the following template HTML to both bind to the `AppComponent.color` and fall back to "violet" as the default color. - 像组件一样，你也可以绑定到指令的很多属性，只要把它们依次写在模板中就行了。 开发者可以绑定到`AppComponent.color`，并且用紫罗兰色作为默认颜色，代码如下： - - - - + Angular knows that the `defaultColor` binding belongs to the `HighlightDirective` because you made it _public_ with the `@Input` decorator. @@ -567,16 +491,17 @@ Angular之所以知道`defaultColor`绑定属于`HighlightDirective`，是因为 Here's how the harness should work when you're done coding. - 当这些代码完成时，测试程序工作时的动图如下： -
    +
    + Final Highlight +
    ## Summary -## 总结 +## 小结 This page covered how to: @@ -584,36 +509,40 @@ This page covered how to: * [Build an **attribute directive**](guide/attribute-directives#write-directive) that modifies the behavior of an element. - [构建一个**属性型指令**](guide/attribute-directives#write-directive)，它用于修改一个元素的行为。 - + [构建一个**属性型指令**](guide/attribute-directives#write-directive)，它用于修改一个元素的行为。 + * [Apply the directive](guide/attribute-directives#apply-directive) to an element in a template. - [把一个指令应用到](guide/attribute-directives#apply-directive)模板中的某个元素上。 - + [把一个指令应用到](guide/attribute-directives#apply-directive)模板中的某个元素上。 + * [Respond to **events**](guide/attribute-directives#respond-to-user) that change the directive's behavior. - [响应**事件**](guide/attribute-directives#respond-to-user)以改变指令的行为。 - + [响应**事件**](guide/attribute-directives#respond-to-user)以改变指令的行为。 + * [**Bind** values to the directive](guide/attribute-directives#bindings). - [把值**绑定**到指令中](guide/attribute-directives#bindings)。 - + [把值**绑定**到指令中](guide/attribute-directives#bindings)。 The final source code follows: 最终的源码如下： + + + + + + + - - You can also experience and download the . 你还可以体验和下载. @@ -627,23 +556,15 @@ You can also experience and download the - - - + You've seen it with an alias: - 也见过用别名时的代码： - - - - + Either way, the `@Input` decorator tells Angular that this property is _public_ and available for binding by a parent component. @@ -687,34 +608,31 @@ You can tell if `@Input` is needed by the position of the property name in a bin * When it appears in the template expression to the ***right*** of the equals (=), it belongs to the template's component and does not require the `@Input` decorator. - 当它出现在等号***右侧***的模板表达式中时，它属于模板所在的组件，不需要`@Input`装饰器。 + 当它出现在等号***右侧***的模板表达式中时，它属于模板所在的组件，不需要`@Input`装饰器。 * When it appears in **square brackets** ([ ]) to the **left** of the equals (=), the property belongs to some _other_ component or directive; that property must be adorned with the `@Input` decorator. - 当它出现在等号**左边**的**方括号（[ ]）**中时，该属性属于*其它*组件或指令，它必须带有`@Input` 装饰器。 + 当它出现在等号**左边**的**方括号（[ ]）**中时，该属性属于*其它*组件或指令，它必须带有`@Input` 装饰器。 Now apply that reasoning to the following example: - 试用此原理分析下列范例： - - - - + * The `color` property in the expression on the right belongs to the template's component. The template and its component trust each other. The `color` property doesn't require the `@Input` decorator. - `color`属性位于右侧的绑定表达式中，它属于模板所在的组件。 + `color`属性位于右侧的绑定表达式中，它属于模板所在的组件。 该模板和组件相互信任。因此`color`不需要`@Input`装饰器。 * The `appHighlight` property on the left refers to an _aliased_ property of the `HighlightDirective`, not a property of the template's component. There are trust issues. Therefore, the directive property must carry the `@Input` decorator. - `myHighlight`属性位于左侧，它引用了`MyHighlightDirective`中一个*带别名的*属性，它不是模板所属组件的一部分，因此存在信任问题。 -所以，该属性必须带`@Input`装饰器。 + + `myHighlight`属性位于左侧，它引用了`MyHighlightDirective`中一个*带别名的*属性，它不是模板所属组件的一部分，因此存在信任问题。 +所以，该属性必须带`@Input`装饰器。 \ No newline at end of file diff --git a/aio/content/guide/bootstrapping.md b/aio/content/guide/bootstrapping.md index 046555b18d..f3bd1318ca 100644 --- a/aio/content/guide/bootstrapping.md +++ b/aio/content/guide/bootstrapping.md @@ -3,6 +3,7 @@ #### Prerequisites A basic understanding of the following: + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
    @@ -47,8 +48,11 @@ The `@NgModule` decorator identifies `AppModule` as an `NgModule` class. `@NgModule` takes a metadata object that tells Angular how to compile and launch the application. * **_declarations_**—this application's lone component. + * **_imports_**—import `BrowserModule` to have browser specific services such as DOM rendering, sanitization, and location. + * **_providers_**—the service providers. + * **_bootstrap_**—the _root_ component that Angular creates and inserts into the `index.html` host web page. @@ -92,42 +96,41 @@ import the module that has the declarable you need in it. **Only `@NgModule` references** go in the `imports` array. - ### Using directives with `@NgModule` Use the `declarations` array for directives. To use a directive, component, or pipe in a module, you must do a few things: 1. Export it from the file where you wrote it. -2. Import it into the appropriate module. -3. Declare it in the `@NgModule` `declarations` array. +2. Import it into the appropriate module. + +3. Declare it in the `@NgModule` `declarations` array. Those three steps look like the following. In the file where you create your directive, export it. The following example, named `ItemDirective` is the default directive structure that the CLI generates in its own file, `item.directive.ts`: + The key point here is that you have to export it so you can import it elsewhere. Next, import it into the NgModule, in this example `app.module.ts`, with a JavaScript import statement: + And in the same file, add it to the `@NgModule` `declarations` array: - + Now you could use your `ItemDirective` in a component. This example uses `AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components. Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean. - - - {@a imports} ## The `imports` array @@ -172,8 +175,6 @@ most applications have only one component tree and bootstrap a single root compo This one root component is usually called `AppComponent` and is in the root module's `bootstrap` array. - - ## More about Angular Modules For more on NgModules you're likely to see frequently in apps, diff --git a/aio/content/guide/browser-support.md b/aio/content/guide/browser-support.md index cac1aecdfb..0b73bdeebb 100644 --- a/aio/content/guide/browser-support.md +++ b/aio/content/guide/browser-support.md @@ -6,17 +6,24 @@ Angular supports most recent browsers. This includes the following specific vers Angular 支持大多数常用浏览器，包括下列版本： - @@ -24,86 +31,141 @@ Angular 支持大多数常用浏览器，包括下列版本： - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Browser + + 浏览器 + + Supported versions + + 支持的版本 +
    + Chrome + -

    - latest -

    - -

    - 最新版 -

    - -
    - Firefox - latest + + 最新版 +
    + + Firefox + + + + latest + + 最新版 + +
    + Edge + + 2 most recent major versions + + 最近的两个主版本 +
    + IE + + 11
    10
    9 +
    + IE Mobile + + 11 +
    + Safari + + 2 most recent major versions + + 最近的两个主版本 +
    + iOS + + 2 most recent major versions + + 最近的两个主版本 +
    + Android + + Nougat (7.0)
    Marshmallow (6.0)
    Lollipop (5.0, 5.1)
    KitKat (4.4) +
    @@ -117,10 +179,8 @@ using SauceLabs and Angular 在持续集成过程中，对每一个提交都会使用 SauceLabs 和 Browserstack 在上述所有浏览器上执行单元测试。 -
    - ## Polyfills ## 腻子脚本 (polyfill) @@ -173,9 +233,11 @@ For example, [if you need the web animations polyfill](http://caniuse.com/#feat= 比如，[如果你需要 web 动画的腻子脚本](http://caniuse.com/#feat=web-animation)，就要通过下列命令之一来安装它： + # note that the web-animations-js polyfill is only here as an example # it isn't a strict requirement of Angular anymore (more below) npm install --save web-animations-js + Then open the `polyfills.ts` file and un-comment the corresponding `import` statement as in the following example: @@ -183,11 +245,13 @@ Then open the `polyfills.ts` file and un-comment the corresponding `import` stat 然后打开 `polyfills.ts` 文件，并反注释对应的 `import` 语句，就像这样： + /** * Required to support Web Animations `@angular/platform-browser/animations`. * Needed for: All but Chrome, Firefox and Opera. http://caniuse.com/#feat=web-animation **/ import 'web-animations-js'; // Run `npm install --save web-animations-js`. + If you can't find the polyfill you want in `polyfills.ts`, @@ -198,7 +262,7 @@ add it yourself, following the same pattern: 1. install the npm package 安装 npm 包 - + 1. `import` the file in `polyfills.ts` 在 `polyfills.ts` 中 `import` 这个文件 @@ -213,7 +277,6 @@ Non-CLI users should follow the instructions [below](#non-cli). {@a polyfill-libs} - ### Mandatory polyfills ### 强制性腻子脚本 @@ -222,31 +285,23 @@ These are the polyfills required to run an Angular application on each supported 下表中的腻子脚本是每个浏览器都要用到的： - @@ -255,7 +310,9 @@ These are the polyfills required to run an Angular application on each supported
    -

    - Browsers (Desktop & Mobile) -

    + Browsers (Desktop & Mobile) + + 浏览器（桌面和移动） -

    - 浏览器（桌面和移动） -

    		-

    - Polyfills Required -

    + Polyfills Required -

    - 需要的腻子脚本 -

    + 需要的腻子脚本
    + Chrome, Firefox, Edge, Safari 9+ + @@ -269,7 +326,9 @@ These are the polyfills required to run an Angular application on each supported
    + Safari 7 & 8, IE10 & 11, Android 4.1+ + @@ -283,7 +342,9 @@ These are the polyfills required to run an Angular application on each supported
    + IE9 + @@ -296,7 +357,6 @@ These are the polyfills required to run an Angular application on each supported
    - ### Optional browser features to polyfill ### 可选浏览器特性的腻子脚本 @@ -314,30 +374,32 @@ Here are the features which may require additional polyfills: 下列特性可能需要更多腻子脚本： - @@ -349,22 +411,24 @@ Here are the features which may require additional polyfills: [JIT compilation](guide/aot-compiler). Required to reflect for metadata. - + [JIT 编译](guide/aot-compiler) 需要 reflect 来提供元数据。 - + @@ -379,7 +443,7 @@ Here are the features which may require additional polyfills:
    Only if `Animation Builder` is used within the application--standard animation support in Angular doesn't require any polyfills (as of NG6). - +
    只有在应用中用到了 `Animation Builder` 时才需要；Angular 标准的动画支持是不需要任何腻子脚本的（截至 NG6）。 @@ -389,13 +453,16 @@ Here are the features which may require additional polyfills: [Web Animations](guide/browser-support#web-animations) [Web 动画](guide/browser-support#web-animations) + @@ -407,15 +474,15 @@ Here are the features which may require additional polyfills: If you use the following deprecated i18n pipes: 如果你使用下列已废弃的i18n管道： - + [date](api/common/DeprecatedDatePipe), - + [currency](api/common/DeprecatedCurrencyPipe), - - [decimal](api/common/DeprecatedDecimalPipe), - + + [decimal](api/common/DeprecatedDecimalPipe), + [percent](api/common/DeprecatedPercentPipe) - + @@ -437,11 +505,12 @@ Here are the features which may require additional polyfills: @@ -460,34 +531,38 @@ Here are the features which may require additional polyfills:
    + Feature - + 特性 - + + Polyfill - + 腻子脚本 - Browsers (Desktop & Mobile) - - 浏览器（桌面和移动） - + + Browsers (Desktop & Mobile) + + 浏览器（桌面和移动） +
    [ES7/reflect](guide/browser-support#core-es7-reflect) + + All current browsers. Enabled by default. Can remove if you always use AOT and only use Angular decorators. - + 默认对目前的所有浏览器都启用了。如果总是使用 AOT 模式，并且只使用 Angular 自带的装饰器，那么可以移除它。 - +
    +

    If AnimationBuilder is used then the polyfill will enable scrubbing support for IE/Edge and Safari (Chrome and Firefox support this natively).

    - +

    如果使用了AnimationBuilder，那么腻子脚本将为 IE/Edge 和 Safari 启用擦除（scrubbing）支持（Chrome 和 Firefox 原生支持此特性）

    +
    @@ -425,9 +492,10 @@ Here are the features which may require additional polyfills: -

    All but Chrome, Firefox, Edge, IE11 and Safari 10

    - -

    除了 Chrome、Firefox、Edge、IE11 和 Safari 10 外的所有浏览器

    + + All but Chrome, Firefox, Edge, IE11 and Safari 10 + + 除了 Chrome、Firefox、Edge、IE11 和 Safari 10 外的所有浏览器     		-

    [NgClass](api/common/NgClass) - - on SVG elements

    - -

    在 SVG 元素上应用 [NgClass](api/common/NgClass)

    + [NgClass](api/common/NgClass) + + on SVG elements + + 在 SVG 元素上应用时 +     		@@ -451,7 +520,9 @@ Here are the features which may require additional polyfills: + IE10, IE11 +
    -

    [Http](guide/http) - - when sending and receiving binary data

    - -

    用 [Http](guide/http) 发送和接收二进制数据

    - + [Http](guide/http) + + when sending and receiving binary data + + 用 [Http](guide/http) 发送和接收二进制数据时 +     		- [Typed Array](guide/browser-support#typedarray)
    + [Typed Array](guide/browser-support#typedarray) - [Blob](guide/browser-support#blob)
    +
    + + [Blob](guide/browser-support#blob) + +
    [FormData](guide/browser-support#formdata)     		+ IE 9 +
    - - ### Suggested polyfills ## ### 建议的腻子脚本 ## @@ -496,44 +571,31 @@ Below are the polyfills which are used to test the framework itself. They are a 下表中是用来测试框架本身的腻子脚本，它们是应用程序的优质起点。 - @@ -548,11 +610,15 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -566,11 +632,15 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -585,18 +655,16 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -610,11 +678,15 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -622,15 +694,21 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -644,11 +722,15 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -662,11 +744,15 @@ Below are the polyfills which are used to test the framework itself. They are a @@ -680,22 +766,28 @@ Below are the polyfills which are used to test the framework itself. They are a
    -

    - Polyfill -

    + Polyfill -

    - 腻子脚本 -

    + 腻子脚本     		-

    - Licence -

    + License -

    - 授权方式 -

    + 授权方式     		-

    - Size* -

    + Size* -

    - 大小* -

    + 大小*     		+ MIT + + 0.5KB +
    + MIT + + 27.4KB +
    -

    - Public domain -

    + Public domain -

    - 公共域 -

    + 公共域     		+ 1KB +
    + MIT / Unicode license + + 13.5KB +
    + Web Animations + + Apache + + 14.8KB +
    + MIT + + 4KB +
    + MIT + + 1.3KB +
    + MIT + + 0.4KB +
    +\* Figures are for minified and gzipped code, +computed with the closure compiler. -\* Figures are for minified and gzipped code, -computed with the closure compiler. +\* 这里的数据都按最小化并且 gzip 压缩后的版本算，是由closure compiler计算出的。 {@a non-cli} + ## Polyfills for non-CLI users ## 不使用 CLI 的用户的腻子脚本 @@ -705,13 +797,17 @@ If you are not using the CLI, you should add your polyfill scripts directly to t 如果你不使用 CLI，就要直接把腻子脚本添加到宿主页（`index.html`）中，就像这样： + <!-- pre-zone polyfills --> <script src="node_modules/core-js/client/shim.min.js"></script> <script src="node_modules/web-animations-js/web-animations.min.js"></script> <script> /** + * you can configure some zone flags which can disable zone interception for some + * asynchronous activities to improve startup performance - use these options only + * if you know what you are doing as it could result in hard to trace down bugs.. */ // __Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame @@ -719,7 +815,9 @@ If you are not using the CLI, you should add your polyfill scripts directly to t // __zone_symbol__BLACK_LISTED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames /* + * in IE/Edge developer tools, the addEventListener will also be wrapped by zone.js + * with the following flag, it will bypass `zone.js` patch for IE/Edge */ // __Zone_enable_cross_context_check = true; @@ -728,4 +826,6 @@ If you are not using the CLI, you should add your polyfill scripts directly to t <script src="node_modules/zone.js/dist/zone.js"></script> <!-- application polyfills --> + + diff --git a/aio/content/guide/change-log.md b/aio/content/guide/change-log.md index b96250ffac..9f8ae96007 100644 --- a/aio/content/guide/change-log.md +++ b/aio/content/guide/change-log.md @@ -2,8 +2,6 @@ # 变更记录 - - The Angular documentation is a living document with continuous improvements. This log calls attention to recent significant changes. @@ -81,23 +79,23 @@ Notably: * `app/main.ts` moved to `src/main.ts`. - 把`app/main.ts`移到`src/main.ts`。 + 把`app/main.ts`移到`src/main.ts`。 * `app/` moved to `src/app/`. - - 把`app/`移到`src/app/`。 - + + 把`app/`移到`src/app/`。 + * `index.html`, `styles.css` and `tsconfig.json` moved inside `src/`. - 把`index.html`、`styles.css`和`tsconfig.json`移到`src/`中。 + 把`index.html`、`styles.css`和`tsconfig.json`移到`src/`中。 * `systemjs.config.js` now imports `main.js` instead of `app`. - `systemjs.config.js`现在要导入`main.js`而不是`app`。 + `systemjs.config.js`现在要导入`main.js`而不是`app`。 * Added `lite-server` configuration (`bs-config.json`) to serve `src/`. - 新增了一个`lite-server`配置(`bs-config.json`)以便在`src/`下启动开发服务器。 + 新增了一个`lite-server`配置(`bs-config.json`)以便在`src/`下启动开发服务器。 ## NEW: Reactive Forms guide (2017-01-31) @@ -131,7 +129,7 @@ It includes important advice on optimizing for production. [Hierarchical Dependency Injection](guide/hierarchical-dependency-injection) guide is significantly revised. Closes issue #3086. -Revised samples are clearer and cover all topics discussed +Revised samples are clearer and cover all topics discussed. [多级依赖注入](guide/hierarchical-dependency-injection)做了显著修改。关闭了issue #3086。修改过的范例更加清晰，而且涵盖了讨论到的全部主题。 @@ -139,25 +137,23 @@ Revised samples are clearer and cover all topics discussed ## 杂项 (2017-01-05) -* [Setup](guide/setup) guide: +* [Setup](guide/setup) guide: +added (optional) instructions on how to remove _non-essential_ files. [环境搭建](guide/setup)指南: - - added (optional) instructions on how to remove _non-essential_ files. - 添加了（可选的）步骤说明，告诉你如何移除*非核心*文件。 - + * No longer consolidate RxJS operator imports in `rxjs-extensions` file; each file should import what it needs. - - 不再在`rxjs-extensions`文件中统一导入RxJS的操作符，每个文件应该各自导入它自己所需的。 + + 不再在`rxjs-extensions`文件中统一导入RxJS的操作符，每个文件应该各自导入它自己所需的。 * All samples prepend template/style URLs with `./` as a best practice. - 所有范例都在模板/样式的URL之前添加`./`前缀 …… 而且你在实际开发中也应该这么做。 + 所有范例都在模板/样式的URL之前添加`./`前缀 …… 而且你在实际开发中也应该这么做。 * [Style Guide](guide/styleguide): copy edits and revised rules. - [风格指南](guide/styleguide)：复制了编辑过的和修改过的规则。 + [风格指南](guide/styleguide)：复制了编辑过的和修改过的规则。 ## Router: more detail (2016-12-21) @@ -189,9 +185,9 @@ Linked to these plunkers in "Testing" and "Setup anatomy" guides. ## Internationalization: pluralization and _select_ (2016-11-30) -## 国际化：单复数和`select` (2016-11-30) +## 国际化：单复数和`select` (2016-11-30) -The [Internationalization (i18n)](guide/i18n) guide explains how to handle pluralization and +The [Internationalization (i18n)](guide/i18n) guide explains how to handle pluralization and translation of alternative texts with `select`. The sample demonstrates these features too. @@ -204,12 +200,12 @@ The sample demonstrates these features too. * `karma.config` + `karma-test-shim` can handle multiple spec source paths; see quickstart issue: [angular/quickstart#294](https://github.com/angular/quickstart/issues/294). - - `karma.config` + `karma-test-shim`可以处理多个测试源文件路径了，参见[angular/quickstart#294](https://github.com/angular/quickstart/issues/294)。 + + `karma.config` + `karma-test-shim`可以处理多个测试源文件路径了，参见[angular/quickstart#294](https://github.com/angular/quickstart/issues/294)。 * Displays Jasmine Runner output in the karma-launched browser. - 在启动了karma的浏览器中显示Jasmine的输出。 + 在启动了karma的浏览器中显示Jasmine的输出。 ## QuickStart Rewrite (2016-11-18) @@ -228,15 +224,15 @@ You are no longer asked to copy-and-paste code into setup files that were not ex ## Sync with Angular v.2.2.0 (2016-11-14) -## 与Angular v.2.2.0同步(2016-11-14) +## 与Angular v.2.2.0同步(2016-11-14) -Docs and code samples updated and tested with Angular v.2.2.0 . +Docs and code samples updated and tested with Angular v.2.2.0. 使用Angular v.2.2.0更新和测试所有文档和代码例子。 ## UPDATE: NgUpgrade Guide for the AOT friendly _upgrade/static_ module (2016-11-14) -## 更新：用于AoT的_upgrade/static_模块NgUpgrade指南 (2016-11-14) +## 更新：用于AoT的_upgrade/static_模块NgUpgrade指南 (2016-11-14) The updated [NgUpgrade Guide](guide/upgrade) guide covers the new AOT friendly `upgrade/static` module @@ -250,15 +246,13 @@ The documentation for the version prior to v.2.2.0 has been removed. ## ES6 described in "TypeScript to JavaScript" (2016-11-14) -## 在“从TypeScript到JavaScript”增加ES6的描述 (2016-11-14) +## 在“从TypeScript到JavaScript”增加ES6的描述 (2016-11-14) The updated TypeScript to JavaScript guide explains how to write apps in ES6/7 - -更新了“[从TypeScript到JavaScript](guide/ts-to-js)”烹饪宝典，解释如何使用ES6/7编写应用 - by translating the common idioms in the TypeScript documentation examples (and elsewhere on the web) to ES6/7 and ES5. +更新了“[从TypeScript到JavaScript](guide/ts-to-js)”烹饪宝典，解释如何使用ES6/7编写应用。 将TypeScript文档示例中（以及网站其它地方）的习惯用法翻译成ES6/7和ES5。 This was [removed in August 2017](https://github.com/angular/angular/pull/18694) but can still be @@ -266,9 +260,9 @@ viewed in the [v2 documentation](https://v2.angular.io/docs/ts/latest/cookbook/t ## Sync with Angular v.2.1.1 (2016-10-21) -## 与Angular v.2.1.1 同步(2016-10-21) +## 与Angular v.2.1.1 同步(2016-10-21) -Docs and code samples updated and tested with Angular v.2.1.1. +Docs and code samples updated and tested with Angular v.2.1.1. 使用Angular v.2.1.1更新和测试所有文档和代码例子。 @@ -327,9 +321,9 @@ New `:enter` and `:leave` aliases make animation more natural. ## Sync with Angular v.2.1.0 (2016-10-12) -## 与Angular v.2.1.0同步(2016-10-12) +## 与Angular v.2.1.0同步(2016-10-12) -Docs and code samples updated and tested with Angular v.2.1.0 . +Docs and code samples updated and tested with Angular v.2.1.0. 使用Angular v.2.1.0更新和测试所有文档和代码例子。 @@ -347,9 +341,9 @@ followed by the more advanced considerations of compiling and bundling the Tour ## Sync with Angular v.2.0.2 (2016-10-6) -## 与Angular v.2.0.2同步 (2016-10-6) +## 与Angular v.2.0.2同步 (2016-10-6) -Docs and code samples updated and tested with Angular v.2.0.2 . +Docs and code samples updated and tested with Angular v.2.0.2. 使用Angular v.2.0.2更新和测试所有文档和代码例子。 @@ -364,10 +358,6 @@ The _Routing Module_ replaces the previous _routing object_ involving the `Modul [Routing and Navigation](guide/router)现在在**路由模块**中设置路由配置。 **路由模块**替换之前的**路由对象**，使用了`ModuleWithProviders`。 -[Routing and Navigation](guide/router) - -[路由与导航](guide/router) - All guided samples with routing use the _Routing Module_ and prose content has been updated, most conspicuously in the [NgModule](guide/ngmodules) guide and [NgModule FAQ](guide/ngmodule-faq) guide. @@ -406,13 +396,11 @@ The new "angular-in-memory-web-api" has new features. ## “风格指南”中添加了_NgModules_(2016-09-27) [StyleGuide](guide/styleguide) explains recommended conventions for NgModules. - -[StyleGuide](guide/styleguide)解释了我们为Angular模块（NgModule）而推荐的约定。 - Barrels now are far less useful and have been removed from the style guide; they remain valuable but are not a matter of Angular style. Also relaxed the rule that discouraged use of the `@Component.host` property. +[StyleGuide](guide/styleguide)解释了我们为Angular模块（NgModule）而推荐的约定。 现在，封装桶不再那么重要，风格指南已经移除了它们。 它们仍然很有价值，但是它们与Angular风格无关。 我们同时对**不推荐使用`@Component.host`属性**的规则有所放宽。 @@ -440,4 +428,5 @@ modules with SystemJS as the samples currently do. The [Lifecycle Hooks](guide/lifecycle-hooks) guide is shorter, simpler, and draws more attention to the order in which Angular calls the hooks. -[生命周期钩子](guide/lifecycle-hooks)章现在更加简短，并且对强调了Angular是以什么顺序来调用钩子方法的。 + +[生命周期钩子](guide/lifecycle-hooks)章现在更加简短，并且对强调了Angular是以什么顺序来调用钩子方法的。 \ No newline at end of file diff --git a/aio/content/guide/cheatsheet.md b/aio/content/guide/cheatsheet.md index b9dc9df176..7da15c03a6 100644 --- a/aio/content/guide/cheatsheet.md +++ b/aio/content/guide/cheatsheet.md @@ -1,498 +1,764 @@ -

    Cheat Sheet

    -

    速查表

    + +

    Cheat Sheet

    + - + + + + + + + + +
    -

    Bootstrapping

    -

    启动

    -    		Bootstrapping

    import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; +

    +
    platformBrowserDynamic().bootstrapModule(AppModule);

    Bootstraps the app, using the root component from the specified NgModule.

    -

    用 NgModule 中指定的根组件进行启动。

    +
    + - + + + + + + + + + + + + + + + + + + + + + + + +

    NgModules

    -

    Angular 模块

    -    		NgModules

    import { NgModule } from '@angular/core'; +

    +
    @NgModule({ declarations: ..., imports: ...,
    exports: ..., providers: ..., bootstrap: ...})
    class MyModule {}

    Defines a module that contains components, directives, pipes, and providers.

    -

    定义一个模块，其中可以包含组件、指令、管道和服务提供商。

    +
    declarations: [MyRedComponent, MyBlueComponent, MyDatePipe]

    List of components, directives, and pipes that belong to this module.

    -

    属于当前模块的组件、指令和管道的列表。

    +
    imports: [BrowserModule, SomeOtherModule]

    List of modules to import into this module. Everything from the imported modules -is available to declarations of this module.

    -

    本模块所导入的模块列表

    +is available to + + declarations of this module.

    +
    exports: [MyRedComponent, MyDatePipe]

    List of components, directives, and pipes visible to modules that import this module.

    -

    那些导入了本模块的模块所能看到的组件、指令和管道的列表

    +
    providers: [MyService, { provide: ... }]

    List of dependency injection providers visible both to the contents of this module and to importers of this module.

    -

    依赖注入提供商的列表，本模块以及本模块导入的所有模块中的内容都可以看见它们。

    +
    bootstrap: [MyAppComponent]

    List of components to bootstrap when this module is bootstrapped.

    -

    当本模块启动时，随之启动的组件列表。

    +
    + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    -

    Template syntax

    -

    模板语法

    -    		Template syntax
    <input [value]="firstName">

    Binds property value to the result of expression firstName.

    -

    把value属性绑定到表达式firstName

    +
    <div [attr.role]="myAriaRole">

    Binds attribute role to the result of expression myAriaRole.

    -

    把属性（Attribute）role绑定到表达式myAriaRole的结果。

    +
    <div [class.extra-sparkle]="isDelightful">

    Binds the presence of the CSS class extra-sparkle on the element to the truthiness of the expression isDelightful.

    -

    根据isDelightful表达式的结果是否为真，决定CSS类extra-sparkle是否出现在当前元素上。

    +
    <div [style.width.px]="mySize">

    Binds style property width to the result of expression mySize in pixels. Units are optional.

    -

    把CSS样式属性width的px（像素）值绑定到表达式mySize的结果。单位是可选的。

    +
    <button (click)="readRainbow($event)">

    Calls method readRainbow when a click event is triggered on this button element (or its children) and passes in the event object.

    -

    当这个按钮元素（及其子元素）上的click事件触发时，调用方法readRainbow，并把这个事件对象作为参数传进去。

    +
    <div title="Hello {{ponyName}}">

    Binds a property to an interpolated string, for example, "Hello Seabiscuit". Equivalent to: + <div [title]="'Hello ' + ponyName">

    -

    把一个属性绑定到插值字符串（如"Hello Seabiscuit"）。这种写法等价于<div [title]="'Hello ' + ponyName">

    +
    <p>Hello {{ponyName}}</p>

    Binds text content to an interpolated string, for example, "Hello Seabiscuit".

    -

    把文本内容绑定到插值字符串（如"Hello Seabiscuit"）

    +
    <my-cmp [(title)]="name">

    Sets up two-way data binding. Equivalent to: <my-cmp [title]="name" (titleChange)="name=$event">

    -

    设置双向绑定。等价于<my-cmp [title]="name" (titleChange)="name=$event">。

    +
    <video #movieplayer ...>
    <button (click)="movieplayer.play()">
    </video>

    Creates a local variable movieplayer that provides access to the video element instance in data-binding and event-binding expressions in the current template.

    -

    创建一个局部变量movieplayer，支持在当前模板的数据绑定和事件绑定表达式中访问video元素的实例。

    +
    <p *myUnless="myExpression">...</p>

    The * symbol turns the current element into an embedded template. Equivalent to: -<template [myUnless]="myExpression"><p>...</p></template>

    -

    星号*会把当前元素转换成内嵌式模板，等价于：<template [myUnless]="myExpression"><p>...</p></template>

    + +<ng-template [myUnless]="myExpression"><p>...</p></ng-template>

    +
    <p>Card No.: {{cardNumber | myCardNumberFormatter}}</p>

    Transforms the current value of expression cardNumber via the pipe called myCardNumberFormatter.

    -

    使用名叫myCardNumberFormatter的管道对表达式cardNumber的当前值进行变幻

    +
    <p>Employer: {{employer?.companyName}}</p>

    The safe navigation operator (?) means that the employer field is optional and if undefined, the rest of the expression should be ignored.

    -

    安全导航操作符（?）表示employer字段是可选的，如果它是 undefined ，那么表达式其余的部分就会被忽略，并返回 undefined。

    +
    <svg:rect x="0" y="0" width="100" height="100"/>

    An SVG snippet template needs an svg: prefix on its root element to disambiguate the SVG element from an HTML component.

    -

    模板中的 SVG 片段需要给它的根元素加上svg:前缀，以便把 SVG 元素和 HTML 元素区分开。

    +
    <svg>
    <rect x="0" y="0" width="100" height="100"/>
    </svg>

    An <svg> root element is detected as an SVG element automatically, without the prefix.

    -

    以<svg>作为根元素时会自动识别为 SVG 元素，不需要前缀。

    +
    + - + + + + + + + + + + + - + + + + + + + + + + + +
    -

    Built-in directives

    -

    内置指令

    -    		Built-in directives

    import { CommonModule } from '@angular/common'; +

    +
    <section *ngIf="showSection">

    Removes or recreates a portion of the DOM tree based on the showSection expression.

    -

    根据showSection表达式的结果，移除或重新创建 DOM 树的一部分。

    +
    <li *ngFor="let item of list">

    Turns the li element and its contents into a template, and uses that to instantiate a view for each item in list.

    -

    把li元素及其内容变成一个模板，并使用这个模板为列表中的每一个条目实例化一个视图。

    +
    <div [ngSwitch]="conditionExpression">
    <template [ngSwitchCase]="case1Exp">...</template>
    <template ngSwitchCase="case2LiteralString">...</template>
    <template ngSwitchDefault>...</template>
    </div>    		<div [ngSwitch]="conditionExpression">
    <ng-template [ngSwitchCase]="case1Exp">...</ng-template>
    <ng-template ngSwitchCase="case2LiteralString">...</ng-template>
    <ng-template ngSwitchDefault>...</ng-template>
    </div>

    Conditionally swaps the contents of the div by selecting one of the embedded templates based on the current value of conditionExpression.

    -

    根据conditionExpression的当前值选择一个嵌入式模板，并用它替换这个 div 的内容。

    +
    <div [ngClass]="{'active': isActive, 'disabled': isDisabled}">

    Binds the presence of CSS classes on the element to the truthiness of the associated map values. The right-hand expression should return {class-name: true/false} map.

    -

    根据 map 中的 value 是否为真，来决定该元素上是否出现与 name 对应的 CSS 类。右侧的表达式应该返回一个形如 {class-name: true/false} 的 map。

    +
    <div [ngStyle]="{'property': 'value'}">
    <div [ngStyle]="dynamicStyles()">

    Allows you to assign styles to an HTML element using CSS. You can use CSS directly, as in the first example, or you can call a method from the component.

    +
    + - + + + + + + + + +
    -

    Forms

    -

    表单

    -    		Forms

    import { FormsModule } from '@angular/forms'; +

    +
    <input [(ngModel)]="userName">

    Provides two-way data-binding, parsing, and validation for form controls.

    -

    为表单控件提供双向数据绑定、解析和验证功能。

    +
    + - + + + + + + + + + + + + + + + + + +
    -

    Class decorators

    -

    类装饰器（decorator）

    -    		Class decorators

    import { Directive, ... } from '@angular/core'; +

    +
    @Component({...})
    class MyComponent() {}

    Declares that a class is a component and provides metadata about the component.

    -

    声明一个类是组件，并提供该组件的元数据。

    +
    @Directive({...})
    class MyDirective() {}

    Declares that a class is a directive and provides metadata about the directive.

    -

    声明一个类是指令，并提供该指令的元数据。

    +
    @Pipe({...})
    class MyPipe() {}

    Declares that a class is a pipe and provides metadata about the pipe.

    -

    声明一个类是管道，并提供该管道的元数据。

    +
    @Injectable()
    class MyService() {}

    Declares that a class has dependencies that should be injected into the constructor when the dependency injector is creating an instance of this class. +

    -

    声明一个类具有一些依赖，当依赖注入器试图创建该类的实例时，应该把这些依赖注入到该类的构造函数中。

    +
    + - + + + + + + + + + + + +
    -

    Directive configuration

    -

    指令配置

    -    		Directive configuration

    @Directive({ property1: value1, ... }) +

    +
    selector: '.cool-button:not(a)'

    Specifies a CSS selector that identifies this directive within a template. Supported selectors include element, + [attribute], .class, and :not().

    -

    指定一个 CSS 选择器，用于在模板中标记出该指令。支持的选择器类型包括：元素名、[属性名], .类名 和 :not()。

    +

    Does not support parent-child relationship selectors.

    -

    但不支持指定父子关系的选择器。

    +
    providers: [MyService, { provide: ... }]

    List of dependency injection providers for this directive and its children.

    -

    该指令及其子指令的依赖注入提供商列表。

    +
    + - + + + + + + + + + + + + + + + + + +
    -

    Component configuration

    -

    组件配置

    -    		Component configuration

    + @Component extends @Directive, -so the @Directive configuration applies to components as well

    -

    @Component 继承自 @Directive，因此 @Directive 的配置也能用于 @Component。

    +so the + + @Directive configuration applies to components as well

    +
    moduleId: module.id

    If set, the templateUrl and styleUrl are resolved relative to the component.

    -

    如果设置了，那么 templateUrl 和 styleUrl 的路径就会相对于当前组件进行解析。

    +
    viewProviders: [MyService, { provide: ... }]

    List of dependency injection providers scoped to this component's view.

    -

    依赖注入提供商列表，但它们的范围被限定为当前组件的视图。

    +
    template: 'Hello {{name}}'
    templateUrl: 'my-component.html'

    Inline template or external template URL of the component's view.

    -

    当前组件视图的内联模板或外部模板的 URL 。

    +
    styles: ['.primary {color: red}']
    styleUrls: ['my-component.css']

    List of inline CSS styles or external stylesheet URLs for styling the component’s view.

    -

    用于为当前组件的视图提供样式的内联 CSS 或外部样式表 URL 的列表。

    +
    + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    -

    Class field decorators for directives and components

    -

    给指令或组件类用的属性装饰器

    -    		Class field decorators for directives and components

    import { Input, ... } from '@angular/core'; +

    +
    @Input() myProperty;

    Declares an input property that you can update via property binding (example: + <my-cmp [myProperty]="someExpression">).

    -

    声明一个输入属性，你可以通过属性绑定来更新它，如 <my-cmp [myProperty]="someExpression">。

    +
    @Output() myEvent = new EventEmitter();

    Declares an output property that fires events that you can subscribe to with an event binding (example: <my-cmp (myEvent)="doSomething()">).

    -

    声明一个输出属性，它发出事件，你可以用事件绑定来订阅它们（如：<my-cmp (myEvent)="doSomething()">）。

    +
    @HostBinding('class.valid') isValid;

    Binds a host element property (here, the CSS class valid) to a directive/component property (isValid).

    -

    把宿主元素的一个属性（这里是 CSS 类 valid）绑定到指令或组件上的 isValid 属性。

    +
    @HostListener('click', ['$event']) onClick(e) {...}

    Subscribes to a host element event (click) with a directive/component method (onClick), optionally passing an argument ($event).

    -

    用指令或组件上的onClick方法订阅宿主元素上的click事件，并从中获取$event参数（可选）

    +
    @ContentChild(myPredicate) myChildComponent;

    Binds the first result of the component content query (myPredicate) to a property (myChildComponent) of the class.

    -

    把组件内容查询（myPredicate）的第一个结果绑定到该类的 myChildComponent 属性上。

    +
    @ContentChildren(myPredicate) myChildComponents;

    Binds the results of the component content query (myPredicate) to a property (myChildComponents) of the class.

    -

    把组件内容查询（myPredicate）的全部结果绑定到该类的 myChildComponents 属性上

    +
    @ViewChild(myPredicate) myChildComponent;

    Binds the first result of the component view query (myPredicate) to a property (myChildComponent) of the class. Not available for directives.

    -

    把组件视图查询（myPredicate）的第一个结果绑定到该类的 myChildComponent 属性上。对指令无效。

    +
    @ViewChildren(myPredicate) myChildComponents;

    Binds the results of the component view query (myPredicate) to a property (myChildComponents) of the class. Not available for directives.

    -

    把组件视图查询（myPredicate）的全部结果绑定到该类的 myChildComponents 属性上。对指令无效。

    +
    + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    -

    Directive and component change detection and lifecycle hooks

    -

    指令和组件的变更检测与生命周期钩子

    -    		Directive and component change detection and lifecycle hooks

    (implemented as class methods) +

    -

    由类的方法实现。

    +
    constructor(myService: MyService, ...) { ... }

    Called before any other lifecycle hook. Use it to inject dependencies, but avoid any serious work here.

    -

    在任何其它生命周期钩子之前调用。可以用它来注入依赖项，但不要在这里做正事。

    +
    ngOnChanges(changeRecord) { ... }

    Called after every change to input properties and before processing content or child views.

    -

    每当输入属性发生变化时就会调用，但位于处理内容（ng-content）或子视图之前。

    +
    ngOnInit() { ... }

    Called after the constructor, initializing input properties, and the first call to ngOnChanges.

    -

    在调用完构造函数、初始化完所有输入属性并首次调用过ngOnChanges之后调用。

    +
    ngDoCheck() { ... }

    Called every time that the input properties of a component or a directive are checked. Use it to extend change detection by performing a custom check.

    -

    每当对组件或指令的输入属性进行变更检测时就会调用。可以用它来扩展变更检测逻辑，执行自定义的检测逻辑。

    +
    ngAfterContentInit() { ... }

    Called after ngOnInit when the component's or directive's content has been initialized.

    -

    ngOnInit完成之后，当组件或指令的内容（ng-content）已经初始化完毕时调用。

    +
    ngAfterContentChecked() { ... }

    Called after every check of the component's or directive's content.

    -

    每当组件或指令的内容（ng-content）做变更检测时调用。

    +
    ngAfterViewInit() { ... }

    Called after ngAfterContentInit when the component's view has been initialized. Applies to components only.

    -

    当ngAfterContentInit完毕，并且组件的视图已经初始化完毕时调用。只适用于组件。

    +
    ngAfterViewChecked() { ... }

    Called after every check of the component's view. Applies to components only.

    -

    当组件视图每次执行变更检测时调用。只适用于组件。

    +
    ngOnDestroy() { ... }

    Called once, before the instance is destroyed.

    -

    只在实例被销毁前调用一次。

    +
    + - + + + + + + + + + + + + + + +
    -

    Dependency injection configuration

    -

    依赖注入的配置

    -    		Dependency injection configuration
    { provide: MyService, useClass: MyMockService }

    Sets or overrides the provider for MyService to the MyMockService class.

    -

    把 MyService 的服务提供商设置或改写为 MyMockService 类。

    +
    { provide: MyService, useFactory: myFactory }

    Sets or overrides the provider for MyService to the myFactory factory function.

    -

    把 MyService 的服务提供商设置或改写为 myFactory 工厂函数。

    +
    { provide: MyValue, useValue: 41 }

    Sets or overrides the provider for MyValue to the value 41.

    -

    把 MyValue 的服务提供商改写为一个特定的值 41 。

    +
    + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    -

    Routing and navigation

    -

    路由与导航

    -    		Routing and navigation

    import { Routes, RouterModule, ... } from '@angular/router'; +

    +
    const routes: Routes = [
    { path: '', component: HomeComponent },
    { path: 'path/:routeParam', component: MyComponent },
    { path: 'staticPath', component: ... },
    { path: '**', component: ... },
    { path: 'oldPath', redirectTo: '/staticPath' },
    { path: ..., component: ..., data: { message: 'Custom' } }
    ]);

    const routing = RouterModule.forRoot(routes);

    Configures routes for the application. Supports static, parameterized, redirect, and wildcard routes. Also supports custom route data and resolve.

    -

    为该应用配置路由。支持静态、参数化、重定向和通配符路由。也支持自定义路由数据和解析（resolve）函数。

    +

    <router-outlet></router-outlet>
    <router-outlet name="aux"></router-outlet>

    Marks the location to load the component of the active route.

    -

    标记出一个位置，用来加载活动路由的组件。

    +

    <a routerLink="/path">
    <a [routerLink]="[ '/path', routeParam ]">
    <a [routerLink]="[ '/path', { matrixParam: 'value' } ]">
    <a [routerLink]="[ '/path' ]" [queryParams]="{ page: 1 }">
    <a [routerLink]="[ '/path' ]" fragment="anchor">

    Creates a link to a different view based on a route instruction consisting of a route path, required and optional parameters, query parameters, and a fragment. To navigate to a root route, use the / prefix; for a child route, use the ./prefix; for a sibling or parent, use the ../ prefix.

    -

    使用路由体系创建一个到其它视图的链接。路由体系由路由路径、必要参数、可选参数、查询参数和文档片段组成。要导航到根路由，请使用/前缀；要导航到子路由，使用./前缀；要导航到兄弟路由或父级路由，使用../前缀。

    +
    <a [routerLink]="[ '/path' ]" routerLinkActive="active">

    The provided classes are added to the element when the routerLink becomes the current active route.

    -

    当 routerLink 指向的路由变成活动路由时，为当前元素添加一些类（比如这里的 active）。

    +
    class CanActivateGuard implements CanActivate {
    canActivate(
    route: ActivatedRouteSnapshot,
    state: RouterStateSnapshot
    ): Observable<boolean>|Promise<boolean>|boolean { ... }
    }

    { path: ..., canActivate: [CanActivateGuard] }

    An interface for defining a class that the router should call first to determine if it should activate this component. Should return a boolean or an Observable/Promise that resolves to a boolean.

    -

    用来定义类的接口。路由器会首先调用本接口来决定是否激活该路由。应该返回一个 boolean 或能解析成 boolean 的 Observable/Promise。

    +
    class CanDeactivateGuard implements CanDeactivate<T> {
    canDeactivate(
    component: T,
    route: ActivatedRouteSnapshot,
    state: RouterStateSnapshot
    ): Observable<boolean>|Promise<boolean>|boolean { ... }
    }

    { path: ..., canDeactivate: [CanDeactivateGuard] }

    An interface for defining a class that the router should call first to determine if it should deactivate this component after a navigation. Should return a boolean or an Observable/Promise that resolves to a boolean.

    -

    用来定义类的接口。路由器会在导航离开前首先调用本接口以决定是否取消激活本路由。应该返回一个 boolean 或能解析成 boolean 的 Observable/Promise。

    +
    class CanActivateChildGuard implements CanActivateChild {
    canActivateChild(
    route: ActivatedRouteSnapshot,
    state: RouterStateSnapshot
    ): Observable<boolean>|Promise<boolean>|boolean { ... }
    }

    { path: ..., canActivateChild: [CanActivateGuard],
    children: ... }

    An interface for defining a class that the router should call first to determine if it should activate the child route. Should return a boolean or an Observable/Promise that resolves to a boolean.

    -

    用来定义类的接口。路由器会首先调用本接口来决定是否激活一个子路由。应该返回一个 boolean 或能解析成 boolean 的 Observable/Promise。

    +
    class ResolveGuard implements Resolve<T> {
    resolve(
    route: ActivatedRouteSnapshot,
    state: RouterStateSnapshot
    ): Observable<any>|Promise<any>|any { ... }
    }

    { path: ..., resolve: [ResolveGuard] }

    An interface for defining a class that the router should call first to resolve route data before rendering the route. Should return a value or an Observable/Promise that resolves to a value.

    -

    用来定义类的接口。路由器会在渲染该路由之前，首先调用它来解析路由数据。应该返回一个值或能解析成值的 Observable/Promise。

    +
    class CanLoadGuard implements CanLoad {
    canLoad(
    route: Route
    ): Observable<boolean>|Promise<boolean>|boolean { ... }
    }

    { path: ..., canLoad: [CanLoadGuard], loadChildren: ... }

    An interface for defining a class that the router should call first to check if the lazy loaded module should be loaded. Should return a boolean or an Observable/Promise that resolves to a boolean.

    -

    用来定义类的接口。路由器会首先调用它来决定是否应该加载一个惰性加载模块。应该返回一个 boolean 或能解析成 boolean 的 Observable/Promise。

    +
    +
    + diff --git a/aio/content/guide/comparing-observables.md b/aio/content/guide/comparing-observables.md index 9cb663cd56..2587f67cb7 100644 --- a/aio/content/guide/comparing-observables.md +++ b/aio/content/guide/comparing-observables.md @@ -16,52 +16,53 @@ Observables are often compared to promises. Here are some key differences: * Observables `subscribe()` is responsible for handling errors. Promises push errors to the child promises. This makes observables useful for centralized and predictable error handling. - ### Creation and subscription * Observables are not executed until a consumer subcribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values. + // declare a publishing operation new Observable((observer) => { subscriber_fn }); // initiate execution observable.subscribe(() => { // observer handles notifications }); + * Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All `then` clauses (subscriptions) share the same computation. + // initiate execution new Promise((resolve, reject) => { executer_fn }); // handle return value promise.then((value) => { // handle result here }); + ### Chaining * Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values. - observable.map((v) => 2*v); - * Promises do not differentiate between the last `.then` clauses (equivalent to subscription) and intermediate `.then` clauses (equivalent to map). - promise.then((v) => 2*v); - ### Cancellation * Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work. + const sub = obs.subscribe(...); sub.unsubscribe(); + * Promises are not cancellable. @@ -71,17 +72,21 @@ sub.unsubscribe(); * Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable. + obs.subscribe(() => { throw Error('my error'); }); + * Promises push errors to the child promises. + promise.then(() => { throw Error('my error'); }); + ### Cheat sheet @@ -89,47 +94,89 @@ promise.then(() => { The following code snippets illustrate how the same kind of operation is defined using observables and promises. + + + + + + + + + + + + + + + + + + + + + + + + +
    + OperationObservablePromise
    Creation + 
    new Observable((observer) => {
   observer.next(123);
-});
    +}); + + +     		+ 
    new Promise((resolve, reject) => {
   resolve(123);
-});
    +}); + + +
    Transform
    obs.map((value) => value * 2 );
    promise.then((value) => value * 2);
    Subscribe + 
    sub = obs.subscribe((value) => {
   console.log(value)
-});
    +}); + + +     		+ 
    promise.then((value) => {
   console.log(value);
-});
    +}); + + +
    Unsubscribe
    sub.unsubscribe();
    		Implied by promise resolution.
    ## Observables compared to events API @@ -141,22 +188,35 @@ Using observables to handle events and asynchronous operations can have the adva Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API. + + + + + + + + + + + + + + + + + - -
    + ObservableEvents API
    Creation & cancellation + 
    // Setup
 let clicks$ = fromEvent(buttonEl, ‘click’);
 // Begin listening
 let subscription = clicks$
   .subscribe(e => console.log(‘Clicked’, e))
 // Stop listening
-subscription.unsubscribe();
    +subscription.unsubscribe(); + + +     		+ 
    function handler(e) {
   console.log(‘Clicked’, e);
 }
@@ -165,106 +225,196 @@ subscription.unsubscribe();
    button.addEventListener(‘click’, handler); // Stop listening button.removeEventListener(‘click’, handler); + +
    Subscription + 
    observable.subscribe(() => {
   // notification handlers here
-});
    +}); + + +     		+ 
    element.addEventListener(eventName, (event) => {
   // notification handler here
-});
    +}); + + +
    ConfigurationListen for keystrokes, but provide a stream representing the value in the input. 
    fromEvent(inputEl, 'keydown').pipe(
   map(e => e.target.value)
-);
    +); + + +     		Does not support configuration. 
    element.addEventListener(eventName, (event) => {
   // Cannot change the passed Event into another
   // value before it gets to the handler
-});
    -
    +}); + + +
    ## Observables compared to arrays An observable produces values over time. An array is created as a static set of values. In a sense, observables are asynchronous where arrays are synchronous. In the following examples, ➞ implies asynchronous value delivery. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + ObservableArray
    Given + 
    obs: ➞1➞2➞3➞5➞7
    + 
    obsB: ➞'a'➞'b'➞'c'
    +     		+ 
    arr: [1, 2, 3, 5, 7]
    + 
    arrB: ['a', 'b', 'c']
    + 
    concat()
    		 + 
    obs.concat(obsB)
    + 
    ➞1➞2➞3➞5➞7➞'a'➞'b'➞'c'
    +     		+ 
    arr.concat(arrB)
    + 
    [1,2,3,5,7,'a','b','c']
    + 
    filter()
    		 + 
    obs.filter((v) => v>3)
    + 
    ➞5➞7
    +     		+ 
    arr.filter((v) => v>3)
    + 
    [5, 7]
    + 
    find()
    		 + 
    obs.find((v) => v>3)
    + 
    ➞5
    +     		+ 
    arr.find((v) => v>10)
    + 
    5
    + 
    findIndex()
    		 + 
    obs.findIndex((v) => v>3)
    + 
    ➞3
    +     		+ 
    arr.findIndex((v) => v>3)
    + 
    3
    + 
    forEach()
    		 + 
    obs.forEach((v) => {
   console.log(v);
 })
@@ -272,9 +422,14 @@ An observable produces values over time. An array is created as a static set of
 2
 3
 4
-5
    +5 + + +     		+ 
    arr.forEach((v) => {
   console.log(v);
 })
@@ -282,32 +437,57 @@ An observable produces values over time. An array is created as a static set of
 2
 3
 4
-5
    +5 + + + 
    map()
    		 + 
    obs.map((v) => -v)
    + 
    ➞-1➞-2➞-3➞-5➞-7
    +     		+ 
    arr.map((v) => -v)
    + 
    [-1, -2, -3, -5, -7]
    + 
    reduce()
    		 + 
    obs.scan((s,v)=> s+v, 0)
    + 
    ➞1➞3➞6➞11➞18
    +     		+ 
    arr.reduce((s,v) => s+v, 0)
    + 
    18
    +
    - - diff --git a/aio/content/guide/component-interaction.md b/aio/content/guide/component-interaction.md index 36c469bfac..1c5aeee5a6 100644 --- a/aio/content/guide/component-interaction.md +++ b/aio/content/guide/component-interaction.md @@ -9,19 +9,6 @@ in which two or more components share information. 本烹饪宝典包含了常见的组件通讯场景，也就是让两个或多个组件之间共享信息的方法。 - -
    - - - -For an in-depth look at each fundamental concepts in component communication, we can find detailed description and -samples in the [Component Communication]() document. - -要深入了解组件通讯的各个基本概念，在[组件通讯]()文档中可以找到详细的描述和例子。 - - -
    - {@a toc} @@ -62,60 +49,49 @@ samples in the [Component Communication]() document. ## 通过输入型绑定把数据从父组件传到子组件。 -`HeroChildComponent` has two ***input properties***, +`HeroChildComponent` has two ***input properties***, typically adorned with [@Input decorations](guide/template-syntax#inputs-outputs). `HeroChildComponent` 有两个***输入型属性***，它们通常带[@Input装饰器](guide/template-syntax#inputs-outputs)。 - - - The second `@Input` aliases the child component property name `masterName` as `'master'`. 第二个`@Input`为子组件的属性名`masterName`指定一个别名`master`(译者注：不推荐为起别名，请参见风格指南). -The `HeroParentComponent` nests the child `HeroChildComponent` inside an `*ngFor` repeater, -binding its `master` string property to the child's `master` alias, and each iteration's `hero` instance to the child's `hero` property. +The `HeroParentComponent` nests the child `HeroChildComponent` inside an `*ngFor` repeater, +binding its `master` string property to the child's `master` alias, +and each iteration's `hero` instance to the child's `hero` property. 父组件`HeroParentComponent`把子组件的`HeroChildComponent`放到`*ngFor`循环器中，把自己的`master`字符串属性绑定到子组件的`master`别名上，并把每个循环的`hero`实例绑定到子组件的`hero`属性。 - - - The running application displays three heroes: 运行应用程序会显示三个英雄： -
    + Parent-to-child +
    - -

    Test it

    -### 测试 - E2E test that all children were instantiated and displayed as expected: 端到端测试，用于确保所有的子组件都像所期待的那样被初始化并显示出来。 - - - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) @@ -130,50 +106,39 @@ Use an input property setter to intercept and act upon a value from the parent. 使用一个输入属性的setter，以拦截父组件中值的变化，并采取行动。 -The setter of the `name` input property in the child `NameChildComponent` -trims the whitespace from a name and replaces an empty value with default text. +The setter of the `name` input property in the child `NameChildComponent` +trims the whitespace from a name and replaces an empty value with default text. 子组件`NameChildComponent`的输入属性`name`上的这个setter，会trim掉名字里的空格，并把空值替换成默认字符串。 - - - Here's the `NameParentComponent` demonstrating name variations including a name with all spaces: 下面的`NameParentComponent`展示了各种名字的处理方式，包括一个全是空格的名字。 - - -
    + Parent-to-child-setter +
    - -

    Test it

    -### 测试 - E2E tests of input property setter with empty and non-empty names: 端到端测试：输入属性的setter，分别使用空名字和非空名字。 - - - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) @@ -188,11 +153,8 @@ Detect and act upon changes to input property values with the `ngOnChanges()` me 使用`OnChanges`生命周期钩子接口的`ngOnChanges()`方法来监测输入属性值的变化并做出回应。 -
    - - You may prefer this approach to the property setter when watching multiple, interacting input properties. 当需要监视多个、交互式输入属性的时候，本方法比用属性的setter更合适。 @@ -201,60 +163,47 @@ Learn about `ngOnChanges()` in the [LifeCycle Hooks](guide/lifecycle-hooks) chap 学习关于`ngOnChanges()`的更多知识，参见[生命周期钩子](guide/lifecycle-hooks)一章。 -
    - - This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes: 这个`VersionChildComponent`会监测输入属性`major`和`minor`的变化，并把这些变化编写成日志以报告这些变化。 - - - The `VersionParentComponent` supplies the `minor` and `major` values and binds buttons to methods that change them. `VersionParentComponent`提供`minor`和`major`值，把修改它们值的方法绑定到按钮上。 - - - Here's the output of a button-pushing sequence: 下面是点击按钮的结果。 -
    + Parent-to-child-onchanges +
    - -

    Test it

    -### 测试 +

    测试一下

    -Test that ***both*** input properties are set initially and that button clicks trigger +Test that ***both*** input properties are set initially and that button clicks trigger the expected `ngOnChanges` calls and values: 测试确保***这两个***输入属性值都被初始化了，当点击按钮后，`ngOnChanges`应该被调用，属性的值也符合预期。 - - - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) @@ -265,108 +214,92 @@ the expected `ngOnChanges` calls and values: ## 父组件监听子组件的事件 -The child component exposes an `EventEmitter` property with which it `emits`events when something happens. +The child component exposes an `EventEmitter` property with which it `emits` events when something happens. The parent binds to that event property and reacts to those events. 子组件暴露一个`EventEmitter`属性，当事件发生时，子组件利用该属性`emits`(向上弹射)事件。父组件绑定到这个事件属性，并在事件发生时作出回应。 -The child's `EventEmitter` property is an ***output property***, +The child's `EventEmitter` property is an ***output property***, typically adorned with an [@Output decoration](guide/template-syntax#inputs-outputs) as seen in this `VoterComponent`: - -子组件的`EventEmitter`属性是一个**输出属性**，通常带有[@Output装饰器](guide/template-syntax#inputs-outputs)，就像在`VoterComponent`中看到的。 +子组件的`EventEmitter`属性是一个**输出属性**，通常带有[@Output装饰器](guide/template-syntax#inputs-outputs)，就像在`VoterComponent`中看到的。 - - -Clicking a button triggers emission of a `true` or `false` ,the boolean *payload*. +Clicking a button triggers emission of a `true` or `false`, the boolean *payload*. 点击按钮会触发`true`或`false`(布尔型*有效载荷*)的事件。 -The parent `VoteTakerComponent` binds an event handler called`onVoted()` that responds to the child event +The parent `VoteTakerComponent` binds an event handler called `onVoted()` that responds to the child event payload `$event` and updates a counter. 父组件`VoteTakerComponent`绑定了一个事件处理器(`onVoted()`)，用来响应子组件的事件(`$event`)并更新一个计数器。 - - - -The framework passes the event argument — represented by `$event` — to the handler method, +The framework passes the event argument—represented by `$event`—to the handler method, and the method processes it: 框架(Angular)把事件参数(用`$event`表示)传给事件处理方法，这个方法会处理： -
    + Child-to-parent +
    - -

    Test it

    -### 测试 +

    测试一下

    Test that clicking the *Agree* and *Disagree* buttons update the appropriate counters: 测试确保点击*Agree*和*Disagree*按钮时，计数器被正确更新。 - - - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) - - ## Parent interacts with child via *local variable* ## 父组件与子组件通过*本地变量*互动 A parent component cannot use data binding to read child properties -or invoke child methods. You can do both +or invoke child methods. You can do both by creating a template reference variable for the child element and then reference that variable *within the parent template* as seen in the following example. 父组件不能使用数据绑定来读取子组件的属性或调用子组件的方法。但可以在父组件模板里，新建一个本地变量来代表子组件，然后利用这个变量来读取子组件的属性和调用子组件的方法，如下例所示。 -{@a countdown-timer-example} -The following is a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket. It has `start` and `stop` methods that control the clock and it displays a countdown status message in its own template. - -子组件`CountdownTimerComponent`进行倒计时，归零时发射一个导弹。`start`和`stop`方法负责控制时钟并在模板里显示倒计时的状态信息。 +{@a countdown-timer-example} +The following is a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket. +It has `start` and `stop` methods that control the clock and it displays a +countdown status message in its own template. +子组件`CountdownTimerComponent`进行倒计时，归零时发射一个导弹。`start`和`stop`方法负责控制时钟并在模板里显示倒计时的状态信息。 - - -The `CountdownLocalVarParentComponent` that hosts the timer componentis as follows: +The `CountdownLocalVarParentComponent` that hosts the timer component is as follows: 让我们来看看计时器组件的宿主组件`CountdownLocalVarParentComponent`。 - - - The parent component cannot data bind to the child's `start` and `stop` methods nor to its `seconds` property. @@ -387,19 +320,17 @@ Here we see the parent and child working together. 下面是父组件和子组件一起工作时的效果。 -
    + countdown timer +
    - - {@a countdown-tests} -

    Test it

    -### 测试 +

    测试一下

    Test that the seconds displayed in the parent template match the seconds displayed in the child's status message. @@ -407,13 +338,10 @@ Test also that clicking the *Stop* button pauses the countdown timer: 测试确保在父组件模板中显示的秒数和子组件状态信息里的秒数同步。它还会点击*Stop*按钮来停止倒计时： - - - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) @@ -448,36 +376,27 @@ The child [CountdownTimerComponent](guide/component-interaction#countdown-timer- 下面的例子用与[倒计时](guide/component-interaction#countdown-timer-example)相同的范例来解释这种技术。 我们没有改变它的外观或行为。子组件[CountdownTimerComponent](guide/component-interaction#countdown-timer-example)也和原来一样。 -
    - - The switch from the *local variable* to the *ViewChild* technique is solely for the purpose of demonstration. 由*本地变量*切换到*ViewChild*技术的唯一目的就是做示范。 -
    - - Here is the parent, `CountdownViewChildParentComponent`: 下面是父组件`CountdownViewChildParentComponent`: - - - It takes a bit more work to get the child view into the parent component *class*. 把子组件的视图插入到父组件类需要做一点额外的工作。 - + First, you have to import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook. 首先，你要使用`ViewChild`装饰器导入这个引用，并挂上`AfterViewInit`生命周期钩子。 @@ -487,8 +406,8 @@ via the `@ViewChild` property decoration. 接着，通过`@ViewChild`属性装饰器，将子组件`CountdownTimerComponent`注入到私有属性`timerComponent`里面。 -The `#timer` local variable is gone from the component metadata. -Instead , bind the buttons to the parent component's own `start` and `stop` methods and +The `#timer` local variable is gone from the component metadata. +Instead, bind the buttons to the parent component's own `start` and `stop` methods and present the ticking seconds in an interpolation around the parent component's `seconds` method. 组件元数据里就不再需要`#timer`本地变量了。而是把按钮绑定到父组件自己的`start`和`stop`方法，使用父组件的`seconds`方法的插值表达式来展示秒数变化。 @@ -517,13 +436,12 @@ that it takes future values from the timer component.

    Test it

    -

    测试一下！

    +

    测试一下

    Use [the same countdown timer tests](guide/component-interaction#countdown-tests) as before. 使用和之前[一样的倒计时测试](guide/component-interaction#countdown-tests)。 - [Back to top](guide/component-interaction#top) [回到顶部](guide/component-interaction#top) @@ -534,11 +452,12 @@ Use [the same countdown timer tests](guide/component-interaction#countdown-tests ## 父组件和子组件通过服务来通讯 -A parent component and its children share a service whose interface enables bi-directional communication *within the family*. +A parent component and its children share a service whose interface enables bi-directional communication +*within the family*. 父组件和它的子组件共享同一个服务，利用该服务*在家庭内部*实现双向通讯。 -The scope of the service instance is the parent component and its children. +The scope of the service instance is the parent component and its children. Components outside this component subtree have no access to the service or their communications. 该服务实例的作用域被限制在父组件和其子组件内。这个组件子树之外的组件将无法访问该服务或者与它们通讯。 @@ -547,41 +466,30 @@ This `MissionService` connects the `MissionControlComponent` to multiple `Astron 这个`MissionService`把`MissionControlComponent`和多个`AstronautComponent`子组件连接起来。 - - - The `MissionControlComponent` both provides the instance of the service that it shares with its children (through the `providers` metadata array) and injects that instance into itself through its constructor: `MissionControlComponent`提供服务的实例，并将其共享给它的子组件(通过`providers`元数据数组)，子组件可以通过构造函数将该实例注入到自身。 - - - The `AstronautComponent` also injects the service in its constructor. Each `AstronautComponent` is a child of the `MissionControlComponent` and therefore receives its parent's service instance: `AstronautComponent`也通过自己的构造函数注入该服务。由于每个`AstronautComponent`都是`MissionControlComponent`的子组件，所以它们获取到的也是父组件的这个服务实例。 - - -
    - - Notice that this example captures the `subscription` and `unsubscribe()` when the `AstronautComponent` is destroyed. This is a memory-leak guard step. There is no actual risk in this app because the lifetime of a `AstronautComponent` is the same as the lifetime of the app itself. @@ -595,40 +503,34 @@ it controls the lifetime of the `MissionService`. 不需要在`MissionControlComponent`中添加这个保护措施，因为它作为父组件，控制着`MissionService`的生命期。 -
    - - The *History* log demonstrates that messages travel in both directions between the parent `MissionControlComponent` and the `AstronautComponent` children, facilitated by the service: *History*日志证明了：在父组件`MissionControlComponent`和子组件`AstronautComponent`之间，信息通过该服务实现了双向传递。 -
    + bidirectional-service +
    - -

    Test it

    -### 测试 +

    测试一下

    Tests click buttons of both the parent `MissionControlComponent` and the `AstronautComponent` children and verify that the history meets expectations: 测试确保点击父组件`MissionControlComponent`和子组件`AstronautComponent`两个的组件的按钮时，*History*日志和预期的一样。 - - - [Back to top](guide/component-interaction#top) + [回到顶部](guide/component-interaction#top) \ No newline at end of file diff --git a/aio/content/guide/component-styles.md b/aio/content/guide/component-styles.md index 5139f4e204..d70055fab6 100644 --- a/aio/content/guide/component-styles.md +++ b/aio/content/guide/component-styles.md @@ -20,7 +20,7 @@ This page describes how to load and apply these component styles. You can run the in Stackblitz and download the code from there. -你可以在Plunker上运行本章这些代码的并下载这些代码。 +你可以在 Stackblitz 上运行本章这些代码的并下载这些代码。 ## Using component styles @@ -41,8 +41,8 @@ Usually you give it one string, as in the following example: `styles`属性可以接受一个包含 CSS 代码的字符串数组。 通常我们只给它一个字符串就行了，如同下例： - + ## Style scope @@ -70,29 +70,28 @@ This scoping restriction is a ***styling modularity feature***. 这种范围限制就是所谓的***样式模块化***特性 -* You can use the CSS class names and selectors that make the most sense in the context of each component. +* You can use the CSS class names and selectors that make the most sense in the context of each component. + + 可以使用对每个组件最有意义的 CSS 类名和选择器。 - 可以使用对每个组件最有意义的 CSS 类名和选择器。 - * Class names and selectors are local to the component and don't collide with classes and selectors used elsewhere in the application. - - 类名和选择器是仅属于组件内部的，它不会和应用中其它地方的类名和选择器出现冲突。 - + + 类名和选择器是仅属于组件内部的，它不会和应用中其它地方的类名和选择器出现冲突。 + * Changes to styles elsewhere in the application don't affect the component's styles. - 我们组件的样式*不会*因为别的地方修改了样式而被意外改变。 - + 我们组件的样式*不会*因为别的地方修改了样式而被意外改变。 + * You can co-locate the CSS code of each component with the TypeScript and HTML code of the component, which leads to a neat and tidy project structure. - - 我们可以让每个组件的 CSS 代码和它的 TypeScript、HTML 代码放在一起，这将促成清爽整洁的项目结构。 - + + 我们可以让每个组件的 CSS 代码和它的 TypeScript、HTML 代码放在一起，这将促成清爽整洁的项目结构。 + * You can change or remove component CSS code without searching through the whole application to find where else the code is used. - 将来我们可以修改或移除组件的 CSS 代码，而不用遍历整个应用来看它有没有被别处用到，只要看看当前组件就可以了。 - + 将来我们可以修改或移除组件的 CSS 代码，而不用遍历整个应用来看它有没有被别处用到，只要看看当前组件就可以了。 {@a special-selectors} @@ -116,8 +115,8 @@ targeting elements *inside* the component's template). 使用`:host`伪类选择器，用来选择组件*宿主*元素中的元素（相对于组件模板*内部*的元素）。 - + The `:host` selector is the only way to target the host element. You can't reach @@ -133,10 +132,11 @@ including another selector inside parentheses after `:host`. 要把宿主样式作为条件，就要像*函数*一样把其它选择器放在`:host`后面的括号中。 The next example targets the host element again, but only when it also has the `active` CSS class. - + 在下一个例子中，我们又一次把宿主元素作为目标，但是只有当它同时带有`active` CSS 类的时候才会生效。 + ### :host-context @@ -159,10 +159,11 @@ up to the document root. The `:host-context()` selector is useful when combined The following example applies a `background-color` style to all `

    ` elements *inside* the component, only if some ancestor element has the CSS class `theme-light`. - + 在下面的例子中，只有当某个祖先元素有 CSS 类`theme-light`时，我们才会把`background-color`样式应用到组件*内部*的所有`

    `元素中。 + ### (deprecated) `/deep/`, `>>>`, and `::ng-deep` @@ -176,7 +177,7 @@ Component styles normally apply only to the HTML in the component's own template Use the `/deep/` shadow-piercing descendant combinator to force a style down through the child component tree into all the child component views. The `/deep/` combinator works to any depth of nested components, and it applies to both the view -children and content children of the component. +children and content children of the component. 我们可以使用`/deep/`选择器，来强制一个样式对各级子组件的视图也生效，它*不但作用于组件的子视图，也会作用于组件的内容*。 @@ -185,7 +186,6 @@ through this component to all of its child elements in the DOM. 在这个例子中，我们以所有的`

    `元素为目标，从宿主元素到当前元素再到 DOM 中的所有子元素： - @@ -204,7 +204,6 @@ Emulated is the default and most commonly used view encapsulation. For more info 这种方式是默认值，也是用得最多的方式。 更多信息，见[控制视图封装模式](guide/component-styles#view-encapsulation)一节。 -
    @@ -231,16 +230,16 @@ There are several ways to add styles to a component: * By setting `styles` or `styleUrls` metadata. - 设置`styles`或`styleUrls`元数据 - + 设置`styles`或`styleUrls`元数据 + * Inline in the template HTML. - 内联在模板的 HTML 中 - + 内联在模板的 HTML 中 + * With CSS imports. - 通过 CSS 文件导入 - + 通过 CSS 文件导入 + The scoping rules outlined earlier apply to each of these loading patterns. 上述作用域规则对所有这些加载模式都适用。 @@ -258,6 +257,7 @@ Each string in the array defines some CSS for this component. 这个数组中的每一个字符串（通常也只有一个）定义一份 CSS。 +
    @@ -275,7 +275,9 @@ The CLI defines an empty `styles` array when you create the component with the ` 当使用 `--inline-styles` 标识创建组件时，CLI 就会定义一个空的 `styles` 数组 + ng generate component hero-app --inline-style + ### Style files in component metadata @@ -288,8 +290,11 @@ to a component's `@Component` decorator: 我们可以通过把外部 CSS 文件添加到 `@Component` 的 `styleUrls` 属性中来加载外部样式。 + + +
    @@ -313,7 +318,9 @@ They are _not inherited_ by any components nested within the template nor by any The CLI creates an empty styles file for you by default and references that file in the component's generated `styleUrls`. + ng generate component hero-app + ### Template inline styles @@ -325,8 +332,8 @@ inside ` + + + + + + + + + + + + + + + + + + + + + +
    FrameworkTaskSpeed
    AngularJSRoutingFast
    Angular v2Routing *Faster*
    Angular v4Routing **Fastest :)**
    Here is the markup for this table. ```html + + + + + + + + + + + + + + + + + + + + + + +
    FrameworkTaskSpeed
    AngularJSRoutingFast
    Angular v2Routing *Faster*
    Angular v4Routing **Fastest :)**
    + ``` ## Images @@ -1173,14 +1395,20 @@ You should nest the `` tag within a `
    ` tag, which styles the image Here's a conforming example
    + flying hero +
    ```html +
    + flying hero +
    + ``` _Note that the HTML image element does not have a closing tag._ @@ -1192,16 +1420,21 @@ The doc generator reads the image dimensions from the file and adds width and he Here's the "flying hero" at a more reasonable scale.
    + flying Angular hero +
    ```html
    + flying Angular hero +
    + ``` Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports. @@ -1209,9 +1442,13 @@ Wide images can be a problem. Most browsers try to rescale the image but wide im **Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide: +
    + toh-pt6-bundle +
    +

    Image compression

    @@ -1247,6 +1484,7 @@ This text wraps around to the right of the floating "flying hero" image. Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
    ` where the text should break.
    + ``` Note that you generally don't wrap a floating image in a `
    ` element. @@ -1267,6 +1505,7 @@ If you have a floating image inside an alert, callout, or a subsection, it is a
    ```html +
    + ``` diff --git a/aio/content/guide/dynamic-component-loader.md b/aio/content/guide/dynamic-component-loader.md index 549e2fbb9d..6788e97047 100644 --- a/aio/content/guide/dynamic-component-loader.md +++ b/aio/content/guide/dynamic-component-loader.md @@ -13,7 +13,7 @@ This cookbook shows you how to use `ComponentFactoryResolver` to add components See the of the code in this cookbook. -到查看本烹饪书的源码。 +到查看本烹饪书的源码。 {@a dynamic-loading} @@ -42,7 +42,6 @@ Angular comes with its own API for loading components dynamically. Angular 自带的API就能支持动态加载组件。 - {@a directive} ## The anchor directive @@ -59,13 +58,10 @@ mark valid insertion points in the template. 广告条使用一个名叫`AdDirective`的辅助指令来在模板中标记出有效的插入点。 - - - `AdDirective` injects `ViewContainerRef` to gain access to the view container of the element that will host the dynamically added component. @@ -99,22 +95,17 @@ where to dynamically load components. 要应用`AdDirective`，回忆一下来自`ad.directive.ts`的选择器`ad-host`。把它应用到``（不用带方括号）。 这下，Angular就知道该把组件动态加载到哪里了。 - - - The `` element is a good choice for dynamic components because it doesn't render any additional output. ``元素是动态加载组件的最佳选择，因为它不会渲染任何额外的输出。 - {@a resolving-components} - ## Resolving components ## 解析组件 @@ -142,24 +133,18 @@ and loads a new component every 3 seconds by calling `loadComponent()`. 通过`getAds()`方法，`AdBannerComponent`可以循环遍历`AdItems`的数组，并且每三秒调用一次`loadComponent()`来加载新组件。 - - - The `loadComponent()` method is doing a lot of the heavy lifting here. Take it step by step. First, it picks an ad. 这里的`loadComponent()`方法很重要。 我们来一步步看看。首先，它选取了一个广告。 -
    - - **How _loadComponent()_ chooses an ad** **`loadComponent()`如何选择广告** @@ -176,11 +161,8 @@ value to select an `adItem` from the array. （译注：循环选取算法）首先，它把`currentAddIndex`递增一，然后用它除以`AdItem`数组长度的*余数*作为新的`currentAddIndex`的值， 最后用这个值来从数组中选取一个`adItem`。 -
    - - After `loadComponent()` selects an ad, it uses `ComponentFactoryResolver` to resolve a `ComponentFactory` for each specific component. The `ComponentFactory` then creates an instance of each component. @@ -212,10 +194,8 @@ Use that reference to interact with the component by assigning to its properties `createComponent()`方法返回一个引用，指向这个刚刚加载的组件。 使用这个引用就可以与该组件进行交互，比如设置它的属性或调用它的方法。 - {@a selector-references} - #### Selector references #### 对选择器的引用 @@ -233,16 +213,12 @@ add dynamically loaded components to the `NgModule`'s `entryComponents` array: 要想确保编译器照常生成工厂类，就要把这些动态加载的组件添加到`NgModule`的`entryComponents`数组中： - - - {@a common-interface} - ## The _AdComponent_ interface ## 公共的`AdComponent`接口 @@ -256,7 +232,6 @@ Here are two sample components and the `AdComponent` interface for reference: 下面就是两个范例组件及其`AdComponent`接口： - @@ -273,26 +248,23 @@ Here are two sample components and the `AdComponent` interface for reference: - - {@a final-ad-baner} - ## Final ad banner ## 最终的广告栏 -The final ad banner looks like this: - -最终的广告栏是这样的： + The final ad banner looks like this: + 最终的广告栏是这样的：
    + Ads +
    - - See the . + 参见。 \ No newline at end of file diff --git a/aio/content/guide/dynamic-form.md b/aio/content/guide/dynamic-form.md index 1efb848e7e..7f78b24bd6 100644 --- a/aio/content/guide/dynamic-form.md +++ b/aio/content/guide/dynamic-form.md @@ -4,17 +4,18 @@ {@a top} -Building handcrafted forms canbe costly and time-consuming, -especially if you need a great number of them, they're similar to each other, and they change frequently +Building handcrafted forms can be costly and time-consuming, +especially if you need a great number of them, they're similar to each other, and they change frequently to meet rapidly changing business and regulatory requirements. 有时候手动编写和维护表单所需工作量和时间会过大。特别是在需要编写大量表单时。表单都很相似，而且随着业务和监管需求的迅速变化，表单也要随之变化，这样维护的成本过高。 -It may be more economical to create the forms dynamically, based on metadata that describes the business object model. +It may be more economical to create the forms dynamically, based on +metadata that describes the business object model. 基于业务对象模型的元数据，动态创建表单可能会更划算。 -This cookbook shows you how to use `formGroup` to dynamically +This cookbook shows you how to use `formGroup` to dynamically render a simple form with different control types and validation. It's a primitive start. It might evolve to support a much richer variety of questions, more graceful rendering, and superior user experience. @@ -23,10 +24,10 @@ All such greatness has humble beginnings. 在此烹饪宝典中，我们会展示如何利用`formGroup`来动态渲染一个简单的表单，包括各种控件类型和验证规则。 这个起点很简陋，但可以在这个基础上添加丰富多彩的问卷问题、更优美的渲染以及更卓越的用户体验。 -The example in this cookbook is a dynamic form to build an +The example in this cookbook is a dynamic form to build an online application experience for heroes seeking employment. The agency is constantly tinkering with the application process. -You can create the forms on the fly *without changing the application code*. +You can create the forms on the fly *without changing the application code*. 在本例中，我们使用动态表单，为正在找工作的英雄们创建一个在线申请表。英雄管理局会不断修改申请流程，我们要在*不修改应用代码*的情况下，动态创建这些表单。 @@ -36,12 +37,11 @@ See the . 参见。 - {@a bootstrap} ## Bootstrap -## 程序启动 +## 启动/引导 (bootstrap) Start by creating an `NgModule` called `AppModule`. @@ -61,7 +61,6 @@ Bootstrap the `AppModule` in `main.ts`. 我们在`main.ts`中启动`AppModule`。 - @@ -74,7 +73,6 @@ Bootstrap the `AppModule` in `main.ts`. - {@a object-model} ## Question model @@ -91,13 +89,10 @@ The following `QuestionBase` is a fundamental question class. 下面是我们建立的最基础的问卷问题基类，名叫`QuestionBase`。 - - - From this base you can derive two new classes in `TextboxQuestion` and `DropdownQuestion` that represent textbox and dropdown questions. The idea is that the form will be bound to specific question types and render the @@ -110,24 +105,18 @@ via the `type` property. `TextboxQuestion`可以通过`type`属性来支持多种HTML5元素类型，比如文本、邮件、网址等。 - - - `DropdownQuestion` presents a list of choices in a select box. `DropdownQuestion`表示一个带可选项列表的选择框。 - - - Next is `QuestionControlService`, a simple service for transforming the questions to a `FormGroup`. In a nutshell, the form group consumes the metadata from the question model and allows you to specify default values and validation rules. @@ -135,8 +124,6 @@ allows you to specify default values and validation rules. 接下来，我们定义了`QuestionControlService`，一个可以把问卷问题转换为`FormGroup`的服务。 简而言之，这个`FormGroup`使用问卷模型的元数据，并允许我们设置默认值和验证规则。 - - @@ -152,12 +139,10 @@ to create components to represent the dynamic form. 现在我们已经有一个定义好的完整模型了，接着就可以开始创建一个展现动态表单的组件。 - -`DynamicFormComponent` is the entry point and the main container for the form. +`DynamicFormComponent` is the entry point and the main container for the form. `DynamicFormComponent`是表单的主要容器和入口点。 - @@ -170,8 +155,6 @@ to create components to represent the dynamic form. - - It presents a list of questions, each bound to a `` component element. The `` tag matches the `DynamicFormQuestionComponent`, the component responsible for rendering the details of each _individual_ @@ -180,7 +163,6 @@ question based on values in the data-bound question object. 它代表了问卷问题列表，每个问题都被绑定到一个``组件元素。 ``标签匹配到的是组件`DynamicFormQuestionComponent`，该组件的职责是根据各个问卷问题对象的值来动态渲染表单控件。 - @@ -193,8 +175,6 @@ question based on values in the data-bound question object. - - Notice this component can present any type of question in your model. You only have two types of questions at this point but you can imagine many more. The `ngSwitch` determines which type of question to display. @@ -211,16 +191,16 @@ underlying control objects, populated from the question model with display and v directly since you imported `ReactiveFormsModule` from `AppModule`. `formControlName`和`formGroup`是在`ReactiveFormsModule`中定义的指令。我们之所以能在模板中使用它们，是因为我们往`AppModule`中导入了`ReactiveFormsModule`。 + {@a questionnaire-data} ## Questionnaire data ## 问卷数据 - `DynamicFormComponent` expects the list of questions in the form of an array bound to `@Input() questions`. - `DynamicForm`期望得到一个问题列表，该列表被绑定到`@Input() questions`属性。 +`DynamicForm`期望得到一个问题列表，该列表被绑定到`@Input() questions`属性。 The set of questions you've defined for the job application is returned from the `QuestionService`. In a real app you'd retrieve these questions from storage. @@ -231,22 +211,18 @@ directly since you imported `ReactiveFormsModule` from `AppModule`. entirely through the objects returned from `QuestionService`. Questionnaire maintenance is a simple matter of adding, updating, and removing objects from the `questions` array. - + 关键是，我们完全根据`QuestionService`返回的对象来控制英雄的工作申请表。 要维护这份问卷，只要非常简单的添加、更新和删除`questions`数组中的对象就可以了。 - - - Finally, display an instance of the form in the `AppComponent` shell. 最后，在`AppComponent`里显示出表单。 - @@ -257,16 +233,16 @@ Finally, display an instance of the form in the `AppComponent` shell. ## 动态模板 -Although in this example you're modelling a job application for heroes, there are +Although in this example you're modelling a job application for heroes, there are no references to any specific hero question outside the objects returned by `QuestionService`. 在这个例子中，虽然我们是在为英雄的工作申请表建模，但是除了`QuestionService`返回的那些对象外，没有其它任何地方是与英雄有关的。 This is very important since it allows you to repurpose the components for any type of survey -as long as it's compatible with the *question* object model. -The key is the dynamic data binding of metadata used to render the form -without making any hardcoded assumptions about specific questions. +as long as it's compatible with the *question* object model. +The key is the dynamic data binding of metadata used to render the form +without making any hardcoded assumptions about specific questions. In addition to control metadata, you are also adding validation dynamically. 这点非常重要，因为只要与*问卷*对象模型兼容，就可以在任何类型的调查问卷中复用这些组件。 @@ -280,18 +256,17 @@ Saving and retrieving the data is an exercise for another time. 表单验证通过之前，*保存*按钮是禁用的。验证通过后，就可以点击*保存*按钮，程序会把当前值渲染成JSON显示出来。 这表明任何用户输入都被传到了数据模型里。至于如何储存和提取数据则是另一话题了。 - The final form looks like this: 完整的表单是这样的： -
    + Dynamic-Form +
    - - [Back to top](guide/dynamic-form#top) -[回到顶部](guide/dynamic-form#top) + +[回到顶部](guide/dynamic-form#top) \ No newline at end of file diff --git a/aio/content/guide/entry-components.md b/aio/content/guide/entry-components.md index d57654218d..cffb6257eb 100644 --- a/aio/content/guide/entry-components.md +++ b/aio/content/guide/entry-components.md @@ -2,7 +2,12 @@ #### Prerequisites: +#### 前提条件： + A basic understanding of the following concepts: + +对下列概念有基本的理解： + * [Bootstrapping](guide/bootstrapping).
    @@ -15,16 +20,14 @@ To contrast the two types of components, there are components which are included
    - There are two main kinds of entry components: * The bootstrapped root component. + * A component you specify in a route definition. - ## A bootstrapped entry component - The following is an example of specifying a bootstrapped component, `AppComponent`, in a basic `app.module.ts`: @@ -58,12 +61,10 @@ it should generate code to bootstrap the application with this component.
    - A bootstrapped component is necessarily an entry component because bootstrapping is an imperative process, thus it needs to have an entry component. ## A routed entry component - The second kind of entry component occurs in a route definition like this: @@ -80,7 +81,6 @@ A route definition refers to a component by its type with `component: CustomerLi All router components must be entry components. Because this would require you to add the component in two places (router and `entryComponents`) the Compiler is smart enough to recognize that this is a router definition and automatically add the router component into `entryComponents`. - ## The `entryComponents` array Though the `@NgModule` decorator has an `entryComponents` array, most of the time @@ -101,13 +101,16 @@ If a component isn't an _entry component_ and isn't found in a template, the tree shaker will throw it away. So, it's best to add only the components that are truly entry components to help keep your app as trim as possible. -
    ## More on Angular modules You may also be interested in the following: + * [Types of NgModules](guide/module-types) + * [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules). + * [Providers](guide/providers). + * [NgModules FAQ](guide/ngmodule-faq). diff --git a/aio/content/guide/feature-modules.md b/aio/content/guide/feature-modules.md index 047a453de5..b80f6ffb92 100644 --- a/aio/content/guide/feature-modules.md +++ b/aio/content/guide/feature-modules.md @@ -3,9 +3,13 @@ Feature modules are NgModules for the purpose of organizing code. #### Prerequisites + A basic understanding of the following: + * [Bootstrapping](guide/bootstrapping). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). + * [Frequently Used Modules](guide/frequent-ngmodules). For the final sample app with a feature module that this page describes, @@ -20,7 +24,6 @@ separate from other code. Delineating areas of your app helps with collaboration between developers and teams, separating directives, and managing the size of the root module. - ## Feature modules vs. root modules A feature module is an organizational best practice, as opposed to a concept of the core Angular API. A feature module delivers a cohesive set of functionality focused on a @@ -43,7 +46,6 @@ ng generate module CustomerDashboard ``` - This causes the CLI to create a folder called `customer-dashboard` with a file inside called `customer-dashboard.module.ts` with the following contents: ```typescript @@ -71,12 +73,10 @@ ng generate component customer-dashboard/CustomerDashboard This generates a folder for the new component within the customer-dashboard folder and updates the feature module with the `CustomerDashboardComponent` info: - + - - The `CustomerDashboardComponent` is now in the JavaScript import list at the top and added to the `declarations` array, which lets Angular know to associate this new component with this feature module. ## Importing a feature module @@ -84,38 +84,37 @@ The `CustomerDashboardComponent` is now in the JavaScript import list at the top To incorporate the feature module into your app, you have to let the root module, `app.module.ts`, know about it. Notice the `CustomerDashboardModule` export at the bottom of `customer-dashboard.module.ts`. This exposes it so that other modules can get to it. To import it into the `AppModule`, add it to the imports in `app.module.ts` and to the `imports` array: + - Now the `AppModule` knows about the feature module. If you were to add any service providers to the feature module, `AppModule` would know about those too, as would any other feature modules. However, NgModules don’t expose their components. - ## Rendering a feature module’s component template When the CLI generated the `CustomerDashboardComponent` for the feature module, it included a template, `customer-dashboard.component.html`, with the following markup: - + To see this HTML in the `AppComponent`, you first have to export the `CustomerDashboardComponent` in the `CustomerDashboardModule`. In `customer-dashboard.module.ts`, just beneath the `declarations` array, add an `exports` array containing `CustomerDashboardModule`: + - - Next, in the `AppComponent`, `app.component.html`, add the tag ``: - + Now, in addition to the title that renders by default, the `CustomerDashboardComponent` template renders too: -
    + feature module component +
    @@ -123,6 +122,9 @@ Now, in addition to the title that renders by default, the `CustomerDashboardCom ## More on NgModules You may also be interested in the following: + * [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules). + * [Providers](guide/providers). + * [Types of Feature Modules](guide/module-types). diff --git a/aio/content/guide/form-validation.md b/aio/content/guide/form-validation.md index a73ff3d8ad..934e6fda08 100644 --- a/aio/content/guide/form-validation.md +++ b/aio/content/guide/form-validation.md @@ -2,9 +2,6 @@ # 表单验证 - - - Improve overall data quality by validating user input for accuracy and completeness. 我们可以通过验证用户输入的准确性和完整性，来增强整体数据质量。 @@ -15,7 +12,6 @@ forms modules. 在本烹饪书中，我们展示在界面中如何验证用户输入，并显示有用的验证信息，先使用模板驱动表单方式，再使用响应式表单方式。 -
    If you're new to forms, start by reviewing the [Forms](guide/forms) and @@ -23,10 +19,8 @@ If you're new to forms, start by reviewing the [Forms](guide/forms) and 参见[表单](guide/forms)和[响应式表单](guide/reactive-forms)了解关于这些选择的更多知识。 -
    - ## Template-driven validation ## 模板驱动验证 @@ -53,7 +47,6 @@ The following example exports `NgModel` into a variable called `name`: - Note the following: 请注意以下几点： @@ -62,33 +55,30 @@ Note the following: also carries a custom validator directive, `forbiddenName`. For more information, see [Custom validators](guide/form-validation#custom-validators) section. - ``元素带有一些HTML验证属性：`required` 和 `minlength`。它还带有一个自定义的验证器指令`forbiddenName`。要了解更多信息，参见[自定义验证器](guide/form-validation#custom-validators)一节。 + ``元素带有一些HTML验证属性：`required` 和 `minlength`。它还带有一个自定义的验证器指令`forbiddenName`。要了解更多信息，参见[自定义验证器](guide/form-validation#custom-validators)一节。 * `#name="ngModel"` exports `NgModel` into a local variable called `name`. `NgModel` mirrors many of the properties of its underlying `FormControl` instance, so you can use this in the template to check for control states such as `valid` and `dirty`. For a full list of control properties, see the [AbstractControl](api/forms/AbstractControl) API reference. - `#name="ngModel"`把`NgModel`导出成了一个名叫`name`的局部变量。`NgModel`把自己控制的`FormControl`实例的属性映射出去，让我们能在模板中检查控件的状态，比如`valid`和`dirty`。要了解完整的控件属性，参见 API 参考手册中的[AbstractControl](api/forms/AbstractControl)。 + `#name="ngModel"`把`NgModel`导出成了一个名叫`name`的局部变量。`NgModel`把自己控制的`FormControl`实例的属性映射出去，让我们能在模板中检查控件的状态，比如`valid`和`dirty`。要了解完整的控件属性，参见 API 参考手册中的[AbstractControl](api/forms/AbstractControl)。 * The `*ngIf` on the `
    ` element reveals a set of nested message `divs` but only if the `name` is invalid and the control is either `dirty` or `touched`. - `
    `元素的`*ngIf`揭露了一套嵌套消息`divs`，但是只在有“name”错误和控制器为`dirty`或者`touched`。 + `
    `元素的`*ngIf`揭露了一套嵌套消息`divs`，但是只在有“name”错误和控制器为`dirty`或者`touched`。 * Each nested `
    ` can present a custom message for one of the possible validation errors. There are messages for `required`, `minlength`, and `forbiddenName`. - - 每个嵌套的`
    `为其中一个可能出现的验证错误显示一条自定义消息。比如 `required`、`minlength`和 `forbiddenName`。 + + 每个嵌套的`
    `为其中一个可能出现的验证错误显示一条自定义消息。比如 `required`、`minlength`和 `forbiddenName`。
    - - #### Why check _dirty_ and _touched_? #### 为何检查**dirty**和**touched**？ - You may not want your application to display errors before the user has a chance to edit the form. The checks for `dirty` and `touched` prevent errors from showing until the user does one of two things: changes the value, @@ -117,13 +107,13 @@ There are two types of validator functions: sync validators and async validators * **Sync validators**: functions that take a control instance and immediately return either a set of validation errors or `null`. You can pass these in as the second argument when you instantiate a `FormControl`. - **同步验证器**函数接受一个控件实例，然后返回一组验证错误或`null`。我们可以在实例化一个`FormControl`时把它作为构造函数的第二个参数传进去。 + **同步验证器**函数接受一个控件实例，然后返回一组验证错误或`null`。我们可以在实例化一个`FormControl`时把它作为构造函数的第二个参数传进去。 * **Async validators**: functions that take a control instance and return a Promise or Observable that later emits a set of validation errors or `null`. You can pass these in as the third argument when you instantiate a `FormControl`. - **异步验证器**函数接受一个控件实例，并返回一个承诺（Promise）或可观察对象（Observable），它们稍后会发出一组验证错误或者`null`。我们可以在实例化一个`FormControl`时把它作为构造函数的第三个参数传进去。 + **异步验证器**函数接受一个控件实例，并返回一个承诺（Promise）或可观察对象（Observable），它们稍后会发出一组验证错误或者`null`。我们可以在实例化一个`FormControl`时把它作为构造函数的第三个参数传进去。 Note: for performance reasons, Angular only runs async validators if all sync validators pass. Each must complete before errors are set. @@ -150,6 +140,7 @@ built-in validators—this time, in function form. See below: {@a reactive-component-class} + Note that: @@ -158,38 +149,38 @@ Note that: * The name control sets up two built-in validators—`Validators.required` and `Validators.minLength(4)`—and one custom validator, `forbiddenNameValidator`. For more details see the [Custom validators](guide/form-validation#custom-validators) section in this guide. - `name`控件设置了两个内置验证器：`Validators.required` 和 `Validators.minLength(4)`。要了解更多信息，参见本章的[自定义验证器](guide/form-validation#custom-validators)一节。 + `name`控件设置了两个内置验证器：`Validators.required` 和 `Validators.minLength(4)`。要了解更多信息，参见本章的[自定义验证器](guide/form-validation#custom-validators)一节。 * As these validators are all sync validators, you pass them in as the second argument. - 由于这些验证器都是同步验证器，因此我们要把它们作为第二个参数传进去。 + 由于这些验证器都是同步验证器，因此我们要把它们作为第二个参数传进去。 * Support multiple validators by passing the functions in as an array. - 可以通过把这些函数放进一个数组后传进去，可以支持多重验证器。 + 可以通过把这些函数放进一个数组后传进去，可以支持多重验证器。 * This example adds a few getter methods. In a reactive form, you can always access any form control through the `get` method on its parent group, but sometimes it's useful to define getters as shorthands for the template. - 这个例子添加了一些getter方法。在响应式表单中，我们通常会通过它所属的控件组（FormGroup）的`get`方法来访问表单控件，但有时候为模板定义一些getter作为简短形式。 + 这个例子添加了一些getter方法。在响应式表单中，我们通常会通过它所属的控件组（FormGroup）的`get`方法来访问表单控件，但有时候为模板定义一些getter作为简短形式。 - -If you look at the template for the name input again, it is fairly similar to the template-driven example. +If you look at the template for the name input again, it is fairly similar to the template-driven example. 如果我们到模板中找到name输入框，就会发现它和模板驱动的例子很相似。 + Key takeaways: 关键改动是： - + * The form no longer exports any directives, and instead uses the `name` getter defined in the component class. - + 该表单不再导出任何指令，而是使用组件类中定义的`name`读取器。 - + * The `required` attribute is still present. While it's not necessary for validation purposes, you may want to keep it in your template for CSS styling or accessibility reasons. @@ -210,6 +201,7 @@ this guide. Here's what the definition of that function looks like: 考虑前面的[例子](guide/form-validation#reactive-component-class)中的`forbiddenNameValidator`函数。该函数的定义看起来是这样的： + The function is actually a factory that takes a regular expression to detect a _specific_ forbidden name and returns a validator function. @@ -249,6 +241,7 @@ to the `FormControl`. 在响应式表单组件中，添加自定义验证器相当简单。你所要做的一切就是直接把这个函数传给 `FormControl` 。 + ### Adding to template-driven forms @@ -269,8 +262,8 @@ with the `NG_VALIDATORS` provider, a provider with an extensible collection of v Angular在验证流程中的识别出指令的作用，是因为指令把自己注册到了`NG_VALIDATORS`提供商中，该提供商拥有一组可扩展的验证器。 - + The directive class then implements the `Validator` interface, so that it can easily integrate @@ -280,6 +273,7 @@ comes together: 然后该指令类实现了`Validator`接口，以便它能简单的与 Angular 表单集成在一起。这个指令的其余部分有助于你理解它们是如何协作的： + Once the `ForbiddenValidatorDirective` is ready, you can simply add its selector, `appForbiddenName`, to any input element to activate it. For example: @@ -290,7 +284,6 @@ Once the `ForbiddenValidatorDirective` is ready, you can simply add its selector -
    You may have noticed that the custom validation directive is instantiated with `useExisting` @@ -313,11 +306,17 @@ Like in AngularJS, Angular automatically mirrors many control properties onto th 像 AngularJS 中一样，Angular 会自动把很多控件属性作为 CSS 类映射到控件所在的元素上。我们可以使用这些类来根据表单状态给表单控件元素添加样式。目前支持下列类： * `.ng-valid` + * `.ng-invalid` + * `.ng-pending` + * `.ng-pristine` + * `.ng-dirty` + * `.ng-untouched` + * `.ng-touched` The hero form uses the `.ng-valid` and `.ng-invalid` classes to @@ -329,7 +328,7 @@ set the color of each form control's border. - **You can run the to see the complete reactive and template-driven example code.** + **你可以运行来查看完整的响应式和模板驱动表单的代码。** \ No newline at end of file diff --git a/aio/content/guide/forms.md b/aio/content/guide/forms.md index 4e3e36db1f..d9d24c1293 100644 --- a/aio/content/guide/forms.md +++ b/aio/content/guide/forms.md @@ -49,13 +49,13 @@ This page shows you how to build a simple form from scratch. Along the way you'l You can run the in Stackblitz and download the code from there. -你可以在Plunker中运行，并且从那里下载代码。 +运行来试用本页的代码。 {@a template-driven} ## Template-driven forms -## 模板驱动的表单 +## 模板驱动表单 (template-driven forms) You can build forms by writing templates in the Angular [template syntax](guide/template-syntax) with the form-specific directives and techniques described in this page. @@ -1209,7 +1209,7 @@ When you click the *Edit* button, this block disappears and the editable form re ## Summary -## 总结 +## 小结 The Angular form discussed in this page takes advantage of the following framework features to provide support for data modification, validation, and more: diff --git a/aio/content/guide/frequent-ngmodules.md b/aio/content/guide/frequent-ngmodules.md index acd8a633b4..ee00d967d5 100644 --- a/aio/content/guide/frequent-ngmodules.md +++ b/aio/content/guide/frequent-ngmodules.md @@ -4,7 +4,6 @@ A basic understanding of [Bootstrapping](guide/bootstrapping). -
    An Angular app needs at least one module that serves as the root module. @@ -12,57 +11,88 @@ As you add features to your app, you can add them in modules. The following are frequently used Angular modules with examples of some of the things they contain: - + + + + + + + + + + + + + + + + + + + + + + + + + +
    + NgModule + + Import it from + + Why you use it +
    BrowserModule@angular/platform-browserWhen you want to run your app in a browser
    CommonModule@angular/commonWhen you want to use NgIf, NgFor
    FormsModule@angular/formsWhen you build template driven forms (includes NgModel)
    ReactiveFormsModule@angular/formsWhen building reactive forms
    RouterModule@angular/routerFor Routing and when you want to use RouterLink,.forRoot(), and .forChild()
    HttpClientModule@angular/common/httpWhen you to talk to a server
    @@ -75,7 +105,6 @@ or your feature module as appropriate, and list them in the `@NgModule` `BrowserModule` is the first import at the top of the `AppModule`, `app.module.ts`. - ```typescript /* import modules so that AppModule can access them */ import { BrowserModule } from '@angular/platform-browser'; @@ -100,7 +129,6 @@ The imports at the top of the array are JavaScript import statements while the `imports` array within `@NgModule` is Angular specific. For more information on the difference, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). - ## `BrowserModule` and `CommonModule` `BrowserModule` imports `CommonModule`, which contributes many common @@ -119,15 +147,19 @@ If you do import `BrowserModule` into a lazy loaded feature module, Angular returns an error telling you to use `CommonModule` instead.
    + BrowserModule error +
    - ## More on NgModules You may also be interested in the following: + * [Bootstrapping](guide/bootstrapping). + * [NgModules](guide/ngmodules). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). diff --git a/aio/content/guide/glossary.md b/aio/content/guide/glossary.md index ff20024f58..63a56fae7e 100644 --- a/aio/content/guide/glossary.md +++ b/aio/content/guide/glossary.md @@ -22,7 +22,6 @@ unexpected definitions. {@a A} {@a aot} - ## Ahead-of-time (AOT) compilation ## 预 (ahead-of-time, AoT) 编译 @@ -30,14 +29,12 @@ unexpected definitions. You can compile Angular applications at build time. By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly to a module factory, meaning you don't need to include the Angular compiler in your JavaScript bundle. Ahead-of-time compiled applications also benefit from decreased load time and increased performance. - + 开发者可以在构造时 (build-time) 编译 Angular 应用程序。 通过`compiler-cli` - `ngc`编译应用程序，应用可以从一个模块工厂直接启动， 意味着不再需要把 Angular 编译器添加到 JavaScript 包中。 预编译的应用程序加载迅速，具有更高的性能。 - - ## Annotation ## 注解 @@ -46,13 +43,10 @@ In practice, a synonym for [Decoration](guide/glossary#decorator). 实际上，是[装饰 (decoration)](guide/glossary#decorator) 的同义词。 - {@a attribute-directive} - {@a attribute-directives} - ## Attribute directives ## 属性型指令 @@ -71,7 +65,6 @@ Learn about them in the [_Attribute Directives_](guide/attribute-directives) gui 要了解更多信息，请参见[_属性型指令_](guide/attribute-directives)页。 - {@a B} ## Barrel @@ -88,75 +81,65 @@ For example, imagine three ES2015 modules in a `heroes` folder: 例如，设想在`heroes`目录下有三个 ES2015 模块： - + // heroes/hero.component.ts export class HeroComponent {} // heroes/hero.model.ts export class Hero {} - // heroes/hero.service.ts - export class HeroService {} + // heroes/hero.service.ts + export class HeroService {} + - - Without a barrel, a consumer needs three import statements: -如果没有封装桶，消费者需要三条导入语句： - +如果没有封装桶，消费者需要三条导入语句： + import { HeroComponent } from '../heroes/hero.component.ts'; import { Hero } from '../heroes/hero.model.ts'; import { HeroService } from '../heroes/hero.service.ts'; + - - You can add a barrel to the `heroes` folder (called `index`, by convention) that exports all of these items: -在`heroes`目录下添加一个封装桶（按约定叫做`index`），它导出所有这三项： - +在`heroes`目录下添加一个封装桶（按约定叫做`index`），它导出所有这三项： + export * from './hero.model.ts'; // re-export all of its exports export * from './hero.service.ts'; // re-export all of its exports export { HeroComponent } from './hero.component.ts'; // re-export the named thing - - Now a consumer can import what it needs from the barrel. 现在，消费者就就可以从这个封装桶中导入它需要的东西了。 - + import { Hero, HeroService } from '../heroes'; // index is implied + - - The Angular [scoped packages](guide/glossary#scoped-package) each have a barrel named `index`. Angular 的每个[范围化包 (scoped package)](guide/glossary#scoped-package) 都有一个名为`index`的封装桶。 -
    - - You can often achieve the same result using [NgModules](guide/glossary#ngmodule) instead. 注意，你可以利用 [Angular 模块](guide/glossary#ngmodule)达到同样的目的。 -
    - ## Binding ## 绑定 (binding) @@ -173,7 +156,6 @@ between a "token"—also referred to as a "key"—and a dependency [prov 之间的[依赖注入 (dependency injection)](guide/glossary#dependency-injection) 绑定。 这种用法很少，而且一般都会在上下文中写清楚。 - ## Bootstrap ## 启动/引导 (bootstrap) @@ -191,7 +173,6 @@ You can bootstrap multiple apps in the same `index.html`, each app with its own 你可以在同一个`index.html`中引导多个应用，每个应用都有它自己的顶级根组件。 - {@a C} ## camelCase @@ -213,7 +194,6 @@ In Angular documentation, "camelCase" always means *lower camel case*. 这种形式也叫做**小写驼峰式命名法 (lower camel case)**，以区分于**大写驼峰式命名法**，也称 [Pascal 命名法 (PascalCase)](guide/glossary#pascalcase)。 在文档中提到“驼峰式命名法 (camelCase) ”的时候，我们所指的都是小驼峰命名法。 - ## CLI The Angular CLI is a `command line interface` tool that can create a project, add files, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. @@ -222,7 +202,6 @@ Learn more in the [Getting Started](guide/quickstart) guide. {@a component} - ## Component ## 组件 (component) @@ -268,7 +247,6 @@ spelled in dash-case. [指令](guide/glossary#directive)的选择器（例如`my-app`）和文件名（例如`hero-list.component.ts`）通常是用中线命名法来命名。 - ## Data binding ## 数据绑定 (data binding) @@ -293,43 +271,41 @@ operations and supporting declaration syntax. Angular 有一个非常强大的数据绑定框架，具有各种数据绑定操作，并支持声明式语法。 Read about the following forms of binding in the [Template Syntax](guide/template-syntax) page: - + 更多的绑定形式，见[模板语法](guide/template-syntax)： - * [Interpolation](guide/template-syntax#interpolation) + * [Interpolation](guide/template-syntax#interpolation). - [插值表达式 (interpolation)](guide/template-syntax#interpolation) + [插值表达式 (interpolation)](guide/template-syntax#interpolation)。 - * [Property binding](guide/template-syntax#property-binding) + * [Property binding](guide/template-syntax#property-binding). - [property 绑定 (property binding)](guide/template-syntax#property-binding) + [property 绑定 (property binding)](guide/template-syntax#property-binding)。 - * [Event binding](guide/template-syntax#event-binding) + * [Event binding](guide/template-syntax#event-binding). - [事件绑定 (event binding)](guide/template-syntax#event-binding) + [事件绑定 (event binding)](guide/template-syntax#event-binding)。 - * [Attribute binding](guide/template-syntax#attribute-binding) + * [Attribute binding](guide/template-syntax#attribute-binding). - [attribute 绑定 (attribute binding)](guide/template-syntax#attribute-binding) + [attribute 绑定 (attribute binding)](guide/template-syntax#attribute-binding)。 - * [Class binding](guide/template-syntax#class-binding) + * [Class binding](guide/template-syntax#class-binding). - [CSS 类绑定 (class binding)](guide/template-syntax#class-binding) + [CSS 类绑定 (class binding)](guide/template-syntax#class-binding)。 - * [Style binding](guide/template-syntax#style-binding) + * [Style binding](guide/template-syntax#style-binding). - [样式绑定 (style binding)](guide/template-syntax#style-binding) + [样式绑定 (style binding)](guide/template-syntax#style-binding)。 - * [Two-way data binding with ngModel](guide/template-syntax#ngModel) + * [Two-way data binding with ngModel](guide/template-syntax#ngModel). - [基于 ngModel 的双向数据绑定 (Two-way data binding with ngModel)](guide/template-syntax#ngModel) + [基于 ngModel 的双向数据绑定 (Two-way data binding with ngModel)](guide/template-syntax#ngModel)。 {@a decorator} - {@a decoration} - ## Decorator | decoration ## 装饰器（decorator | decoration） @@ -356,7 +332,8 @@ Angular 使用自己的一套装饰器来实现应用程序各部件之间的相 并将`@Input`装饰器来应用到组件的`name`属性。 `@Component`装饰器中省略的参数对象会包含与组件有关的元数据。 -```@Component({...}) +``` +@Component({...}) export class AppComponent { constructor(@Inject('SpecialFoo') public foo:Foo) {} @Input() name:string; @@ -370,19 +347,14 @@ classes that follow it in the file. 装饰器的作用域会被限制在它所装饰的语言特性。 在同一文件中，装饰器不会“泄露”到它后面的其它类。 -
    - - Always include parentheses `()` when applying a decorator. 永远别忘了在装饰器后面加括号`()`。 -
    - ## Dependency injection ## 依赖注入（dependency injection） @@ -414,7 +386,6 @@ for us and handle all the dependencies. If "A" needs "B" and "B" needs "C," the system resolves that chain of dependencies and returns a fully prepared instance of "A." - 可以要求“依赖注入系统”为我们创建 “A” 并处理所有依赖。如果 “A” 需要 “B” ，“B” 需要 “C ”， 系统将解析这个依赖链，返回一个完全准备好的 “A” 实例。 @@ -473,13 +444,10 @@ Read more in the [Dependency Injection](guide/dependency-injection) page. 更多信息，参见[依赖注入 (dependency injection)](guide/dependency-injection)。 - {@a directive} - {@a directives} - ## Directive ## 指令 (directive) @@ -492,12 +460,14 @@ in the browser DOM. The directive is Angular's most fundamental feature. A directive is usually associated with an HTML element or attribute. This element or attribute is often referred to as the directive itself. + +指令几乎总与 HTML 元素或属性 (attribute) 相关。 +我们通常把这些关联到的 HTML 元素或者属性 (attribute) 当做指令本身。 + When Angular finds a directive in an HTML template, it creates the matching directive class instance and gives the instance control over that portion of the browser DOM. -指令几乎总与 HTML 元素或属性 (attribute) 相关。 -我们通常把这些关联到的 HTML 元素或者属性 (attribute) 当做指令本身。 当 Angular 在 HTML 模板中遇到一个指令的时候， 它会创建匹配的指令类的实例，并把浏览器中这部分 DOM 的控制权交给它。 @@ -518,21 +488,21 @@ Directives fall into one of the following categories: render application [views](guide/glossary#view). Components are usually represented as HTML elements. They are the building blocks of an Angular application. - [组件 (component)](guide/glossary#component): 用于组合程序逻辑和 HTML 模板，渲染出应用程序的[视图](guide/glossary#view)。 + [组件 (component)](guide/glossary#component): 用于组合程序逻辑和 HTML 模板，渲染出应用程序的[视图](guide/glossary#view)。 组件一般表示成 HTML 元素的形式，它们是构建 Angular 应用程序的基本单元。 * [Attribute directives](guide/glossary#attribute-directive) can listen to and modify the behavior of other HTML elements, attributes, properties, and components. They are usually represented as HTML attributes, hence the name. - [属性型指令 (attribute directive)](guide/glossary#attribute-directive)：可以监控和修改其它 HTML 元素、 + [属性型指令 (attribute directive)](guide/glossary#attribute-directive)：可以监控和修改其它 HTML 元素、 HTML 属性 (attribute)、 DOM 属性 (property)、组件等行为等等。它们通常表示为 HTML 属性 (attibute)，故名。 * [Structural directives](guide/glossary#structural-directive) are responsible for shaping or reshaping HTML layout, typically by adding, removing, or manipulating elements and their children. - [结构型指令 (structural directive)](guide/glossary#structural-directive)：负责塑造或重塑 HTML + [结构型指令 (structural directive)](guide/glossary#structural-directive)：负责塑造或重塑 HTML 布局。这一般是通过添加、删除或者操作 HTML 元素及其子元素来实现的。 {@a E} @@ -565,14 +535,13 @@ Angular developers can write in ES5 directly. Angular 的开发人员也可以选择直接使用 ES5 编程。 - ## ES2015 ## ES2015 语言 Short hand for [ECMAScript](guide/glossary#ecmascript) 2015. -[ECMAScript](guide/glossary#ecmascript) 2015 的缩写。 +[ECMAScript](guide/glossary#ecmascript) 2015 的简写。 ## ES5 @@ -592,10 +561,8 @@ Short hand for [ECMAScript](guide/glossary#ecmascript) 2015. {@a F} - {@a G} - {@a H} {@a I} @@ -625,8 +592,7 @@ in the template expression to the right of the equal sign. See the [Input and output properties](guide/template-syntax#inputs-outputs) section of the [Template Syntax](guide/template-syntax) page. -见[模板语法](guide/template-syntax)中的[输入与输出属性](guide/template-syntax#inputs-outputs)。 - +参见[模板语法](guide/template-syntax)中的[输入与输出属性](guide/template-syntax#inputs-outputs)部分。 ## Interpolation @@ -641,25 +607,21 @@ or displayed between element tags, as in this example. [属性数据绑定 (property data binding)](guide/glossary#data-binding) 的一种形式，位于双大括号中的[模板表达式 (template expression)](guide/glossary#template-expression)会被渲染成文本。 在被赋值给元素属性或者显示在元素标签中之前，这些文本可能会先与周边的文本合并，参见下面的例子。 - + - - Read more about [interpolation](guide/template-syntax#interpolation) in the [Template Syntax](guide/template-syntax) page. 更多信息，见[模板语法](guide/template-syntax)中的[插值表达式](guide/template-syntax#interpolation)。 - {@a J} {@a jit} - ## Just-in-time (JIT) compilation ## 即时 (just-in-time, JiT) 编译 @@ -671,7 +633,6 @@ Consider using the [ahead-of-time](guide/glossary#aot) mode for production apps. Angular 的即时编译在浏览器中启动并编译所有的组件和模块，动态运行应用程序。 它很适合在开发过程中使用。但是在产品发布时，推荐采用[预编译 (ahead-of-time)](guide/glossary#aot) 模式。 - {@a K} ## kebab-case @@ -682,12 +643,11 @@ See [dash-case](guide/glossary#dash-case). 见[中线命名法 (dash-case)](guide/glossary#dash-case)。 - {@a L} ## Lifecycle hooks -## 生命周期钩子 (lifecycle hook) +## 生命周期钩子 [Directives](guide/glossary#directive) and [components](guide/glossary#component) have a lifecycle managed by Angular as it creates, updates, and destroys them. @@ -710,35 +670,35 @@ Angular 会按以下顺序调用钩子方法： * `ngOnChanges`: when an [input](guide/glossary#input)/[output](guide/glossary#output) binding value changes. - `ngOnChanges` - 在[输入属性 (input)](guide/glossary#input)/[输出属性 (output)](guide/glossary#output)的绑定值发生变化时调用。 - + `ngOnChanges` - 在[输入属性 (input)](guide/glossary#input)/[输出属性 (output)](guide/glossary#output)的绑定值发生变化时调用。 + * `ngOnInit`: after the first `ngOnChanges`. - `ngOnInit` - 在第一次`ngOnChanges`完成后调用。 - + `ngOnInit` - 在第一次`ngOnChanges`完成后调用。 + * `ngDoCheck`: developer's custom change detection. - `ngDoCheck` - 开发者自定义变更检测。 - + `ngDoCheck` - 开发者自定义变更检测。 + * `ngAfterContentInit`: after component content initialized. - `ngAfterContentInit` - 在组件内容初始化后调用。 - + `ngAfterContentInit` - 在组件内容初始化后调用。 + * `ngAfterContentChecked`: after every check of component content. - `ngAfterContentChecked` - 在组件内容每次检查后调用。 - + `ngAfterContentChecked` - 在组件内容每次检查后调用。 + * `ngAfterViewInit`: after a component's views are initialized. - `ngAfterViewInit` - 在组件视图初始化后调用。 - + `ngAfterViewInit` - 在组件视图初始化后调用。 + * `ngAfterViewChecked`: after every check of a component's views. - `ngAfterViewChecked` - 在组件视图每次检查后调用。 - + `ngAfterViewChecked` - 在组件视图每次检查后调用。 + * `ngOnDestroy`: just before the directive is destroyed. - `ngOnDestroy` - 在指令销毁前调用。 + `ngOnDestroy` - 在指令销毁前调用。 Read more in the [Lifecycle Hooks](guide/lifecycle-hooks) page. @@ -752,32 +712,33 @@ Read more in the [Lifecycle Hooks](guide/lifecycle-hooks) page.
    - Angular has the following types of modules: Angular有下列模块类型： * [NgModules](guide/glossary#ngmodule). -For details and examples, see the [NgModules](guide/ngmodules) page. +For details and examples, see the [NgModules](guide/ngmodules) page. + + [Angular 模块](guide/glossary#ngmodule)，见[Angular 模块](guide/ngmodule)。 - [Angular 模块](guide/glossary#ngmodule)，见[Angular 模块](guide/ngmodule)。 - * ES2015 modules, as described in this section. - ES2015模块，如本节所述。 - + ES2015模块，如本节所述。 + +For a comparison, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). + +要对比这两个概念，请参见[JavaScript 模块 vs. NgModules](guide/ngmodule-vs-jsmodule)。 +
    - - -A cohesive block of code dedicated to a single purpose. +A cohesive block of code dedicated to a single purpose. 模块是一个内聚的代码块，具有单一用途。 Angular apps are modular. Angular 应用程序是模块化的。 - + In general, you assemble an application from many modules, both the ones you write and the ones you acquire from others. 一般来说，我们用模块来组装应用程序，这些模块包含自己编写的模块和从其它地方获取的模块。 @@ -787,16 +748,16 @@ a module that needs that class *imports* it. 模块会**导出 (export) **代码中的某些值，最典型的就是类。 模块如果需要什么东西，那就**导入 (import) **它。 - + The structure of NgModules and the import/export syntax is based on the [ES2015 module standard](http://www.2ality.com/2014/09/es6-modules-final.html). - + Angular 的模块结构和导入/导出语法是基于 [ES2015 模块标准](http://www.2ality.com/2014/09/es6-modules-final.html)的。 An application that adheres to this standard requires a module loader to load modules on request and resolve inter-module dependencies. Angular doesn't include a module loader and doesn't have a preference -for any particular third- party library. +for any particular third-party library. You can use any module library that conforms to the standard. 采用这个标准的应用程序需要一个模块加载器来按需加载模块，并解析模块间的依赖关系。 @@ -814,16 +775,10 @@ You rarely access Angular feature modules directly. You usually import them from 你很少需要直接访问 Angular 的特性模块。 而通常会从一个 Angular [范围化包 (scoped package)](guide/glossary#scoped-package)中导入它们，例如`@angular/core`。 - {@a N} - ## NgModule -
    - - - Helps you organize an application into cohesive blocks of functionality. An NgModule identifies the components, directives, and pipes that the application uses along with the list of external NgModules that the application needs, such as `FormsModule`. @@ -833,9 +788,6 @@ called `AppModule` and resides in a file named `app.module.ts`. For details and examples, see [NgModules](guide/ngmodules) and the related files in that section. - - - {@a O} ## Observable @@ -851,12 +803,11 @@ Observables are used within Angular itself, including Angular's event system and Angular 自身使用了`Observable`，包括 Angular 的事件系统和它的 http 客户端服务。 To use observables, Angular uses a third-party library called Reactive Extensions (RxJS). -Observables are a proposed feature for ES 2016, the next version of JavaScript. +Observables are a proposed feature for ES2016, the next version of JavaScript. 为了使用`Observable`， Angular 采用了名为 Reactive Extensions (RxJS) 的第三方包。 在下个版本的 JavaScript - ES 2016 中，`Observable`是建议的特性之一。 - ## Output ## 输出属性 (output) @@ -874,7 +825,6 @@ See the [Input and output properties](guide/template-syntax#inputs-outputs) sect 参见[模板语法](guide/template-syntax)中的[输入与输出属性](guide/template-syntax#inputs-outputs)部分。 - {@a P} ## PascalCase @@ -893,7 +843,6 @@ In this documentation, "PascalCase" means *upper camel case* and "camelCase" me 这种形式也称**大写驼峰式命名法**，以区别于**小写驼峰式命名法”或[驼峰式命名法 (camelCase)](guide/glossary#camelcase)** 。 在本文档中，“Pascal 命名法”都是指的*大写驼峰式命名法*，“驼峰式命名法”指的都是*小写驼峰式命名法*。 - ## Pipe ## 管道 (pipe) @@ -906,21 +855,18 @@ a numeric value in the local currency. Angular 管道是一个函数，用于把输入值转换成输出值以供[视图 (view)](guide/glossary#view)显示。 下面这个例子中，用内置的`currency`管道把数字值显示为本地货币格式。 - + {{product.price | currency}} - - You can also write your own custom pipes. Read more in the page on [pipes](guide/pipes). 我们还可以写自己的自定义管道。 更多信息，见[管道](guide/pipes)。 - ## Provider ## 提供商 (provider) @@ -932,7 +878,6 @@ It relates a lookup token to code—sometimes called a "recipe"—that c 依赖注入系统依靠提供商来创建依赖的实例。 它把一个查找令牌和代码（有时也叫“配方”）关联到一起，以便创建依赖值。 - {@a Q} {@a R} @@ -953,25 +898,24 @@ When building reactive forms: * The "source of truth" is the component. The validation is defined using code in the component. - 组件是“真理之源”。表单验证在组件代码中定义。 + 组件是“真理之源”。表单验证在组件代码中定义。 * Each control is explicitly created in the component class with `new FormControl()` or with `FormBuilder`. - 在组件类中，使用`new FormControl()`或者`FormBuilder`显性地创建每个控件。 + 在组件类中，使用`new FormControl()`或者`FormBuilder`显性地创建每个控件。 * The template input elements do *not* use `ngModel`. - 模板中的`input`元素**不**使用`ngModel`。 - + 模板中的`input`元素**不**使用`ngModel`。 + * The associated Angular directives are all prefixed with `Form`, such as `FormGroup`, `FormControl`, and `FormControlName`. - 相关联的 Angular 指令全部以`Form`开头，例如`FormGroup`、`FormControl`和`FormControlName`。 + 相关联的 Angular 指令全部以`Form`开头，例如`FormGroup`、`FormControl`和`FormControlName`。 Reactive forms are powerful, flexible, and a good choice for more complex data-entry form scenarios, such as dynamic generation of form controls. 动态表单非常强大、灵活，它在复杂数据输入的场景下尤其好用，例如动态的生成表单控制器。 - ## Router ## 路由器 (router) @@ -995,12 +939,12 @@ of a `RouterConfig` that defines routes to views. 多数情况下，组件会通过`RouterConfig`中定义的路由到视图的对照表来附加到[路由器](guide/glossary#router)上。 A [routing component's](guide/glossary#routing-component) template has a `RouterOutlet` element - where it can display views produced by the router. +where it can display views produced by the router. [路由组件](guide/glossary#routing-component)的模板中带有一个`RouterOutlet`元素，那是显示路由器生成的视图的地方。 Other views in the application likely have anchor tags or buttons with `RouterLink` - directives that users can click to navigate. +directives that users can click to navigate. 应用中的其它视图中某些锚标签或按钮上带有`RouterLink`指令，用户可以点击它们进行导航。 @@ -1008,10 +952,9 @@ For more information, see the [Routing & Navigation](guide/router) page. 更多信息，见[路由与导航](guide/router)。 - ## Router module -
    +## 路由器模块 A separate [NgModule](guide/glossary#ngmodule) that provides the necessary service providers and directives for navigating through application views. @@ -1021,7 +964,6 @@ For more information, see the [Routing & Navigation](guide/router) page. 更多信息，见[路由与导航](guide/router)。 - ## Routing component ## 路由组件 (routing component) @@ -1034,7 +976,6 @@ For more information, see the [Routing & Navigation](guide/router) page. 更多信息，见[路由与导航](guide/router)。 - {@a S} ## Scoped package @@ -1057,13 +998,11 @@ is that the scoped package name begins with the Angular *scope name*, `@angular` 导入范围化包与导入*普通*包方式相同。 从消费者的视角看，唯一的不同是那些包的名字是用 Angular 的*范围化包名*`@angular`开头的。 - - ## Service ## 服务 (service) @@ -1096,7 +1035,6 @@ For more information, see the [Services](tutorial/toh-pt4) page of the [Tour of {@a snake-case} - ## snake_case ## 蛇形命名法 @@ -1106,13 +1044,10 @@ underscore (`_`) separates one word from the next. This form is also known as *u 写复合词或短语的一种方式，在多个词之间用下划线(`_`)分隔。也叫*下划线命名法* - {@a structural-directive} - {@a structural-directives} - ## Structural directives ## 结构型指令 @@ -1129,7 +1064,6 @@ Read more in the [Structural Directives](guide/structural-directives) page. 更多信息，见[结构型指令](guide/structural-directives)。 - {@a T} ## Template @@ -1143,7 +1077,6 @@ most notably a [component](guide/glossary#component). 模板是一大块 HTML。Angular 会在[指令 (directive)](guide/glossary#directive) 特别是[组件 (component)](guide/glossary#component) 的支持和持续指导下，用它来渲染[视图 (view)](guide/glossary#view)。 - ## Template-driven forms ## 模板驱动表单 (template-driven forms) @@ -1160,19 +1093,19 @@ When building template-driven forms: * The "source of truth" is the template. The validation is defined using attributes on the individual input elements. - 模板是“真理之源”。使用属性 (attribute) 在单个输入元素上定义验证规则。 - + 模板是“真理之源”。使用属性 (attribute) 在单个输入元素上定义验证规则。 + * [Two-way binding](guide/glossary#data-binding) with `ngModel` keeps the component model synchronized with the user's entry into the input elements. - 使用`ngModel`进行[双向绑定](guide/glossary#data-binding)，保持组件模型和用户输入之间的同步。 - + 使用`ngModel`进行[双向绑定](guide/glossary#data-binding)，保持组件模型和用户输入之间的同步。 + * Behind the scenes, Angular creates a new control for each input element, provided you have set up a `name` attribute and two-way binding for each input. - 在幕后，Angular 为每个带有`name`属性和双向绑定的输入元素创建了一个新的控件。 - + 在幕后，Angular 为每个带有`name`属性和双向绑定的输入元素创建了一个新的控件。 + * The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`. - 相关的 Angular 指令都带有`ng`前缀，例如`ngForm`、`ngModel`和`ngModelGroup`。 + 相关的 Angular 指令都带有`ng`前缀，例如`ngForm`、`ngModel`和`ngModelGroup`。 Template-driven forms are convenient, quick, and simple. They are a good choice for many basic data-entry form scenarios. @@ -1183,7 +1116,6 @@ in the [Forms](guide/forms) page. 要了解如何构建模板驱动表单的更多信息，参见[表单](guide/forms)页。 - ## Template expression ## 模板表达式 (template expression) @@ -1199,7 +1131,6 @@ of the [Template Syntax](guide/template-syntax) page. 到[模板语法](guide/template-syntax)一章的[模板表达式](guide/template-syntax#template-expressions)部分了解更多模板表达式的知识。 - ## Transpile ## 转译（transpile) @@ -1209,7 +1140,6 @@ The process of transforming code written in one form of JavaScript 把一种形式的 JavaScript（例如 TypeScript）转换成另一种形式的 JavaScript（例如 [ES5](guide/glossary#es5)）的过程。 - ## TypeScript ## TypeScript 语言 @@ -1237,7 +1167,6 @@ Read more about TypeScript at [typescriptlang.org](http://www.typescriptlang.org 更多信息，见[typescript.org](http://www.typescriptlang.org/)。 - {@a U} {@a V} @@ -1267,16 +1196,12 @@ under the control of a [router](guide/glossary#router). 视图一般包含其它视图，在用户在应用程序中导航时， 任何视图都可能被动态加载或卸载，这一般会在[路由器 (router)](guide/glossary#router) 的控制下进行。 - {@a W} - {@a X} - {@a Y} - {@a Z} ## Zone @@ -1289,27 +1214,28 @@ a JavaScript application's asynchronous activity. 区域是一种用来封装和截听 JavaScript 应用程序异步活动的机制。 The browser DOM and JavaScript have a limited number - of asynchronous activities, such as DOM events (for example, clicks), - [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and - [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) - calls to remote servers. +of asynchronous activities, such as DOM events (for example, clicks), +[promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and +[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) +calls to remote servers. 浏览器中的 DOM 和 JavaScript 之间常会有一些数量有限的异步活动， 例如 DOM 事件（例如点击）、[承诺 (promise)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) 和通过 [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) 调用远程服务。 - + Zones intercept all of these activities and give a "zone client" the opportunity - to take action before and after the async activity finishes. +to take action before and after the async activity finishes. 区域能截听所有这些活动，并让“区域的客户”有机会在异步活动完成之前和之后采取行动。 Angular runs your application in a zone where it can respond to - asynchronous events by checking for data changes and updating - the information it displays via [data bindings](guide/glossary#data-binding). +asynchronous events by checking for data changes and updating +the information it displays via [data bindings](guide/glossary#data-binding). Angular 会在一个 Zone 区域中运行应用程序，在这个区域中，它可以对异步事件做出反应，可以通过检查数据变更、利用[数据绑定 (data bindings)](guide/glossary#data-binding) 来更新信息显示。 Learn more about zones in this - [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). +[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). -更多信息，见 [Brian Ford 的视频](https://www.youtube.com/watch?v=3IqtmUscE_U)。 + +更多信息，见 [Brian Ford 的视频](https://www.youtube.com/watch?v=3IqtmUscE_U)。 \ No newline at end of file diff --git a/aio/content/guide/hierarchical-dependency-injection.md b/aio/content/guide/hierarchical-dependency-injection.md index 113c038957..5b0884e410 100644 --- a/aio/content/guide/hierarchical-dependency-injection.md +++ b/aio/content/guide/hierarchical-dependency-injection.md @@ -21,9 +21,7 @@ This guide explores this system and how to use it to your advantage. Try the . -试试. - - +试试。 ## The injector tree @@ -43,11 +41,8 @@ The tree of components parallels the tree of injectors. 一个 Angular 应用是一个组件树。每个组件实例都有自己的注入器！ 组件的树与注入器的树平行。 -
    - - The component's injector may be a _proxy_ for an ancestor injector higher in the component tree. That's an implementation detail that improves efficiency. You won't notice the difference and @@ -56,15 +51,12 @@ your mental model should be that every component has its own injector. 组件的注入器可能是一个组件树中更高级的祖先注入器的*代理*。 但这只是提升效率的实现细节，我们不用在乎这点差异，在你的脑海里只要想象成每个组件都有自己的注入器就可以了。 -
    - - -Consider this guide's variation on the Tour of Heroes application . -At the top is the `AppComponent` which has some sub- components. -One of them is the`HeroesListComponent`. -The `HeroesListComponent` holds and manages multiple instances of the `HeroTaxReturnComponent`. +Consider this guide's variation on the Tour of Heroes application. +At the top is the `AppComponent` which has some sub-components. +One of them is the `HeroesListComponent`. +The `HeroesListComponent` holds and manages multiple instances of the `HeroTaxReturnComponent`. The following diagram represents the state of the this guide's three-level component tree when there are three instances of `HeroTaxReturnComponent` open simultaneously. @@ -74,11 +66,11 @@ open simultaneously.
    + injector tree +
    - - ### Injector bubbling ### 注入器冒泡 @@ -95,24 +87,18 @@ If it runs out of ancestors, Angular throws an error. 这个申请继续往上冒泡 —— 直到我们找到了一个能处理此申请的注入器或者超出了组件树中的祖先位置为止。 如果超出了组件树中的祖先还未找到，Angular 就会抛出一个错误。 -
    - - You can cap the bubbling. An intermediate component can declare that it is the "host" component. The hunt for providers will climb no higher than the injector for that host component. - This is a topic for another day. - +This is a topic for another day. + 我们还可以“盖住”这次冒泡。一个中层的组件可以声称自己是“宿主”组件。 向上查找提供商的过程会截止于这个“宿主”组件。 我们先保留这个问题，等改天再讨论这个选项。 -
    - - ### Re-providing a service at different levels ### 在不同层级再次提供同一个服务 @@ -138,8 +124,6 @@ All requests bubble up to the root NgModule injector that you confi 如果我们只在顶级（通常是根模块`AppModule`），这三个注入器看起来将是“平面”的。 所有的申请都会冒泡到根NgModule进行处理，也就是我们在`bootstrapModule`方法中配置的那个。 - - ## Component injectors ## 组件注入器 @@ -176,13 +160,10 @@ Instead, provide the `VillainsService` in the `providers` metadata of the `Villa 我们可以换一种方案：在`VillainsListComponent`元数据的`providers`中提供`VillainsService`，就像这样： - - - By providing `VillainsService` in the `VillainsListComponent` metadata and nowhere else, the service becomes available only in the `VillainsListComponent` and its sub-component tree. It's still a singleton, but it's a singleton that exist solely in the _villain_ domain. @@ -223,23 +204,22 @@ Each tax return component has the following characteristics: * Is its own tax return editing session. - 属于它自己的报税单会话。 - + 属于它自己的报税单会话。 + * Can change a tax return without affecting a return in another component. - 可以修改一个报税单，而不会影响另一个组件中的申报单。 - + 可以修改一个报税单，而不会影响另一个组件中的申报单。 + * Has the ability to save the changes to its tax return or cancel them. - 能把所做的修改保存到它的报税单中，或者放弃它们。 - + 能把所做的修改保存到它的报税单中，或者放弃它们。
    + Heroes in action +
    - - One might suppose that the `HeroTaxReturnComponent` has logic to manage and restore changes. That would be a pretty easy task for a simple hero tax return. In the real world, with a rich tax return data model, the change management would be tricky. @@ -258,24 +238,18 @@ It also delegates to the application-wide singleton `HeroService`, which it gets 它缓存了单条`HeroTaxReturn`，用于跟踪那个申报单的变更，并且可以保存或还原它。 它还委托给了全应用级的单例服务`HeroService`，它是通过依赖注入机制取得的。 - - - Here is the `HeroTaxReturnComponent` that makes use of it. 下面是正在使用它的`HeroTaxReturnComponent`组件。 - - - The _tax-return-to-edit_ arrives via the input property which is implemented with getters and setters. The setter initializes the component's own instance of the `HeroTaxReturnService` with the incoming return. The getter always returns what that service says is the current state of the hero. @@ -297,13 +271,10 @@ Look closely at the metadata for the `HeroTaxReturnComponent`. Notice the `provi 但仔细看`HeroTaxReturnComponent`的元数据，注意`providers`属性。 - - - The `HeroTaxReturnComponent` has its own provider of the `HeroTaxReturnService`. Recall that every component _instance_ has its own injector. Providing the service at the component level ensures that _every_ instance of the component gets its own, private instance of the service. @@ -314,22 +285,16 @@ No tax return overwriting. No mess. 在组件级提供服务可以确保组件的*每个*实例都得到一个自己的、私有的服务实例。 报税单不会再被意外覆盖，这下清楚了。 -
    - - The rest of the scenario code relies on other Angular features and techniques that you can learn about elsewhere in the documentation. You can review it and download it from the . 该场景代码中的其它部分依赖另一些Angular的特性和技术，我们将会在本文档的其它章节学到。 你可以到查看代码和下载它。 -
    - - ### Scenario: specialized providers ### 场景：专门的提供商 @@ -359,13 +324,12 @@ Component (B) is the parent of another component (C) that defines its own, even 组件B是另一个组件C的父组件，而组件C又定义了自己的，*更特殊的*`CarService`提供商。 -
    + car components +
    - - Behind the scenes, each component sets up its own injector with zero, one, or more providers defined for that component itself. 在幕后，每个组件都有自己的注入器，这个注入器带有为组件本身准备的0个、1个或多个提供商。 @@ -376,22 +340,18 @@ its injector produces an instance of `Car` resolved by injector (C) with an `Eng 当我们在最深层的组件C解析`Car`的实例时，它使用注入器C解析生成了一个`Car`的实例，使用注入器B解析了`Engine`，而`Tires`则是由根注入器A解析的。 -
    + car injector tree +
    - -
    - - The code for this _cars_ scenario is in the `car.components.ts` and `car.services.ts` files of the sample which you can review and download from the . *车辆*场景下的代码位于`car.components.ts`和`car.services.ts`文件中，这个例子你可以在查看和下载。 -
    diff --git a/aio/content/guide/http.md b/aio/content/guide/http.md index 3dd1eeda0b..13efcff27a 100644 --- a/aio/content/guide/http.md +++ b/aio/content/guide/http.md @@ -200,6 +200,7 @@ It's certainly a good idea to give the user some kind of feedback when data acce But displaying the raw error object returned by `HttpClient` is far from the best way to do it. {@a error-details} + ### Getting error details ### 获取错误详情 @@ -264,6 +265,7 @@ _Pipe_ it onto the `HttpClient` method result just before the error handler. {@a rxjs} + ## Observables and operators The previous sections of this guide referred to RxJS `Observables` and operators such as `catchError` and `retry`. @@ -422,6 +424,7 @@ Merely calling `HeroService.deleteHero()` **does not initiate the DELETE request {@a always-subscribe} + ### Always _subscribe_! An `HttpClient` method does not begin its HTTP request until you call `subscribe()` on the observable returned by that method. This is true for _all_ `HttpClient` _methods_. @@ -905,6 +908,7 @@ Data services, such as `PackageSearchService`, are unaware that some of their `HttpClient` requests actually return cached responses. {@a cache-refresh} + #### Return a multi-valued _Observable_ The `HttpClient.get()` method normally returns an _observable_ diff --git a/aio/content/guide/i18n.md b/aio/content/guide/i18n.md index b6b5d54e4b..328b837b7b 100644 --- a/aio/content/guide/i18n.md +++ b/aio/content/guide/i18n.md @@ -9,20 +9,25 @@ an AOT-compiled app, translated into French. 可以把这个翻译为法语版的 AOT 应用i18n 例子作为一个简单的例子。 - {@a angular-i18n} + ## Angular and i18n Angular simplifies the following aspects of internationalization: + * Displaying dates, number, percentages, and currencies in a local format. + * Translating text in component templates. + * Handling plural forms of words. + * Handling alternative text. This document focuses on [**Angular CLI**](https://cli.angular.io/) projects, in which the Angular CLI generates most of the boilerplate necessary to write your app in multiple languages. {@a setting-up-locale} + ## Setting up the locale of your app A locale is an identifier (id) that refers to a set of user preferences that tend to be shared @@ -52,14 +57,16 @@ To set your app's locale to another value, use the CLI parameter `--locale` with of the locale id that you want to use: + ng serve --aot --locale fr + If you use JIT, you also need to define the `LOCALE_ID` provider in your main module: - + For more information about Unicode locale identifiers, see the [CLDR core spec](http://cldr.unicode.org/core-spec#Unicode_Language_and_Locale_Identifiers). @@ -84,7 +91,6 @@ time of writing: | Chinese Traditional | zh-tw, zh-Hant-TW | zh-Hant | | Chinese Traditional Hong Kong | zh-hk | zh-Hant-HK | - ## i18n pipes Angular pipes can help you with internationalization: the `DatePipe`, `CurrencyPipe`, `DecimalPipe` @@ -98,6 +104,7 @@ The CLI imports the locale data for you when you use the parameter `--locale` wi If you want to import locale data for other languages, you can do it manually: + The first parameter is an object containing the locale data imported from `@angular/common/locales`. @@ -111,8 +118,9 @@ locale id "fr-FR" instead of "fr". The files in `@angular/common/locales` contain most of the locale data that you need, but some advanced formatting options might only be available in the extra dataset that you can import from `@angular/common/locales/extra`. An error message informs you when this is the case. - + +
    @@ -122,13 +130,12 @@ import from `@angular/common/locales/extra`. An error message informs you when t
    - ## Template translations
    This document refers to a unit of translatable text as "text," a "message", or a - "text message." + "text message."
    @@ -148,6 +155,7 @@ in the target language. You need to build and deploy a separate version of the app for each supported language. {@a i18n-attribute} + ### Mark text with the i18n attribute The Angular `i18n` attribute marks translatable content. Place it on every element tag whose fixed @@ -156,16 +164,16 @@ text is to be translated. In the example below, an `

    ` tag displays a simple English language greeting, "Hello i18n!" + To mark the greeting for translation, add the `i18n` attribute to the `

    ` tag. - 添加`i18n`属性到该标签上，把它标记为需要翻译的文本。 - +
    @@ -174,8 +182,8 @@ To mark the greeting for translation, add the `i18n` attribute to the `

    ` tag

    - {@a help-translator} + ### Help the translator with a description and meaning To translate a text message accurately, the translator may need additional information or context. @@ -184,6 +192,7 @@ You can add a description of the text message as the value of the `i18n` attribu example below: + The translator may also need to know the meaning or intent of the text message within this particular @@ -197,6 +206,7 @@ separating it from the _description_ with the `|` character: `||<描述>`)。 + All occurrences of a text message that have the same meaning will have the same translation. @@ -212,8 +222,8 @@ text messages with different descriptions (not different meanings), then they ar 但是如果在某些地方它具有**不同含义**，那么它应该有不同的翻译。 Angular的提取工具在翻译源文件中保留**含义**和**描述**，以支持符合特定上下文的翻译。 - {@a custom-id} + ### Set a custom id for persistence and maintenance ### 设置一个自定义的`id`来提升可搜索性和可维护性 @@ -224,6 +234,7 @@ attribute in a template. By default, it assigns each translation unit a unique i Angular 的 `i18n` 提取工具会为模板中每个带有`i18n`属性的元素生成一个*翻译单元（translation unit）*条目，并保存到一个文件中。默认情况下，它为每个翻译单元指定一个唯一的`id`，就像这样： + When you change the translatable text, the extractor tool generates a new id for that translation unit. @@ -233,9 +244,10 @@ You must then update the translation file with the new id. 我们就要使用这个新的 id 来修改这个翻译文件。 Alternatively, you can specify a custom id in the `i18n` attribute by using the prefix `@@`. -The example below defines the custom id `introductionHeader`: +The example below defines the custom id `introductionHeader`: + When you specify a custom id, the extractor tool and compiler generate a translation unit with that @@ -244,6 +256,7 @@ custom id. 现在，提取工具和编译器就会用*你的自定义id`生成一个翻译单元，而不会再改变它。 + The custom id is persistent. The extractor tool does not change it when the translatable text changes. @@ -256,6 +269,7 @@ You can use a custom id in combination with a description by including both in t by the custom `id`: + You also can add a meaning, as shown in this example: @@ -263,44 +277,57 @@ You also can add a meaning, as shown in this example: 下面这个例子带有*含义*和*描述*，最后是`id`： + #### Define unique custom ids Be sure to define custom ids that are unique. If you use the same id for two different text messages, only the first one is extracted, and its translation is used in place of both original text messages. - + 为了确保定义出*唯一*的自定义id。如果我们对两个*不同的*文本块使用了同一个id，那么就只有一个会被提取出来，然后其翻译结果会被用于全部文本块。 In the example below the custom id `myId` is used for two different messages: - + ```html +

    Hello

    + +

    Good bye

    + ``` Consider this translation to French: - + ```xml + + Hello + Bonjour + + ``` Because the custom id is the same, both of the elements in the resulting translation contain the same text, `Bonjour`: ```html -

    Bonjour

    - -

    Bonjour

    - ``` - +

    Bonjour

    + + + +

    Bonjour

    + + ``` {@a no-element} + ### Translate text without creating an element ### 翻译文本，而不必创建元素 @@ -314,9 +341,11 @@ The `` is transformed into an html comment: 但如果由于某些原因（比如CSS结构方面的考虑），我们可能不希望仅仅为了翻译而创建一个新的DOM元素，那么也可以把这段文本包裹进一个``元素中。``将被转换成一个HTML注释： + {@a translate-attributes} + ## Add i18n translation attributes ## 添加 *i18n* 翻译属性 @@ -328,6 +357,7 @@ For example, assume that your template has an image with a `title` attribute: 比如，假设我们的模板具有一个带`title`属性的图片： + This `title` attribute needs to be translated. @@ -339,6 +369,7 @@ where `x` is the name of the attribute to translate. The following example shows `title` attribute for translation by adding the `i18n-title` attribute on the `img` tag: + This technique works for any attribute of any element. @@ -349,6 +380,7 @@ syntax. 我们也同样可以使用`i18n-x="|@@"`语法来指定一个含义和描述。 {@a plural-ICU} + ## Translate singular and plural ## 处理单数与复数 @@ -370,19 +402,21 @@ The example below shows how to use a `plural` ICU expression to display one of t based on when the update occurred: + -* The first parameter is the key. It is bound to the component property (`minutes`), which determines the number of minutes. +* The first parameter is the key. It is bound to the component property (`minutes`), which determines +the number of minutes. + + 第一个参数是key。它绑定到了组件中表示狼的数量的`wolves`属性。 - 第一个参数是key。它绑定到了组件中表示狼的数量的`wolves`属性。 - * The second parameter identifies this as a `plural` translation type. - 第二个参数表示这是一个`plural`（复数）翻译类型。 + 第二个参数表示这是一个`plural`（复数）翻译类型。 * The third parameter defines a pluralization pattern consisting of pluralization categories and their matching values. - - 第三个参数定义了一组复数表示模式，这个模式由复数类别和它们所匹配的值组成。 + + 第三个参数定义了一组复数表示模式，这个模式由复数类别和它们所匹配的值组成。
    @@ -399,27 +433,27 @@ Pluralization categories include (depending on the language): * =0 (or any other number) - =0 （或其它数字） - + =0 （或其它数字） + * zero - zero（零） + zero（零） * one - one（一个) + one（一个) * two - two（两个） + two（两个） * few - few（少数） + few（少数） * many - many（很多） + many（很多） * other @@ -440,6 +474,7 @@ for two, three, or any other number if the pluralization rules were different. F
    {@a select-ICU} + ## Select among alternative text messages ## 在候选文本中选择 @@ -459,9 +494,11 @@ The message maps those values to the appropriate translations: 这个消息会把那些值映射到适当的翻译文本： + {@a nesting-ICUS} + ## Nesting plural and select ICU expressions ## 把"复数"与"选择"表达式嵌套在一起 @@ -471,16 +508,18 @@ You can also nest different ICU expressions together, as shown in this example: 我们也可以把不同的 ICU 表达式嵌套在一起，比如： + {@a ng-xi18n} + ## Create a translation source file with _ng xi18n_ ## 使用_ng-xi18n_工具创建翻译源文件 -Use the `ng xi18n` command provided by the CLI to extract the text messages marked with`i18n`into - a translation source file . - +Use the `ng xi18n` command provided by the CLI to extract the text messages marked with `i18n` into +a translation source file. + 使用`ng-xi18n`提取工具来将带`i18n`标记的文本提取到一个翻译源文件中。 @@ -488,9 +527,10 @@ Open a terminal window at the root of the app project and enter the `ng xi18n` c 在应用的项目根目录打开一个终端窗口，并输入`ng-xi18n`命令： - + ng xi18n + By default, the tool generates a translation file named `messages.xlf` in the @@ -500,8 +540,10 @@ By default, the tool generates a translation file named `messages.xlf` in the
    If you don't use the CLI, you have two options: + * You can use the `ng-xi18n` tool directly from the `@angular/compiler-cli` package. For more information, see [i18n in the CLI documentation](https://github.com/angular/angular-cli/wiki/xi18n). + * You can use the CLI Webpack plugin `AngularCompilerPlugin` from the `@ngtools/webpack` package. Set the parameters `i18nOutFile` and `i18nOutFormat` to trigger the extraction. For more information, see the [Angular Ahead-of-Time Webpack Plugin documentation](https://github.com/angular/angular-cli/tree/master/packages/%40ngtools/webpack). @@ -509,13 +551,17 @@ For more information, see the [Angular Ahead-of-Time Webpack Plugin documentatio
    {@a other-formats} + ### Other translation formats ### 其它翻译格式 Angular i18n tooling supports three translation formats: + * XLIFF 1.2 (default) + * XLIFF 2 + * XML Message Bundle (XMB) @@ -525,9 +571,11 @@ these example commands: 我们可以使用`--i18nFormat`来明确指定想用的格式，范例如下： + ng xi18n --i18nFormat=xlf ng xi18n --i18nFormat=xlf2 ng xi18n --i18nFormat=xmb + The sample in this guide uses the default XLIFF 1.2 format. @@ -540,6 +588,7 @@ The sample in this guide uses the default XLIFF 1.2 format.

    {@a ng-xi18n-options} + ### Other options ### 其它选项 @@ -576,24 +625,25 @@ You can specify the base locale of your app with the parameter `--locale`: The extraction tool uses the locale to add the app locale information into your translation source file. This information is not used by Angular, but external translation tools may need it. - {@a translate} + ## Translate text messages ## 翻译文本信息 -The `ng xi18n` command generates a translation source file -named `messages.xlf`in the project `src` folder . +The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src` +folder. `ng xi18n`命令在项目根目录生成一个名为`messages.xlf`的翻译源文件。 -The next step is to translate this source file into the specific language -translation files. The example in this guide creates a French translation file. +The next step is to translate this source file into the specific language +translation files. The example in this guide creates a French translation file. 下一步是将英文模板文本翻译到指定语言的翻译文件。 这个例子中创建了一个法语翻译文件。 {@a localization-folder} + ### Create a localization folder ### 新建一个本土化目录 @@ -603,7 +653,7 @@ for the project structure to reflect the entire internationalization effort. 大多数应用都要被翻译成多种其它语言，因此，为全部国际化工作做适当的调整项目目录结构是一种标准实践。 -One approach is to dedicate a folder to localization and store related assets , such as +One approach is to dedicate a folder to localization and store related assets, such as internationalization files, there. 其中一种方法是为本土化和相关资源（比如国际化文件）创建一个专门的目录。 @@ -615,7 +665,7 @@ internationalization files, there. different but closely related terms. -本土化和国际化是不同但是很相近的概念。 + 本土化和国际化是不同但是很相近的概念。
    @@ -630,20 +680,23 @@ resulting translation. For this example: 1. Make a copy of the `messages.xlf` file. + 2. Put the copy in the `locale` folder. + 3. Rename the copy to `messages.fr.xlf` for the French language translation. If you were translating to other languages, you would repeat these steps for each target language. {@a translate-text-nodes} + ### Translate text nodes ### 翻译文本节点 -In a large translation project, you wouldsend the `messages.fr.xlf` file to a French translator who would enter the translations -using an XLIFF file editor. +In a large translation project, you would send the `messages.fr.xlf` file to a French translator who +would enter the translations using an XLIFF file editor. -在现实世界中，`messages.es.xlf`文件会被发给西班牙语翻译，他们使用这些XLIFF文件编辑器中的一种来翻译它。 +在现实世界中，`messages.fr.xlf`文件会被发给法语翻译，他们使用这些XLIFF文件编辑器中的一种来翻译它。 This sample file is easy to translate without a special editor or knowledge of French. @@ -661,7 +714,6 @@ This sample file is easy to translate without a special editor or knowledge of F [custom `id`](#custom-id "Set a custom id") that you set earlier, but without the `@@` prefix required in the source HTML. - 2. Duplicate the `` tag, rename it `target`, and then replace its content with the French greeting. If you were working with a more complex translation, you could use the the information and context provided by the source, description, and meaning elements to guide your selection of @@ -685,6 +737,7 @@ This sample file is easy to translate without a special editor or knowledge of F
    {@a translate-plural-select} + ## Translate plural and select expressions _Plural_ and _select_ ICU expressions are extracted separately, so they require special attention @@ -695,6 +748,7 @@ elsewhere in the source template. In this example, you know the translation unit must be just below the translation unit for the logo. {@a translate-plural} + ### Translate _plural_ To translate a `plural`, translate its ICU format match values: @@ -702,12 +756,14 @@ To translate a `plural`, translate its ICU format match values: 要翻译一个复数，就要翻译它的ICU格式中匹配的值： + You can add or remove plural cases, with each language having its own cardinality. (See [CLDR plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html).) {@a translate-select} + ### Translate _select_ ### 翻译*选择*（select） @@ -715,6 +771,7 @@ You can add or remove plural cases, with each language having its own cardinalit Below is the content of our example `select` ICU expression in the component template: + The extraction tool broke that into two translation units because ICU expressions are extracted @@ -732,6 +789,7 @@ the placeholder, the ICU expression will not be present in your translated app. 翻译这段文本，并把占位符放在那里。 + The second translation unit, immediately below the first one, contains the `select` message. @@ -740,6 +798,7 @@ Translate that as well. 第一个翻译单元的紧下方就是第二个翻译单元，包含`select`中的消息。翻译它。 + Here they are together, after translation: @@ -747,9 +806,11 @@ Here they are together, after translation: 在翻译之后，它们会放在一起： + {@a translate-nested} + ### Translate a nested expression ### 翻译嵌套的表达式 @@ -760,6 +821,7 @@ two translation units. The first one contains the text outside of the nested exp 嵌套的表达式和前一节没有什么不同。就像上一个例子中那样，我们有*两个*翻译单元。 + The second unit contains the complete nested expression: @@ -767,6 +829,7 @@ The second unit contains the complete nested expression: 第二个包含完整的嵌套表达式： + And both together: @@ -774,12 +837,14 @@ And both together: 放在一起时： + The entire template translation is complete. The next section describes how to load that translation into the app. {@a app-pre-translation} + ### The app and its translation file ### 应用及其翻译文件 @@ -788,21 +853,32 @@ The sample app and its translation file are now as follows: 下面是例子应用及其翻译文件： - + + + + + + + + + + + {@a merge} + ## Merge the completed translation file into the app ## 合并已经翻译的文件 @@ -811,12 +887,12 @@ To merge the translated text into component templates, compile the app with the translation file. Provide the Angular compiler with three translation-specific pieces of information: * The translation file. - - 翻译文件 - + + 翻译文件 + * The translation file format. - - 翻译文件的格式 + + 翻译文件的格式 * The locale (`fr` or `en-US` for instance). @@ -827,10 +903,11 @@ How you provide this information depends upon whether you compile with the JIT compiler or the AOT compiler. * With [AOT](guide/i18n#merge-aot), you pass the information as a CLI parameter. + * With [JIT](guide/i18n#merge-jit), you provide the information at bootstrap time. - {@a merge-aot} + ### Merge with the AOT compiler The AOT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, @@ -841,21 +918,25 @@ package for each language and serve the appropriate package based on either serv detection or url parameters. You also need to instruct the AOT compiler to use your translation file. To do so, you use three -options withthe `ng serve` or `ng build` commands: - +options with the `ng serve` or `ng build` commands: * `--i18nFile`: the path to the translation file. + * `--i18nFormat`: the format of the translation file. + * `--locale`: the locale id. The example below shows how to serve the French language file created in previous sections of this guide: + ng serve --aot --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr + {@a merge-jit} + ### Merge with the JIT compiler ### 用JiT编译器合并 @@ -868,15 +949,15 @@ JiT（即时）编译器在应用程序加载时，在浏览器中编译应用 1. Importing the appropriate language translation file as a string constant. - 把合适的语言翻译文件导入成一个字符串常量 - + 把合适的语言翻译文件导入成一个字符串常量 + 2. Creating corresponding translation providers for the JIT compiler. - 为JiT编译器创建相应的翻译提供商。 - + 为JiT编译器创建相应的翻译提供商。 + 3. Bootstrapping the app with those providers. - 使用这些提供商来启动应用。 + 使用这些提供商来启动应用。 Three providers tell the JIT compiler how to translate the template texts for a particular language while compiling the app: @@ -885,47 +966,53 @@ while compiling the app: * `TRANSLATIONS` is a string containing the content of the translation file. - `TRANSLATIONS`是含有翻译文件内容的字符串。 + `TRANSLATIONS`是含有翻译文件内容的字符串。 * `TRANSLATIONS_FORMAT` is the format of the file: `xlf`, `xlf2`, or `xtb`. - `TRANSLATIONS_FORMAT`是文件的格式: `xlf`、`xlif`或`xtb`。 - + `TRANSLATIONS_FORMAT`是文件的格式: `xlf`、`xlif`或`xtb`。 + * `LOCALE_ID` is the locale of the target language. - `LOCALE_ID`是目标语言的语言环境。 + `LOCALE_ID`是目标语言的语言环境。 The Angular `bootstrapModule` method has a second `compilerOptions` parameter that can influence the behavior of the compiler. You can use it to provide the translation providers: 在下面的`src/app/i18n-providers.ts`文件的`getTranslationProviders()`函数中，根据用户的**语言环境**和对应的翻译文件构建这些提供商： - + Then provide the `LOCALE_ID` in the main module: + - {@a missing-translation} + ### Report missing translations + By default, when a translation is missing, the build succeeds but generates a warning such as `Missing translation for message "foo"`. You can configure the level of warning that is generated by the Angular compiler: * Error: throw an error. If you are using AOT compilation, the build will fail. If you are using JIT compilation, the app will fail to load. + * Warning (default): show a 'Missing translation' warning in the console or shell. + * Ignore: do nothing. If you use the AOT compiler, specify the warning level by using the CLI parameter `--missingTranslation`. The example below shows how to set the warning level to error: + ng serve --aot --missingTranslation=error + If you use the JIT compiler, specify the warning level in the compiler config at bootstrap by adding @@ -933,4 +1020,6 @@ the 'MissingTranslationStrategy' property. The example below shows how to set th error: + + diff --git a/aio/content/guide/language-service.md b/aio/content/guide/language-service.md index f4865b25a6..5edf145920 100644 --- a/aio/content/guide/language-service.md +++ b/aio/content/guide/language-service.md @@ -25,7 +25,9 @@ you can hit tab to complete. 自动完成可以在输入时为我们提供当前情境下的候选内容和提示，从而提高开发速度。下面这个例子展示了插值表达式中的自动完成功能。当我们进行输入的时候，就可以按tab键来自动完成。
    + autocompletion +
    There are also completions within @@ -39,12 +41,14 @@ show up in the completion list. ## 错误检查 The Angular Language Service can also forewarn you of mistakes in your code. -In this example, Angular doesn't know what `orders` is or where it comes from. +In this example, Angular doesn't know what `orders` is or where it comes from. Angular 语言服务还能对代码中存在的错误进行预警。在这个例子中，Angular 不知道什么是`orders`或者它来自哪里。
    + error checking +
    ## Navigation @@ -58,9 +62,10 @@ click and press F12 to go directly to its definition. 导航可以让我们在鼠标悬浮时看到某个组件、指令、模块等来自哪里，然后可以点击并按 F12 直接跳转到它的定义处。
    - navigation -
    + navigation + + ## Angular Language Service in your editor @@ -126,7 +131,7 @@ npm install *OR* -*或* +*或* ```sh yarn @@ -140,7 +145,6 @@ yarn yarn install ``` - ### Sublime Text ### Sublime Text 编辑器 @@ -175,7 +179,6 @@ Next, in your user preferences (`Cmd+,` or `Ctrl+,`), add: "typescript-tsdk": "/node_modules/typescript/lib" ``` - ## Installing in your project ## 安装到工程中 @@ -222,20 +225,14 @@ context, it can then determine what the children can be. It's a little more involved if you are in an interpolation. If you have an interpolation of `{{data.---}}` inside a `div` and need the completion list after `data.---`, the compiler can't use the HTML AST to find the answer. The HTML AST can only tell the compiler that there is some text with the characters "`{{data.---}}`". That's when the template parser produces an expression AST, which resides within the template AST. The Angular Language Services then looks at `data.---` within its context and asks the TypeScript Language Service what the members of data are. TypeScript then returns the list of possibilities. - 如果是在插值表达式中，还会牵扯到更多东西。如果我们在`div`元素中有一个插值表达式`{{data.---}}`，并且需要在输入了`data.`之后提供自动完成列表，编译器就没办法使用 HTML AST 来找出答案了。 HTML AST只能告诉编译器，有一些具有 "`{{data.---}}`" 特征的文本。也就是说模板解析器会生成表达式的 AST ，并且放在模板的 AST 中。Angular 语言服务然后在这个情境下查找`data.---`，并向 TypeScript 语言服务询问这些数据都有哪些成员。然后 TypeScript 就会返回一个可能的列表。 For more in-depth information, see the [Angular Language Service API](https://github.com/angular/angular/blob/master/packages/language-service/src/types.ts) - 要了解更多更深入的信息，参见 [Angular 语言服务 API](https://github.com/angular/angular/blob/master/packages/language-service/src/types.ts) - - - -
    ## More on Information @@ -246,3 +243,4 @@ For more information, see [Chuck Jazdzewski's presentation](https://www.youtube. Service from [ng-conf](https://www.ng-conf.org/) 2017. 要了解更多信息，参见 [ng-conf](https://www.ng-conf.org/) 2017 中 [Chuck Jazdzewski的演讲](https://www.youtube.com/watch?v=ez3R0Gi4z5A&t=368s) 中讲解的 Angular 语言服务。 + diff --git a/aio/content/guide/lazy-loading-ngmodules.md b/aio/content/guide/lazy-loading-ngmodules.md index 48265a9a2c..227d644dcf 100644 --- a/aio/content/guide/lazy-loading-ngmodules.md +++ b/aio/content/guide/lazy-loading-ngmodules.md @@ -1,11 +1,17 @@ # Lazy Loading Feature Modules #### Prerequisites + A basic understanding of the following: + * [Feature Modules](guide/feature-modules). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). + * [Frequently Used Modules](guide/frequent-ngmodules). + * [Types of Feature Modules](guide/module-types). + * [Routing and Navigation](guide/router). For the final sample app with two lazy loaded modules that this page describes, see the @@ -18,7 +24,9 @@ For the final sample app with two lazy loaded modules that this page describes, There are three main steps to setting up a lazy loaded feature module: 1. Create the feature module. + 1. Create the feature module’s routing module. + 1. Configure the routes. ## Set up an app @@ -73,7 +81,6 @@ about components, see [Components](). --> Just like with the routing module, the CLI imports the `CustomerListComponent` into the `CustomersModule`. - ## Add another feature module For another place to route to, create a second feature module with routing: @@ -97,13 +104,10 @@ is easier for the user and more common. Replace the default placeholder markup in `app.component.html` with a custom nav so you can easily navigate to your modules in the browser: - - - To see your app in the browser so far, enter the following command in the terminal window: ```sh @@ -113,9 +117,10 @@ ng serve Then go to `localhost:4200` where you should see “app works!” and three buttons.
    - three buttons in the browser -
    + three buttons in the browser + + To make the buttons work, you need to configure the routing modules. @@ -127,9 +132,10 @@ The two feature modules, `OrdersModule` and `CustomersModule`, have to be wired up to the `AppRoutingModule` so the router knows about them. The structure is as follows:
    - lazy loaded modules diagram -
    + lazy loaded modules diagram + + Each feature module acts as a doorway via the router. In the `AppRoutingModule`, you configure the routes to the feature modules, in this case `OrdersModule` and `CustomersModule`. This way, the router knows to go to the feature module. The feature module then connects the `AppRoutingModule` to the `CustomersRoutingModule` or the `OrdersRoutingModule`. Those routing modules tell the router where to go to load relevant components. @@ -137,28 +143,22 @@ Each feature module acts as a doorway via the router. In the `AppRoutingModule`, In `AppRoutingModule`, update the `routes` array with the following: - - The import statements stay the same. The first two paths are the routes to the `CustomersModule` and the `OrdersModule` respectively. Notice that the lazy loading syntax uses `loadChildren` followed by a string that is the path to the module, a hash mark or `#`, and the module’s class name. ### Inside the feature module Next, take a look at `customers.module.ts`. If you’re using the CLI and following the steps outlined in this page, you don’t have to do anything here. The feature module is like a connector between the `AppRoutingModule` and the feature routing module. The `AppRoutingModule` imports the feature module, `CustomersModule`, and `CustomersModule` in turn imports the `CustomersRoutingModule`. - - - The `customers.module.ts` file imports the `CustomersRoutingModule` and `CustomerListComponent` so the `CustomersModule` class can have access to them. `CustomersRoutingModule` is then listed in the `@NgModule` `imports` array giving `CustomersModule` access to its own routing module, and `CustomerListComponent` is in the `declarations` array, which means `CustomerListComponent` belongs to the `CustomersModule`. - ### Configure the feature module’s routes The next step is in `customers-routing.module.ts`. First, import the component at the top of the file with the other JavaScript import statements. Then, add the route to `CustomerListComponent`. @@ -167,7 +167,6 @@ The next step is in `customers-routing.module.ts`. First, import the component a - Notice that the `path` is set to an empty string. This is because the path in `AppRoutingModule` is already set to `customers`, so this route in the `CustomersRoutingModule`, is already within the `customers` context. Every route in this routing module is a child route. Repeat this last step of importing the `OrdersListComponent` and configuring the Routes array for the `orders-routing.module.ts`: @@ -183,24 +182,26 @@ Now, if you view the app in the browser, the three buttons take you to each modu You can check to see that a module is indeed being lazy loaded with the Chrome developer tools. In Chrome, open the dev tools by pressing `Cmd+Option+i` on a Mac or `Ctrl+Alt+i` on a PC and go to the Network Tab.
    - lazy loaded modules diagram -
    + lazy loaded modules diagram + + Click on the Orders or Customers button. If you see a chunk appear, you’ve wired everything up properly and the feature module is being lazy loaded. A chunk should appear for Orders and for Customers but will only appear once for each. -
    - lazy loaded modules diagram -
    + lazy loaded modules diagram + + To see it again, or to test after working in the project, clear everything out by clicking the circle with a line through it in the upper left of the Network Tab:
    - lazy loaded modules diagram -
    + lazy loaded modules diagram + + Then reload with `Cmd+r` or `Ctrl+r`, depending on your platform. @@ -217,12 +218,14 @@ knows that the route list is only responsible for providing additional routes an `forRoot()` contains injector configuration which is global; such as configuring the Router. `forChild()` has no injector configuration, only directives such as `RouterOutlet` and `RouterLink`. -
    ## More on NgModules and routing You may also be interested in the following: + * [Routing and Navigation](guide/router). + * [Providers](guide/providers). + * [Types of Feature Modules](guide/module-types). diff --git a/aio/content/guide/lifecycle-hooks.md b/aio/content/guide/lifecycle-hooks.md index 1d13be0cfb..033cb629eb 100644 --- a/aio/content/guide/lifecycle-hooks.md +++ b/aio/content/guide/lifecycle-hooks.md @@ -41,7 +41,6 @@ that Angular calls shortly after creating the component: 每个接口都有唯一的一个钩子方法，它们的名字是由接口名再加上`ng`前缀构成的。比如，`OnInit`接口的钩子方法叫做`ngOnInit`， Angular在创建组件后立刻调用它，： - No directive or component will implement all of the lifecycle hooks. @@ -49,7 +48,6 @@ Angular only calls a directive/component hook method *if it is defined*. 没有指令或者组件会实现所有这些接口，并且有些钩子只对组件有意义。只有在指令/组件中*定义过的*那些钩子方法才会被Angular调用。 - {@a hooks-purpose-timing} ## Lifecycle sequence @@ -61,34 +59,28 @@ calls the lifecycle hook methods in the following sequence at specific moments: 当Angular使用构造函数新建一个组件或指令后，就会按下面的顺序在特定时刻调用这些生命周期钩子方法： - + + + - -

    - 钩子 -

    + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    -

    Hook -

    +     		HookPurpose and Timing -

    Purpose and Timing -

    - -

    - 目的和时机 -

    + ngOnChanges() + Respond when Angular (re)sets data-bound input properties. @@ -102,11 +94,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: 当被绑定的输入属性的值发生变化时调用，首次调用一定会发生在`ngOnInit()`之前。
    + ngOnInit() + Initialize the directive/component after Angular first displays the data-bound properties @@ -114,16 +112,22 @@ calls the lifecycle hook methods in the following sequence at specific moments: 在Angular第一次显示数据绑定和设置指令/组件的输入属性之后，初始化指令/组件。 - Called _once_, after the _first_ `ngOnChanges()`. + Called _once_, after the _first_ `ngOnChanges()`. 在第一轮`ngOnChanges()`完成之后调用，只调用**一次**。
    + ngDoCheck() + Detect and act upon changes that Angular can't or won't detect on its own. @@ -135,11 +139,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: 在每个Angular变更检测周期中调用，`ngOnChanges()`和`ngOnInit()`之后。
    + ngAfterContentInit() + Respond after Angular projects external content into the component's view / the view that a directive is in. @@ -151,11 +161,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: 第一次`ngDoCheck()`之后调用，只调用一次。
    + ngAfterContentChecked() + Respond after Angular checks the content projected into the directive/component. @@ -167,11 +183,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: `ngAfterContentInit()`和每次`ngDoCheck()`之后调用
    + ngAfterViewInit() + Respond after Angular initializes the component's views and child views / the view that a directive is in. @@ -183,11 +205,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: 第一次`ngAfterContentChecked()`之后调用，只调用一次。
    + ngAfterViewChecked() + Respond after Angular checks the component's views and child views / the view that a directive is in. @@ -199,11 +227,17 @@ calls the lifecycle hook methods in the following sequence at specific moments: `ngAfterViewInit()`和每次`ngAfterContentChecked()`之后调用。
    + ngOnDestroy() + Cleanup just before Angular destroys the directive/component. @@ -217,7 +251,9 @@ calls the lifecycle hook methods in the following sequence at specific moments: 在Angular销毁指令/组件之前调用。
    {@a interface-optional} @@ -234,11 +270,9 @@ Angular can't see TypeScript interfaces at runtime because they disappear from t Angular在运行时看不到TypeScript接口，因为它们在编译为JavaScript的时候已经消失了。 Fortunately, they aren't necessary. - -幸运的是，它们并不是必须的。 - You don't have to add the lifecycle hook interfaces to directives and components to benefit from the hooks themselves. +幸运的是，它们并不是必须的。 我们并不需要在指令和组件上添加生命周期钩子接口就能获得钩子带来的好处。 Angular instead inspects directive and component classes and calls the hook methods *if they are defined*. @@ -252,7 +286,6 @@ in order to benefit from strong typing and editor tooling. 虽然如此，我们还是强烈建议你在TypeScript指令类中添加接口，以获得强类型和IDE等编辑器带来的好处。 - {@a other-lifecycle-hooks} ## Other Angular lifecycle hooks @@ -263,7 +296,6 @@ Other Angular sub-systems may have their own lifecycle hooks apart from these co Angular的其它子系统除了有这些组件钩子外，还可能有它们自己的生命周期钩子。 - 3rd party libraries might implement their hooks as well in order to give developers more control over how these libraries are used. @@ -291,32 +323,27 @@ Here's a brief description of each exercise: 下面是每个练习简短的描述： + + + - -

    - 组件 -

    + - - - + + + + + + + + + + + + + + + + + - - - + + + + + + + - - - + + + + + + + + + + +
    -

    Component -

    +     		ComponentDescription -

    Description -

    - -

    - 描述 -

    + Peek-a-boo + Demonstrates every lifecycle hook. @@ -325,11 +352,17 @@ Here's a brief description of each exercise: 展示每个生命周期钩子，每个钩子方法都会在屏幕上显示一条日志。
    + Spy + Directives have lifecycle hooks too. @@ -344,11 +377,17 @@ Here's a brief description of each exercise: 本例把`SpyDirective`应用到父组件里的`ngFor`*英雄*重复器(repeater)的`
    `里面。
    + OnChanges + See how Angular calls the `ngOnChanges()` hook with a `changes` object @@ -358,13 +397,18 @@ Here's a brief description of each exercise: 这里将会看到：每当组件的输入属性发生变化时，Angular会如何以`changes`对象作为参数去调用`ngOnChanges()`钩子。 展示了该如何理解和使用`changes`对象。 +
    + + DoCheck
    - DoCheck - Implements an `ngDoCheck()` method with custom change detection. @@ -373,13 +417,18 @@ Here's a brief description of each exercise: 实现了一个`ngDoCheck()`方法，通过它可以自定义变更检测逻辑。 这里将会看到：Angular会用什么频度调用这个钩子，监视它的变化，并把这些变化输出成一条日志。 +
    + + AfterView
    - AfterView - Shows what Angular means by a *view*. @@ -389,11 +438,17 @@ Here's a brief description of each exercise: 演示了`ngAfterViewInit`和`ngAfterViewChecked`钩子。
    + AfterContent + Shows how to project external content into a component and @@ -404,19 +459,19 @@ Here's a brief description of each exercise: 演示了`ngAfterContentInit`和`ngAfterContentChecked`钩子。
    -

    - Counter -

    + Counter -

    - 计数器 -

    + 计数器     		Demonstrates a combination of a component and a directive @@ -433,14 +488,15 @@ Here's a brief description of each exercise: 同时，我们还把前一个例子中的`SpyDirective`用在`CounterComponent`上，来提供日志，可以同时观察到日志的创建和销毁过程。
    The remainder of this page discusses selected exercises in further detail. 接下来，我们将详细讨论这些练习。 - {@a peek-a-boo} ## Peek-a-boo: all hooks @@ -461,9 +517,10 @@ This snapshot reflects the state of the log after the user clicked the *Create.. 用户点击**Create...**按钮，然后点击**Destroy...**按钮后，日志的状态如下图所示： -
    + Peek-a-boo +
    The sequence of log messages follows the prescribed hook calling order: @@ -474,16 +531,14 @@ The sequence of log messages follows the prescribed hook calling order: `OnChanges`、`OnInit`、`DoCheck` (3x)、`AfterContentInit`、`AfterContentChecked` (3x)、 `AfterViewInit`、`AfterViewChecked` (3x)和`OnDestroy` -
    The constructor isn't an Angular hook *per se*. The log confirms that input properties (the `name` property in this case) have no assigned values at construction. -构造函数本质上不应该算作Angular的钩子。 + 构造函数本质上不应该算作Angular的钩子。 记录确认了在创建期间那些输入属性(这里是`name`属性)没有被赋值。 -
    Had the user clicked the *Update Hero* button, the log would show another `OnChanges` and two more triplets of @@ -497,7 +552,6 @@ The next examples focus on hook details. 下一个例子就聚焦于这些钩子的细节上。 - {@a spy} ## Spying *OnInit* and *OnDestroy* @@ -513,40 +567,34 @@ The heroes will never know they're being watched. 指令是一种完美的渗透方式，我们的英雄永远不会知道该指令的存在。 -
    Kidding aside, pay attention to two key points: -不开玩笑了，注意下面两个关键点： + 不开玩笑了，注意下面两个关键点： -1. Angular calls hook methods for *directives* as well as components.

    + 1. Angular calls hook methods for *directives* as well as components.

    - 就像对组件一样，Angular也会对*指令*调用这些钩子方法。 + 就像对组件一样，Angular也会对*指令*调用这些钩子方法。

    -2. A spy directive can provide insight into a DOM object that you cannot change directly. -Obviously you can't touch the implementation of a native `
    `. -You can't modify a third party component either. -But you can watch both with a directive. + 2. A spy directive can provide insight into a DOM object that you cannot change directly. + Obviously you can't touch the implementation of a native `
    `. + You can't modify a third party component either. + But you can watch both with a directive. - 一个侦探(spy)指令可以让我们在无法直接修改DOM对象实现代码的情况下，透视其内部细节。 + 一个侦探(spy)指令可以让我们在无法直接修改DOM对象实现代码的情况下，透视其内部细节。 显然，你不能修改一个原生`
    `元素的实现代码。 你同样不能修改第三方组件。 但我们用一个指令就能监视它们了。 -
    The sneaky spy directive is simple, consisting almost entirely of `ngOnInit()` and `ngOnDestroy()` hooks that log messages to the parent via an injected `LoggerService`. - 我们这个鬼鬼祟祟的侦探指令很简单，几乎完全由`ngOnInit()`和`ngOnDestroy()`钩子组成，它通过一个注入进来的`LoggerService`来把消息记录到父组件中去。 - - - - + You can apply the spy to any native or component element and it'll be initialized and destroyed at the same time as that element. @@ -555,17 +603,17 @@ Here it is attached to the repeated hero `
    `: 我们可以把这个侦探指令写到任何原生元素或组件元素上，它将与所在的组件同时初始化和销毁。 下面是把它附加到用来重复显示英雄数据的这个`
    `上。 - Each spy's birth and death marks the birth and death of the attached hero `
    ` with an entry in the *Hook Log* as seen here: - 每个“侦探”的出生和死亡也同时标记出了存放英雄的那个`
    `的出生和死亡。*钩子记录*中的结构是这样的： -
    +
    + Spy Directive +
    Adding a hero results in a new hero `
    `. The spy's `ngOnInit()` logs that event. @@ -584,7 +632,6 @@ The `ngOnInit()` and `ngOnDestroy()` methods have more vital roles to play in re 在真实的应用程序中，`ngOnInit()`和`ngOnDestroy()`方法扮演着更重要的角色。 - {@a oninit} ### _OnInit()_ @@ -598,7 +645,7 @@ Use `ngOnInit()` for two main reasons: 1. To perform complex initializations shortly after construction. 在构造函数之后马上执行复杂的初始化逻辑 - + 1. To set up the component after Angular sets the input properties. 在Angular设置完输入属性之后，对该组件进行准备。 @@ -607,7 +654,6 @@ Experienced developers agree that components should be cheap and safe to constru 有经验的开发者会认同组件的构建应该很便宜和安全。 -
    Misko Hevery, Angular team lead, @@ -616,7 +662,6 @@ Experienced developers agree that components should be cheap and safe to constru Misko Hevery，Angular项目的组长，在[这里解释](http://misko.hevery.com/code-reviewers-guide/flaw-constructor-does-real-work/)了你为什么应该避免复杂的构造函数逻辑。 -
    Don't fetch data in a component constructor. @@ -629,7 +674,7 @@ Constructors should do no more than set the initial local variables to simple va 构造函数中除了使用简单的值对局部变量进行初始化之外，什么都不应该做。 An `ngOnInit()` is a good place for a component to fetch its initial data. The -[Tour of Heroes Tutorial](tutorial/toh-pt4#oninit) guideshows how. +[Tour of Heroes Tutorial](tutorial/toh-pt4#oninit) guide shows how. `ngOnInit()`是组件获取初始数据的好地方。[指南](tutorial/toh-pt4#oninit)中讲解了如何这样做。 @@ -641,17 +686,15 @@ They'll have been set when `ngOnInit()` runs. 如果我们需要基于这些属性的值来初始化这个指令，这种情况就会出问题。 而当`ngOnInit()`执行的时候，这些属性都已经被正确的赋值过了。 -
    The `ngOnChanges()` method is your first opportunity to access those properties. Angular calls `ngOnChanges()` before `ngOnInit()` and many times after that. It only calls `ngOnInit()` once. -我们访问这些属性的第一次机会，实际上是`ngOnChanges()`方法，Angular会在`ngOnInit()`之前调用它。 + 我们访问这些属性的第一次机会，实际上是`ngOnChanges()`方法，Angular会在`ngOnInit()`之前调用它。 但是在那之后，Angular还会调用`ngOnChanges()`很多次。而`ngOnInit()`只会被调用一次。 -
    You can count on Angular to call the `ngOnInit()` method _soon_ after creating the component. @@ -660,7 +703,6 @@ That's where the heavy initialization logic belongs. 你可以信任Angular会在创建组件后立刻调用`ngOnInit()`方法。 这里是放置复杂初始化逻辑的好地方。 - {@a ondestroy} ### _OnDestroy()_ @@ -684,8 +726,6 @@ You risk memory leaks if you neglect to do so. 取消那些对可观察对象和DOM事件的订阅。停止定时器。注销该指令曾注册到全局服务或应用级服务中的各种回调函数。 如果不这么做，就会有导致内存泄露的风险。 - - {@a onchanges} ## _OnChanges()_ @@ -693,14 +733,11 @@ You risk memory leaks if you neglect to do so. ## _OnChanges()_ 钩子 Angular calls its `ngOnChanges()` method whenever it detects changes to ***input properties*** of the component (or directive). - -一旦检测到该组件(或指令)的***输入属性***发生了变化，Angular就会调用它的`ngOnChanges()`方法。 - This example monitors the `OnChanges` hook. +一旦检测到该组件(或指令)的***输入属性***发生了变化，Angular就会调用它的`ngOnChanges()`方法。 本例监控`OnChanges`钩子。 - The `ngOnChanges()` method takes an object that maps each changed property name to a @@ -714,26 +751,22 @@ The example component, `OnChangesComponent`, has two input properties: `hero` an 这个例子中的`OnChangesComponent`组件有两个输入属性：`hero`和`power`。 - The host `OnChangesParentComponent` binds to them like this: - 宿主`OnChangesParentComponent`绑定了它们，就像这样： - - - - + Here's the sample in action as the user makes changes. - 下面是此例子中的当用户做出更改时的操作演示： -
    +
    + OnChanges +
    The log entries appear as the string value of the *power* property changes. @@ -754,8 +787,6 @@ Angular只会在输入属性的值变化时调用这个钩子。 Angular不会关注这个英雄对象的`name`属性的变化。 这个英雄对象的*引用*没有发生变化，于是从Angular的视角看来，也就没有什么需要报告的变化了。 - - {@a docheck} ## _DoCheck()_ @@ -766,13 +797,11 @@ Use the `DoCheck` hook to detect and act upon changes that Angular doesn't catch 使用`DoCheck`钩子来检测那些Angular自身无法捕获的变更并采取行动。 -
    Use this method to detect a change that Angular overlooked. -用这个方法来检测那些被Angular忽略的更改。 - + 用这个方法来检测那些被Angular忽略的更改。
    @@ -780,20 +809,20 @@ The *DoCheck* sample extends the *OnChanges* sample with the following `ngDoChec *DoCheck*范例通过下面的`ngDoCheck()`实现扩展了*OnChanges*范例： - This code inspects certain _values of interest_, capturing and comparing their current state against previous values. It writes a special message to the log when there are no substantive changes to the `hero` or the `power` so you can see how often `DoCheck` is called. The results are illuminating: - 该代码检测一些**相关的值**，捕获当前值并与以前的值进行比较。 当英雄或它的超能力发生了非实质性改变时，我们就往日志中写一条特殊的消息。 这样你可以看到`DoCheck`被调用的频率。结果非常显眼： -
    +
    + DoCheck +
    While the `ngDoCheck()` hook can detect when the hero's `name` has changed, it has a frightful cost. @@ -830,14 +859,12 @@ Here's a child view that displays a hero's name in an ``: 下面是一个子视图，它用来把英雄的名字显示在一个``中： - The `AfterViewComponent` displays this child view *within its template*: `AfterViewComponent`把这个子视图显示*在它的模板中*： - The following hooks take action based on changing values *within the child view*, @@ -846,7 +873,6 @@ which can only be reached by querying for the child view via the property decora 下列钩子基于*子视图中*的每一次数据变更采取行动，我们只能通过带[@ViewChild](api/core/ViewChild)装饰器的属性来访问子视图。 - {@a wait-a-tick} @@ -859,9 +885,7 @@ The `doSomething()` method updates the screen when the hero name exceeds 10 char 当英雄的名字超过10个字符时，`doSomething()`方法就会更新屏幕。 - - - + Why does the `doSomething()` method wait a tick before updating `comment`? @@ -880,14 +904,14 @@ for one turn of the browser's JavaScript cycle and that's just long enough. 如果我们立即更新组件中被绑定的`comment`属性，Angular就会抛出一个错误(试试!)。 `LoggerService.tick_then()`方法延迟更新日志一个回合（浏览器JavaScript周期回合），这样就够了。 - Here's *AfterView* in action: 这里是*AfterView*的操作演示： -
    + AfterView +
    Notice that Angular frequently calls `AfterViewChecked()`, often when there are no changes of interest. @@ -896,8 +920,6 @@ Write lean hook methods to avoid performance problems. 注意，Angular会频繁的调用`AfterViewChecked()`，甚至在并没有需要关注的更改时也会触发。 所以务必把这个钩子方法写得尽可能精简，以免出现性能问题。 - - {@a aftercontent} ## AfterContent @@ -909,7 +931,6 @@ The *AfterContent* sample explores the `AfterContentInit()` and `AfterContentChe *AfterContent*例子展示了`AfterContentInit()`和`AfterContentChecked()`钩子，Angular会在外来内容被投影到组件中*之后*调用它们。 - {@a content-projection} ### Content projection @@ -921,13 +942,11 @@ into the component's template in a designated spot. *内容投影*是从组件外部导入HTML内容，并把它插入在组件模板中指定位置上的一种途径。 -
    AngularJS developers know this technique as *transclusion*. -AngularJS的开发者大概知道一项叫做*transclusion*的技术，对，这就是它的马甲。 - + AngularJS的开发者大概知道一项叫做*transclusion*的技术，对，这就是它的马甲。
    @@ -938,7 +957,6 @@ the `AfterContentComponent`'s parent. Here's the parent's template: 对比[前一个](guide/lifecycle-hooks#afterview)例子考虑这个变化。 这次，我们不再通过模板来把子视图包含进来，而是改从`AfterContentComponent`的父组件中导入它。下面是父组件的模板： - Notice that the `` tag is tucked between the `` tags. @@ -952,7 +970,6 @@ Now look at the component's template: 现在来看下``组件的模板： - The `` tag is a *placeholder* for the external content. @@ -963,25 +980,25 @@ In this case, the projected content is the `` from the parent. 它告诉Angular在哪里插入这些外来内容。 在这里，被投影进去的内容就是来自父组件的``标签。 -
    + Projected Content +
    The telltale signs of *content projection* are twofold: -下列迹象表明存在着*内容投影*： + 下列迹象表明存在着*内容投影*： * HTML between component element tags. - - 在组件的元素标签中有HTML - + + 在组件的元素标签中有HTML + * The presence of `` tags in the component's template. - 组件的模板中出现了``标签 - + 组件的模板中出现了``标签
    @@ -989,9 +1006,9 @@ In this case, the projected content is the `` from the parent. ### AfterContent hooks -### AfterContent钩子 +### AfterContent钩子 -*AfterContent* hooks are similar to the *AfterView* hooks. +*AfterContent* hooks are similar to the *AfterView* hooks. The key difference is in the child component. *AfterContent*钩子和*AfterView*相似。关键的不同点是子组件的类型不同。 @@ -999,20 +1016,21 @@ The key difference is in the child component. * The *AfterView* hooks concern `ViewChildren`, the child components whose element tags appear *within* the component's template. - *AfterView*钩子所关心的是`ViewChildren`，这些子组件的元素标签会出现在该组件的模板*里面*。 + *AfterView*钩子所关心的是`ViewChildren`，这些子组件的元素标签会出现在该组件的模板*里面*。 * The *AfterContent* hooks concern `ContentChildren`, the child components that Angular projected into the component. - *AfterContent*钩子所关心的是`ContentChildren`，这些子组件被Angular投影进该组件中。 + *AfterContent*钩子所关心的是`ContentChildren`，这些子组件被Angular投影进该组件中。 The following *AfterContent* hooks take action based on changing values in a *content child*, which can only be reached by querying for them via the property decorated with [@ContentChild](api/core/ContentChild). - 下列*AfterContent*钩子基于*子级内容*中值的变化而采取相应的行动，这里我们只能通过带有[@ContentChild](api/core/ContentChild)装饰器的属性来查询到“子级内容”。 + + {@a no-unidirectional-flow-worries} ### No unidirectional flow worries with _AfterContent_ @@ -1029,6 +1047,7 @@ Recall that Angular calls both *AfterContent* hooks before calling either of the Angular completes composition of the projected content *before* finishing the composition of this component's view. There is a small window between the `AfterContent...` and `AfterView...` hooks to modify the host view. + 回忆一下，Angular在每次调用*AfterView*钩子之前也会同时调用*AfterContent*。 Angular在完成当前组件的视图合成之前，就已经完成了被投影内容的合成。 -所以我们仍然有机会去修改那个视图。 +所以我们仍然有机会去修改那个视图。 \ No newline at end of file diff --git a/aio/content/guide/module-types.md b/aio/content/guide/module-types.md index 1e768858a7..7c338d5ae1 100644 --- a/aio/content/guide/module-types.md +++ b/aio/content/guide/module-types.md @@ -5,8 +5,13 @@ #### Prerequisites A basic understanding of the following concepts: + +对下列概念有基本的理解： + * [Feature Modules](guide/feature-modules). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule). + * [Frequently Used Modules](guide/frequent-ngmodules).
    @@ -15,9 +20,13 @@ There are five general categories of feature modules which tend to fall into the following groups: * Domain feature modules. + * Routed feature modules. + * Routing modules. + * Service feature modules. + * Widget feature modules. While the following guidelines describe the use of each type and their @@ -26,18 +35,27 @@ typical characteristics, in real world apps, you may see hybrids. + + + + + + + + + + + + + + + + + +
    + Feature Module + + Guidelines +
    Domain + Domain feature modules deliver a user experience dedicated to a particular application domain like editing a customer or placing an order. They typically have a top component that acts as the feature root and private, supporting sub-components descend from it. @@ -49,11 +67,17 @@ typical characteristics, in real world apps, you may see hybrids. Domain feature modules are typically imported exactly once by a larger feature module. They might be imported by the root `AppModule` of a small application that lacks routing. +
    Routed + Routed feature modules are domain feature modules whose top components are the targets of router navigation routes. All lazy-loaded modules are routed feature modules by definition. @@ -63,11 +87,15 @@ typical characteristics, in real world apps, you may see hybrids. A lazy-loaded routed feature module should not be imported by any module. Doing so would trigger an eager load, defeating the purpose of lazy loading.That means you won’t see them mentioned among the `AppModule` imports. An eager loaded routed feature module must be imported by another module so that the compiler learns about its components. Routed feature modules rarely have providers for reasons explained in [Lazy Loading Feature Modules](/guide/lazy-loading-ngmodules). When they do, the lifetime of the provided services should be the same as the lifetime of the module. Don't provide application-wide singleton services in a routed feature module or in a module that the routed module imports. +
    Routing A routing module provides routing configuration for another module and separates routing concerns from its companion module. @@ -75,21 +103,31 @@ typical characteristics, in real world apps, you may see hybrids. A routing module typically does the following:
      +
    • Defines routes.
      • +
    • Adds router configuration to the module's imports.
      • +
    • Adds guard and resolver service providers to the module's providers.
      • +
    • The name of the routing module should parallel the name of its companion module, using the suffix "Routing". For example, FooModule in foo.module.ts has a routing module named FooRoutingModule in foo-routing.module.ts. If the companion module is the root AppModule, the AppRoutingModule adds router configuration to its imports with RouterModule.forRoot(routes). All other routing modules are children that import RouterModule.forChild(routes).
      • +
    • A routing module re-exports the RouterModule as a convenience so that components of the companion module have access to router directives such as RouterLink and RouterOutlet.
      • +
    • A routing module does not have its own declarations. Components, directives, and pipes are the responsibility of the feature module, not the routing module.
      • +
    A routing module should only be imported by its companion module.
    Service Service modules provide utility services such as data access and messaging. Ideally, they consist entirely of providers and have no declarations. Angular's `HttpClientModule` is a good example of a service module. @@ -97,10 +135,13 @@ typical characteristics, in real world apps, you may see hybrids. The root `AppModule` is the only module that should import service modules.
    Widget A widget module makes components, directives, and pipes available to external modules. Many third-party UI component libraries are widget modules. @@ -112,6 +153,7 @@ typical characteristics, in real world apps, you may see hybrids. Import widget modules in any module whose component templates need the widgets.
    @@ -119,67 +161,111 @@ typical characteristics, in real world apps, you may see hybrids. The following table summarizes the key characteristics of each feature module group. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Feature Module + + Declarations + + Providers + + Exports + + Imported by +
    DomainYesRareTop componentFeature, AppModule
    RoutedYesRareNoNone
    RoutingNoYes (Guards)RouterModuleFeature (for routing)
    ServiceNoYesNoAppModule
    WidgetYesRareYesFeature
    @@ -187,5 +273,7 @@ The following table summarizes the key characteristics of each feature module gr ## More on NgModules You may also be interested in the following: + * [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules). + * [Providers](guide/providers). diff --git a/aio/content/guide/ngmodule-api.md b/aio/content/guide/ngmodule-api.md index e661cad113..024796fd2f 100644 --- a/aio/content/guide/ngmodule-api.md +++ b/aio/content/guide/ngmodule-api.md @@ -3,7 +3,11 @@ #### Prerequisites A basic understanding of the following concepts: + +对下列概念有基本的理解： + * [Bootstrapping](guide/bootstrapping). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
    @@ -16,7 +20,9 @@ decorator. The metadata falls into three categories: * **Static:** Compiler configuration which tells the compiler about directive selectors and where in templates the directives should be applied through selector matching. This is configured via the `declarations` array. + * **Runtime:** Injector configuration via the `providers` array. + * **Composability/Grouping:** Bringing NgModules together and making them available via the `imports` and `exports` arrays. ```typescript @@ -43,11 +49,19 @@ The following table summarizes the `@NgModule` metadata properties.

    + Property + + 属性 + + Description + + 描述 +
    + declarations + @@ -64,14 +80,23 @@ The following table summarizes the `@NgModule` metadata properties. (*components*, *directives*, and *pipes*) that _belong to this module_.
      +
    1. When compiling a template, you need to determine a set of selectors which should be used for triggering their corresponding directives.
      2. +
    2. + The template is compiled within the context of an NgModule—the NgModule within which the template's component is declared—which determines the set of selectors using the following rules: +
        +
      • All selectors of directives listed in `declarations`.
        • +
      • All selectors of directives exported from imported NgModules.
        • +
      +
      3. +
    Components, directives, and pipes must belong to _exactly_ one module. @@ -86,7 +111,9 @@ The following table summarizes the `@NgModule` metadata properties.
    + providers + @@ -117,7 +144,9 @@ The following table summarizes the `@NgModule` metadata properties.
    + imports + @@ -145,7 +174,9 @@ The following table summarizes the `@NgModule` metadata properties.
    + exports + @@ -179,7 +210,9 @@ The following table summarizes the `@NgModule` metadata properties.
    + bootstrap + @@ -200,7 +233,9 @@ The following table summarizes the `@NgModule` metadata properties.
    + entryComponents + @@ -224,19 +259,24 @@ The following table summarizes the `@NgModule` metadata properties. For more information, see [Entry Components](guide/entry-components). + 要了解更多，参见[入口组件](guide/entry-components)一章。 +
    -
    ## More on NgModules You may also be interested in the following: + * [Feature Modules](guide/feature-modules). + * [Entry Components](guide/entry-components). + * [Providers](guide/providers). + * [Types of Feature Modules](guide/module-types). diff --git a/aio/content/guide/ngmodule-faq.md b/aio/content/guide/ngmodule-faq.md index c1e65e0869..4460866788 100644 --- a/aio/content/guide/ngmodule-faq.md +++ b/aio/content/guide/ngmodule-faq.md @@ -22,7 +22,6 @@ This page answers the questions many developers ask about NgModule design and im 这里回答的是开发者常问起的关于Angular模块的设计与实现问题。 - ## What classes should I add to the `declarations` array? ## 我应该把哪些类加到*declarations*中？ @@ -51,7 +50,6 @@ They're the only classes that you can add to `declarations`. *可声明的*就是组件、指令和管道等可以被加到模块的`declarations`列表中的类。它们也是*所有*能被加到`declarations`中的类。 -
    ## What classes should I _not_ add to `declarations`? @@ -68,30 +66,28 @@ Do *not* declare the following: * A class that's already declared in another module, whether an app module, @NgModule, or third-party module. - 已经在其它模块中声明过的类。无论它来自应用自己的模块（@NgModule）还是第三方模块。 - + 已经在其它模块中声明过的类。无论它来自应用自己的模块（@NgModule）还是第三方模块。 + * An array of directives imported from another module. For example, don't declare `FORMS_DIRECTIVES` from `@angular/forms` because the `FormsModule` already declares it. - 从其它模块中导入的指令。例如，不要声明来自`@angular/forms`的FORMS_DIRECTIVES，因为 `FormsModule` 已经声明过它们了。 + 从其它模块中导入的指令。例如，不要声明来自`@angular/forms`的FORMS_DIRECTIVES，因为 `FormsModule` 已经声明过它们了。 * Module classes. - 模块类。 - + 模块类。 + * Service classes. - 服务类 - + 服务类 + * Non-Angular classes and objects, such as strings, numbers, functions, entity models, configurations, business logic, and helper classes. - 非Angular的类和对象，比如：字符串、数字、函数、实体模型、配置、业务逻辑和辅助类。 - + 非Angular的类和对象，比如：字符串、数字、函数、实体模型、配置、业务逻辑和辅助类。
    - ## Why list the same component in multiple `NgModule` properties? ## 为什么要把同一个组件声明在不同的*NgModule*属性中？ @@ -109,22 +105,20 @@ Membership in one list doesn't imply membership in another list. * `AppComponent` could be declared in this module but not bootstrapped. - `AppComponent`可能被声明在此模块中，但可能不是引导组件。 + `AppComponent`可能被声明在此模块中，但可能不是引导组件。 * `AppComponent` could be bootstrapped in this module but declared in a different feature module. - `AppComponent`可能在此模块中引导，但可能是由另一个特性模块声明的。 + `AppComponent`可能在此模块中引导，但可能是由另一个特性模块声明的。 * A component could be imported from another app module (so you can't declare it) and re-exported by this module. - `HeroComponent`可能是从另一个应用模块中导入的（所以我们没法声明它）并且被当前模块重新导出。 - + `HeroComponent`可能是从另一个应用模块中导入的（所以我们没法声明它）并且被当前模块重新导出。 + * A component could be exported for inclusion in an external component's template as well as dynamically loaded in a pop-up dialog. - `HeroComponent`可能被导入，以便用在外部组件的模板中，但也可能同时被一个弹出式对话框加载。 - - + `HeroComponent`可能被导入，以便用在外部组件的模板中，但也可能同时被一个弹出式对话框加载。
    @@ -178,7 +172,6 @@ Import only [BrowserModule](guide/ngmodule-faq#q-browser-vs-common-module) in th 只能在根模块`AppModule`中[导入_BrowserModule_](guide/ngmodule-faq#q-browser-vs-common-module)。 -
    {@a q-browser-vs-common-module} @@ -214,7 +207,6 @@ Importing `CommonModule` also frees feature modules for use on _any_ target plat 特性模块中导入`CommonModule`可以让它能用在任何目标平台上，不仅是浏览器。那些跨平台库的作者应该喜欢这种方式的。 -
    {@a q-reimport} @@ -260,9 +252,12 @@ declared in this NgModule. You _can_ export any declarable class—components, directives, and pipes—whether it's declared in this NgModule or in an imported NgModule. -你*可以*导出任何可声明类（组件、指令和管道），而不用管它是声明在当前模块中还是某个导入的模块中。You _can_ re-export entire imported NgModules, which effectively re-exports all of their exported classes. +你*可以*导出任何可声明类（组件、指令和管道），而不用管它是声明在当前模块中还是某个导入的模块中。 + +You _can_ re-export entire imported NgModules, which effectively re-exports all of their exported classes. An NgModule can even export a module that it doesn't import. -你*可以*重新导出整个导入过的模块，这将导致重新导出它们导出的所有类。模块甚至还可以导出它未曾导入过的模块。 + +你*可以*重新导出整个导入过的模块，这将导致重新导出它们导出的所有类。重新导出的模块甚至不用先导入。
    @@ -277,33 +272,30 @@ Don't export the following: * Private components, directives, and pipes that you need only within components declared in this NgModule. If you don't want another NgModule to see it, don't export it. - 那些你只想在当前模块中声明的那些组件中使用的私有组件、指令和管道。如果你不希望任何模块看到它，就不要导出。 - + 那些你只想在当前模块中声明的那些组件中使用的私有组件、指令和管道。如果你不希望任何模块看到它，就不要导出。 + * Non-declarable objects such as services, functions, configurations, and entity models. - 不可声明的对象，比如服务、函数、配置、实体模型等。 - + 不可声明的对象，比如服务、函数、配置、实体模型等。 + * Components that are only loaded dynamically by the router or by bootstrapping. Such [entry components](guide/ngmodule-faq#q-entry-component-defined) can never be selected in another component's template. While there's no harm in exporting them, there's also no benefit. - 那些只被路由器或引导函数动态加载的组件。 + 那些只被路由器或引导函数动态加载的组件。 比如[入口组件](guide/ngmodule-faq#q-entry-component-defined)可能从来不会在其它组件的模板中出现。 导出它们没有坏处，但也没有好处。 - + * Pure service modules that don't have public (exported) declarations. For example, there's no point in re-exporting `HttpClientModule` because it doesn't export anything. Its only purpose is to add http service providers to the application as a whole. - 纯服务模块没有公开（导出）的声明。 + 纯服务模块没有公开（导出）的声明。 例如，没必要重新导出`HttpClientModule`，因为它不导出任何东西。 它唯一的用途是一起把http的那些服务提供商添加到应用中。 -
    - - ## Can I re-export classes and modules? ## 我可以重新导出类和模块吗？ @@ -341,10 +333,8 @@ Its only purpose is to add http service providers to the application as a whole. 例如，不用重新导出`HttpClientModule`，因为它没有导出任何东西。 它唯一的用途是把那些http服务提供商一起添加到应用中。 -
    - ## What is the `forRoot()` method? ## *forRoot*方法是什么？ @@ -388,10 +378,8 @@ Follow this convention when you write similar modules with configurable service Angular并不识别这些名字，但是Angular的开发人员可以。 当你写类似的需要可配置的服务提供商时，请遵循这个约定。 -
    - ## Why is a service provided in a feature module visible everywhere? ## 为什么服务提供商在特性模块中的任何地方都是可见的？ @@ -432,7 +420,6 @@ not just the classes declared in the `HeroModule`. 不过，如果你期望模块的服务只对那个特性模块内部声明的组件可见，那么这可能会带来一些不受欢迎的意外。 如果`HeroModule`提供了一个`HeroService`，并且根模块`AppModule`导入了`HeroModule`，那么任何知道`HeroService`*类型*的类都可能注入该服务，而不仅是在`HeroModule`中声明的那些类。 -
    {@a q-lazy-loaded-module-provider-visibility} @@ -464,10 +451,8 @@ Angular prefers service instances created from these providers to the service in 这些提供商不会被拥有相同令牌的应用级别提供商的变化所影响。 当路由器在惰性加载环境中创建组件时，Angular优先使用惰性加载模块中的服务实例，而不是来自应用的根注入器的。 -
    - ## What if two modules provide the same service? ## 如果两个模块提供了*同一个*服务会怎么样？ @@ -498,10 +483,8 @@ The `AppModule` always wins. 由根`AppModule`提供的服务相对于所导入模块中提供的服务有优先权。换句话说：`AppModule`总会获胜。 -
    - ## How do I restrict service scope to a module? ## 我们应该如何把服务的范围限制到模块中？ @@ -587,12 +570,10 @@ Define child routes and let the router load module components into that outlet. 你可以把这些子组件都嵌在顶级组件的模板中。或者，给顶级组件一个``，让它作为路由的宿主。 定义子路由，并让路由器把模块中的组件加载进该路由出口（outlet）中。 -
    {@a q-root-component-or-module} - ## Should I add application-wide providers to the root `AppModule` or the root `AppComponent`? ## 我应该把全应用级提供商添加到根模块`AppModule`中还是根组件`AppComponent`中？ @@ -654,8 +635,6 @@ This means that lazy-loaded modules can't reach them. {@a q-component-or-module} - - ## Should I add other providers to a module or a component? ## 我应该把其它提供商注册到模块中还是组件中？ @@ -686,12 +665,10 @@ not the root `AppComponent`. [总是在根模块`AppModule`中注册*全应用级*服务](guide/ngmodule-faq#q-root-component-or-module)，而不要在根组件`AppComponent`中。 -
    {@a q-why-bad} - ## Why is it bad if a shared module provides a service to a lazy-loaded module? ## 为什么在共享模块中为惰性加载模块提供服务是个馊主意？ @@ -790,7 +767,6 @@ Angular必须把这个惰性加载模块中的提供商添加到*某个*注入 但是它无法将它们添加到应用的根注入器中，因为根注入器已经不再接受新的提供商了。 于是，Angular在惰性加载模块的上下文中创建了一个新的子注入器。 -
    {@a q-is-it-loaded} @@ -817,8 +793,8 @@ Here is a custom constructor for an NgModule called `CoreModule`. 某些Angular模块（例如`BrowserModule`）就实现了一个像 Angular 模块那一章的`CoreModule`构造函数那样的守卫。 - +
    @@ -852,7 +828,6 @@ selector doesn't match an element in any component template. 而用于引导的根`AppComponent`则是一个*入口组件*。 虽然它的选择器匹配了`index.html`中的一个元素，但是`index.html`并不是组件模板，而且`AppComponent`选择器也不会在任何组件模板中出现。 - Components in route definitions are also _entry components_. A route definition refers to a component by its _type_. The router ignores a routed component's selector, if it even has one, and @@ -890,7 +865,6 @@ although doing so is harmless. 不需要把组件同时列在`bootstrap`和`entryComponent`列表中 —— 虽然这样做也没坏处。 - For more information, see [Entry Components](guide/entry-components). 要了解更多，参见[入口组件](guide/entry-components)一章。 @@ -928,14 +902,12 @@ in the templates of other components. 虽然把组件加到这个列表中也没什么坏处，不过最好还是只添加真正的*入口组件*。 不要添加那些被其它组件的模板[引用过](guide/ngmodule-faq#q-template-reference)的组件。 - For more information, see [Entry Components](guide/entry-components). 要了解更多，参见[入口组件](guide/entry-components)一章。
    - ## Why does Angular need _entryComponents_? ## 为什么 Angular 需要*入口组件*？ @@ -975,7 +947,6 @@ the compiler omits it. 如果该组件不是*入口组件*或者没有在任何模板中发现过，编译器就会忽略它。 -
    ## What kinds of modules should I have and how should I use them? @@ -988,6 +959,7 @@ Some suggestions and guidelines appear to have wide appeal. 每个应用都不一样。根据不同程度的经验，开发者会做出不同的选择。下列建议和指导原则广受欢迎。 ### `SharedModule` + `SharedModule` is a conventional name for an `NgModule` with the components, directives, and pipes that you use everywhere in your app. This module should consist entirely of `declarations`, most of them exported. @@ -1013,6 +985,7 @@ both those loaded when the app starts and those you lazy load later. 在任何特性模块中（无论是你在应用启动时主动加载的模块还是之后惰性加载的模块），你都可以随意导入这个`SharedModule`。 ### `CoreModule` + `CoreModule` is a conventional name for an `NgModule` with `providers` for the singleton services you load when the application starts. @@ -1048,8 +1021,6 @@ would make up the search functionality. For more information, see [Feature Modules](guide/feature-modules) and [Module Types](guide/module-types) - - ## What's the difference between NgModules and JavaScript Modules? In an Angular app, NgModules and JavaScript modules work together. @@ -1096,8 +1067,11 @@ Angular编译器通过在一个模板的HTML中匹配组件或指令的**选择 The compiler finds a pipe if the pipe's *name* appears within the pipe syntax of the template HTML. -编译器通过分析模板HTML中的管道语法中是否出现了特定的管道名来查找对应的管道。Angular only matches selectors and pipe names for classes that are declared by this module +编译器通过分析模板HTML中的管道语法中是否出现了特定的管道名来查找对应的管道。 + +Angular only matches selectors and pipe names for classes that are declared by this module or exported by a module that this module imports. + Angular只查询两种组件、指令或管道：1）那些在当前模块中声明过的，以及2）那些被当前模块导入的模块所导出的。
    @@ -1140,4 +1114,5 @@ the Angular compiler incorporates them into compiled component code too. `@NgModule` metadata tells the Angular compiler what components to compile for this module and how to link this module with other modules. -`@NgModule`元数据告诉*Angular编译器*要为当前模块编译哪些组件，以及如何把当前模块和其它模块链接起来。 + +`@NgModule`元数据告诉*Angular编译器*要为当前模块编译哪些组件，以及如何把当前模块和其它模块链接起来。 \ No newline at end of file diff --git a/aio/content/guide/ngmodule-vs-jsmodule.md b/aio/content/guide/ngmodule-vs-jsmodule.md index 36866b2cfc..92b862a45c 100644 --- a/aio/content/guide/ngmodule-vs-jsmodule.md +++ b/aio/content/guide/ngmodule-vs-jsmodule.md @@ -1,6 +1,7 @@ # JavaScript Modules vs. NgModules #### Prerequisites + A basic understanding of [JavaScript/ECMAScript modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/).
    @@ -52,15 +53,17 @@ import { AppComponent } from './app.component'; export class AppModule { } ``` - The NgModule classes differ from JavaScript module in the following key ways: * An NgModule bounds [declarable classes](guide/ngmodule-faq#q-declarable) only. Declarables are the only classes that matter to the [Angular compiler](guide/ngmodule-faq#q-angular-compiler). + * Instead of defining all member classes in one giant file as in a JavaScript module, you list the module's classes in the `@NgModule.declarations` list. + * An NgModule can only export the [declarable classes](guide/ngmodule-faq#q-declarable) it owns or imports from other modules. It doesn't declare or export any other kind of class. + * Unlike JavaScript modules, an NgModule can extend the _entire_ application with services by adding providers to the `@NgModule.providers` list. @@ -69,6 +72,9 @@ by adding providers to the `@NgModule.providers` list. ## More on NgModules For more information on NgModules, see: + * [Bootstrapping](guide/bootstrapping). + * [Frequently used modules](guide/frequent-ngmodules). + * [Providers](guide/providers). diff --git a/aio/content/guide/ngmodules.md b/aio/content/guide/ngmodules.md index b3f136a340..8483e5b3be 100644 --- a/aio/content/guide/ngmodules.md +++ b/aio/content/guide/ngmodules.md @@ -3,7 +3,11 @@ #### Prerequisites A basic understanding of the following concepts: + +对下列概念有基本的理解： + * [Bootstrapping](guide/bootstrapping). + * [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
    @@ -20,7 +24,6 @@ For an example app showcasing all the techniques that NgModules related pages cover, see the . For explanations on the individual techniques, visit the relevant NgModule pages under the NgModules section. - ## Angular modularity Modules are a great way to organize an application and extend it with capabilities from external libraries. @@ -43,8 +46,11 @@ Modules can be loaded eagerly when the application starts or lazy loaded asynchr NgModule metadata does the following: * Declares which components, directives, and pipes belong to the module. + * Makes some of those components, directives, and pipes public so that other module's component templates can use them. + * Imports other modules with the components, directives, and pipes that components in the current module need. + * Provides services that the other application components can use. Every Angular app has at least one module, the root module. @@ -60,6 +66,7 @@ You then import these modules into the root module. The CLI generates the following basic app module when creating a new app. + At the top are the import statements. The next section is where you configure the `@NgModule` by stating what components and directives belong to it (`declarations`) as well as which other modules it uses (`imports`). This page builds on [Bootstrapping](guide/bootstrapping), which covers the structure of an NgModule in detail. If you need more information on the structure of an `@NgModule`, be sure to read [Bootstrapping](guide/bootstrapping). @@ -69,7 +76,11 @@ At the top are the import statements. The next section is where you configure th ## More on NgModules You may also be interested in the following: + * [Feature Modules](guide/feature-modules). + * [Entry Components](guide/entry-components). + * [Providers](guide/providers). + * [Types of NgModules](guide/module-types). diff --git a/aio/content/guide/npm-packages.md b/aio/content/guide/npm-packages.md index 973127a0ea..3f106f744e 100644 --- a/aio/content/guide/npm-packages.md +++ b/aio/content/guide/npm-packages.md @@ -4,7 +4,7 @@ The [**Angular CLI**](https://cli.angular.io/), Angular applications, and Angular itself depend upon features and functionality provided by libraries that are available as [**npm**](https://docs.npmjs.com/) packages. -[**Angular CLI**](https://cli.angular.io/)、Angular应用程序以及Angular本身都依赖于很多第三方包(包括Angular自己)提供的特性和功能。这些都是 [**npm**](https://docs.npmjs.com/) 包。 + [**Angular CLI**](https://cli.angular.io/)、Angular应用程序以及Angular本身都依赖于很多第三方包(包括Angular自己)提供的特性和功能。这些都是 [**npm**](https://docs.npmjs.com/) 包。 You can download and install these npm packages with the [**npm client**](https://docs.npmjs.com/cli/install), which runs as a node.js application. @@ -18,7 +18,7 @@ The Angular CLI uses `yarn` by default to install npm packages when you create a
    -Node.js and npm are essential to Angular development. +Node.js and npm are essential to Angular development. Node.js和npm是做Angular开发的基础。 @@ -31,8 +31,8 @@ if they're not already installed on your machine. by running the commands `node -v` and `npm -v` in a terminal/console window. Older versions produce errors. -通过在终端/控制台窗口中运行`node -v`和`npm -v`命令，来**验证下你是否正在使用node `v4.x.x`和npm `3.x.x`**。 - 过老的版本有可能出现问题。 +在终端/控制器窗口运行命令`node -v`和`npm -v`，来**确认你运行的 node 是`v4.x.x`或更高，npm 为`3.x.x`或更高。** +老版本会产生错误。 Consider using [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if @@ -86,17 +86,17 @@ The `dependencies` section of `package.json` contains: 应用程序的`package.json`文件中，`dependencies`下包括： -* **Angular packages **: Angular core and optional modules; their package names begin `@angular/`. +* **Angular packages**: Angular core and optional modules; their package names begin `@angular/`. **Angular 包**：Angular 的核心和可选模块，它们的包名以`@angular/`开头。 * **Support packages**: 3rd party libraries that must be present for Angular apps to run. - **支持包**：那些Angular 应用运行时必需的第三方库。 - + **支持包**：那些Angular 应用运行时必需的第三方库。 + * **Polyfill packages**: Polyfills plug gaps in a browser's JavaScript implementation. - **腻子脚本**：腻子脚本负责抹平不同浏览器的 JavaScript 实现之间的差异。 + **腻子脚本**：腻子脚本负责抹平不同浏览器的 JavaScript 实现之间的差异。 ### Angular Packages @@ -187,7 +187,6 @@ which polyfills missing features for several popular browser. **[rxjs](https://github.com/benlesh/RxJS)**：很多 Angular API 都会返回**可观察对象（Observable）**。RxJS 是个对[Observables规范](https://github.com/zenparsing/es-observable)的当前实现。[TC39](http://www.ecma-international.org/memento/TC39.htm)委员会将来会决定它是否成为 JavaScript 语言标准的一部分。 - **[zone.js](https://github.com/angular/zone.js)**: Angular relies on zone.js to run Angular's change detection processes when native JavaScript operations raise events. Zone.js is an implementation of a [specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the [TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language. @@ -226,6 +225,10 @@ For example, see the [Angular language service extension for VS Code](https://ma **[codelyzer](https://www.npmjs.com/package/codelyzer)**：专用于 Angular 应用的 linter，它的规则适用于 Angular 的[风格指南](guide/styleguide)。 +**jasmine/... **: packages to support the [Jasmine](https://jasmine.github.io/) test library. + +**jasmine/... **：[Jasmine](https://jasmine.github.io/) 测试库的支持包。 + **karma/... **: packages to support the [karma](https://www.npmjs.com/package/karma) test runner. **karma/... **：[karma](https://www.npmjs.com/package/karma) 测试运行器的支持包。 @@ -278,4 +281,5 @@ The browser downloads this bundle, not the original package files. See the [Deployment](guide/deployment) to learn more. + 参见[部署](guide/deployment)一章了解详情。 \ No newline at end of file diff --git a/aio/content/guide/observables-in-angular.md b/aio/content/guide/observables-in-angular.md index 858e9c8dc5..978a95151c 100644 --- a/aio/content/guide/observables-in-angular.md +++ b/aio/content/guide/observables-in-angular.md @@ -3,7 +3,9 @@ Angular makes use of observables as an interface to handle a variety of common asynchronous operations. For example: * The `EventEmitter` class extends `Observable`. + * The HTTP module uses observables to handle AJAX requests and responses. + * The Router and Forms modules use observables to listen for and respond to user-input events. ## Event emitter @@ -19,11 +21,15 @@ Here is the component definition: ## HTTP + Angular’s `HttpClient` returns observables from HTTP method calls. For instance, `http.get(‘/api’)` returns an observable. This provides several advantages over promise-based HTTP APIs: * Observables do not mutate the server response (as can occur through chained `.then()` calls on promises). Instead, you can use a series of operators to transform values as needed. + * HTTP requests are cancellable through the `unsubscribe()` method. + * Requests can be configured to get progress event updates. + * Failed requests can be retried easily. ## Async pipe @@ -36,6 +42,8 @@ The following example binds the `time` observable to the component's view. The o ## Router +## 路由器 (router) + [`Router.events`](https://angular.io/api/router/Router#events) provides events as observables. You can use the `filter()` operator from RxJS to look for events of interest, and subscribe to them in order to make decisions based on the sequence of events in the navigation process. Here's an example: @@ -46,6 +54,9 @@ The [ActivatedRoute](https://angular.io/api/router/ActivatedRoute) is an injecte ## Reactive forms +## 响应式表单 (reactive forms) + Reactive forms have properties that use observables to monitor form control values. The [`FormControl`](https://angular.io/api/forms/FormControl) properties `valueChanges` and `statusChanges` contain observables that raise change events. Subscribing to an observable form-control property is a way of triggering application logic within the component class. For example: + diff --git a/aio/content/guide/observables.md b/aio/content/guide/observables.md index abc4bd005a..204046dad4 100644 --- a/aio/content/guide/observables.md +++ b/aio/content/guide/observables.md @@ -39,6 +39,7 @@ An `Observable` instance begins publishing values only when someone subscribes t In order to show how subscribing works, we need to create a new observable. There is a constructor that you use to create new instances, but for illustration, we can use some static methods on the `Observable` class that create simple observables of frequently used types: * `Observable.of(...items)`—Returns an `Observable` instance that synchronously delivers the values provided as arguments. + * `Observable.from(iterable)`—Converts its argument to an `Observable` instance. This method is commonly used to convert an array to an observable.
    @@ -48,7 +49,9 @@ Here's an example of creating and subscribing to a simple observable, with an ob + title="Subscribe using observer"> + + Alternatively, the `subscribe()` method can accept callback function definitions in line, for `next`, `error`, and `complete` handlers. For example, the following `subscribe()` call is the same as the one that specifies the predefined observer: @@ -97,18 +100,24 @@ Notice that if you subscribe twice, there will be two separate streams, each emi
    + Multicasting observables take a bit more setup, but they can be useful for certain applications. Later we will look at tools that simplify the process of multicasting, allowing you to take any observable and make it multicasting. +
    ## Error handling +## 错误处理 + Because observables produce values asynchronously, try/catch will not effectively catch errors. Instead, you handle errors by specifying an `error` callback on the observer. Producing an error also causes the observable to clean up subscriptions and stop producing values. An observable can either produce values (calling the `next` callback), or it can complete, calling either the `complete` or `error` callback. + myObservable.subscribe({ next(num) { console.log('Next num: ' + num)}, error(err) { console.log('Received an errror: ' + err)} }); + Error handling (and specifically recovering from an error) is covered in more detail in a later section. diff --git a/aio/content/guide/pipes.md b/aio/content/guide/pipes.md index 6336394787..1bf7483b5d 100644 --- a/aio/content/guide/pipes.md +++ b/aio/content/guide/pipes.md @@ -32,8 +32,7 @@ Introducing Angular pipes, a way to write display-value transformations that you You can run the in Stackblitz and download the code from there. -试试在线例子。 - +运行来试用本页的代码。 ## Using pipes @@ -46,24 +45,18 @@ a human-friendly date. 管道把数据作为输入，然后转换它，给出期望的输出。 我们将把组件的`birthday`属性转换成对人类更友好的日期格式，来说明这一点： - - - Focus on the component's template. 重点看下组件的模板。 - - - Inside the interpolation expression, you flow the component's `birthday` value through the [pipe operator](guide/template-syntax#pipe) ( | ) to the [Date pipe](api/common/DatePipe) function on the right. All pipes work this way. @@ -82,11 +75,8 @@ They are all available for use in any template. Angular内置了一些管道，比如`DatePipe`、`UpperCasePipe`、`LowerCasePipe`、`CurrencyPipe`和`PercentPipe`。 它们全都可以直接用在任何模板中。 -
    - - Read more about these and many other built-in pipes in the [pipes topics](api?type=pipe) of the [API Reference](api); filter for entries that include the word "pipe". @@ -96,12 +86,8 @@ Angular doesn't have a `FilterPipe` or an `OrderByPipe` for reasons explained in Angular没有`FilterPipe`或`OrderByPipe`管道，原因在[后面的附录中](guide/pipes#no-filter-pipe)有解释。 -
    - - - ## Parameterizing a pipe ## 对管道进行参数化 @@ -120,13 +106,10 @@ After formatting the hero's April 15th birthday, it renders as **04/15/88< 我们将通过修改生日模板来给这个日期管道提供一个格式化参数。 当格式化完该英雄的4月15日生日之后，它应该被渲染成**04/15/88**。 - - - The parameter value can be any valid template expression, (see the [Template expressions](guide/template-syntax#template-expressions) section of the [Template Syntax](guide/template-syntax) page) @@ -141,13 +124,10 @@ to the component's `format` property. Here's the template for that component: 我们来写第二个组件，它把管道的格式参数*绑定*到该组件的`format`属性。这里是新组件的模板： - - - You also added a button to the template and bound its click event to the component's `toggleFormat()` method. That method toggles the component's `format` property between a short form (`'shortDate'`) and a longer form (`'fullDate'`). @@ -155,40 +135,31 @@ That method toggles the component's `format` property between a short form 我们还能在模板中添加一个按钮，并把它的点击事件绑定到组件的`toggleFormat()`方法。 此方法会在短日期格式(`'shortDate'`)和长日期格式(`'fullDate'`)之间切换组件的`format`属性。 - - - As you click the button, the displayed date alternates between "**04/15/1988**" and "**Friday, April 15, 1988**". 当我们点击按钮的时候，显示的日志会在“**04/15/1988**”和“**Friday, April 15, 1988**”之间切换。 -
    + Date Format Toggle +
    - -
    - - Read more about the `DatePipe` format options in the [Date Pipe](api/common/DatePipe) API Reference page. 要了解更多`DatePipes`的格式选项，请参阅[API文档](api/common/DatePipe)。 -
    - - ## Chaining pipes ## 链式管道 @@ -202,26 +173,19 @@ The birthday displays as **APR 15, 1988**. 下面这个例子中，我们把`birthday`链到`DatePipe`管道，然后又链到`UpperCasePipe`，这样我们就可以把生日显示成大写形式了。 比如下面的代码就会把生日显示成**APR 15, 1988**： - - - This example—which displays **FRIDAY, APRIL 15, 1988**—chains the same pipes as above, but passes in a parameter to `date` as well. 下面这个显示**FRIDAY, APRIL 15, 1988**的例子用同样的方式链接了这两个管道，而且同时还给`date`管道传进去一个参数。 - - - - ## Custom pipes ## 自定义管道 @@ -232,48 +196,42 @@ Here's a custom pipe named `ExponentialStrengthPipe` that can boost a hero's pow 我们还可以写自己的自定义管道。 下面就是一个名叫`ExponentialStrengthPipe`的管道，它可以放大英雄的能力： - - - This pipe definition reveals the following key points: 在这个管道的定义中体现了几个关键点： * A pipe is a class decorated with pipe metadata. - 管道是一个带有“管道元数据(pipe metadata)”装饰器的类。 + 管道是一个带有“管道元数据(pipe metadata)”装饰器的类。 * The pipe class implements the `PipeTransform` interface's `transform` method that accepts an input value followed by optional parameters and returns the transformed value. - 这个管道类实现了`PipeTransform`接口的`transform`方法，该方法接受一个输入值和一些可选参数，并返回转换后的值。 + 这个管道类实现了`PipeTransform`接口的`transform`方法，该方法接受一个输入值和一些可选参数，并返回转换后的值。 * There will be one additional argument to the `transform` method for each parameter passed to the pipe. Your pipe has one such parameter: the `exponent`. - 当每个输入值被传给`transform`方法时，还会带上另一个参数，比如我们这个管道中的`exponent`(放大指数)。 + 当每个输入值被传给`transform`方法时，还会带上另一个参数，比如我们这个管道中的`exponent`(放大指数)。 * To tell Angular that this is a pipe, you apply the `@Pipe` decorator, which you import from the core Angular library. - 我们通过`@Pipe`装饰器告诉Angular：这是一个管道。该装饰器是从Angular的`core`库中引入的。 + 我们通过`@Pipe`装饰器告诉Angular：这是一个管道。该装饰器是从Angular的`core`库中引入的。 * The `@Pipe` decorator allows you to define the pipe name that you'll use within template expressions. It must be a valid JavaScript identifier. Your pipe's name is `exponentialStrength`. - 这个`@Pipe`装饰器允许我们定义管道的名字，这个名字会被用在模板表达式中。它必须是一个有效的JavaScript标识符。 + 这个`@Pipe`装饰器允许我们定义管道的名字，这个名字会被用在模板表达式中。它必须是一个有效的JavaScript标识符。 比如，我们这个管道的名字是`exponentialStrength`。 -
    - - ## The *PipeTransform* interface ## *PipeTransform*接口 @@ -286,50 +244,44 @@ Technically, it's optional; Angular looks for and executes the `transform` metho `PipeTransform`*接口*中定义了它，并用它指导各种工具和编译器。 理论上说，它是可选的。Angular不会管它，而是直接查找并执行`transform`方法。 -
    Now you need a component to demonstrate the pipe. 现在，我们需要一个组件来演示这个管道。 - +
    + Power Booster +
    - - Note the following: 要注意的有两点： * You use your custom pipe the same way you use built-in pipes. - 我们使用自定义管道的方式和内置管道完全相同。 - + 我们使用自定义管道的方式和内置管道完全相同。 + * You must include your pipe in the `declarations` array of the `AppModule`. - 我们必须在`AppModule`的`declarations`数组中包含这个管道。 - + 我们必须在`AppModule`的`declarations`数组中包含这个管道。
    + Remember the declarations array -
    - - -
    别忘了`declarations`数组 +
    - - You must register custom pipes. If you don't, Angular reports an error. Angular CLI's generator registers the pipe automatically. @@ -337,11 +289,8 @@ Angular CLI's generator registers the pipe automatically. 我们必须手动注册自定义管道。如果忘了，Angular就会报告一个错误。 在前一个例子中我们没有把`DatePipe`列进去，这是因为Angular所有的内置管道都已经预注册过了。 -
    - - To probe the behavior in the , change the value and optional exponent in the template. @@ -358,23 +307,18 @@ your pipe and two-way data binding with `ngModel`. 仅仅升级模板来测试这个自定义管道其实没多大意思。 我们干脆把这个例子升级为“能力倍增计算器”，它可以把该管道和使用`ngModel`的双向数据绑定组合起来。 - - -
    + Power Boost Calculator +
    - - - {@a change-detection} - ## Pipes and change detection ## 管道与变更检测 @@ -397,24 +341,18 @@ its display of every hero in the `heroes` array. Here's the template: 我们下一个例子中的组件使用默认的、激进(昂贵)的变更检测策略来检测和更新`heroes`数组中的每个英雄。下面是它的模板： - - - The companion component class provides heroes, adds heroes into the array, and can reset the array. 和模板相伴的组件类可以提供英雄数组，能把新的英雄添加到数组中，还能重置英雄数组。 - - - You can add heroes and Angular updates the display when you do. If you click the `reset` button, Angular replaces `heroes` with a new array of the original heroes and updates the display. If you added the ability to remove or change a hero, Angular would detect those changes and update the display as well. @@ -431,24 +369,18 @@ Add a `FlyingHeroesPipe` to the `*ngFor` repeater that filters the list of heroe 我们来往`*ngFor`重复器中添加一个`FlyingHeroesPipe`管道，这个管道能过滤出所有会飞的英雄。 - - - Here's the `FlyingHeroesPipe` implementation, which follows the pattern for custom pipes described earlier. 下面是`FlyingHeroesPipe`的实现，它遵循了我们以前见过的那些写自定义管道的模式。 - - - Notice the odd behavior in the : when you add flying heroes, none of them are displayed under "Heroes who fly." @@ -464,13 +396,10 @@ Notice how a hero is added: 来看看我们是如何添加新英雄的： - - - You add the hero into the `heroes` array. The reference to the array hasn't changed. It's the same array. That's all Angular cares about. From its perspective, *same array, no change, no display update*. @@ -493,13 +422,12 @@ code with checkbox switches and additional displays to help you experience these 如果我们**替换了**这个数组，管道就会被执行，显示也更新了。 这个*飞行英雄*的例子用检查框和其它显示内容扩展了原有代码，来帮我们体验这些效果。 -
    + Flying Heroes +
    - - Replacing the array is an efficient way to signal Angular to update the display. When do you replace the array? When the data change. That's an easy rule to follow in *this* example @@ -525,8 +453,6 @@ For filtering flying heroes, consider an *impure pipe*. 为了过滤会飞的英雄，我们要使用*非纯(impure)管道*。 - - ## Pure and impure pipes ## 纯(pure)管道与非纯(impure)管道 @@ -540,13 +466,10 @@ impure like this: 默认情况下，管道都是纯的。我们以前见到的每个管道都是纯的。 通过把它的`pure`标志设置为`false`，我们可以制作一个非纯管道。我们可以像这样让`FlyingHeroesPipe`变成非纯的： - - - Before doing that, understand the difference between pure and impure, starting with a pure pipe. 在继续往下走之前，我们先理解一下*纯*和*非纯*之间的区别，从*纯*管道开始。 @@ -583,14 +506,11 @@ When you can't, you *can* use the impure pipe. 因此，如果我们要和变更检测策略打交道，就会更喜欢用纯管道。 如果不能，我们就*可以*转回到非纯管道。 -
    - - Or you might not use a pipe at all. It may be better to pursue the pipe's purpose with a property of the component, -a point that's discussed laterin this page. +a point that's discussed later in this page. 或者我们也可以完全不用管道。 有时候，使用组件的属性能比用管道更好的达到目的，这一点我们等后面会再提起。 @@ -598,8 +518,6 @@ a point that's discussed laterin this page.
    - -

    Impure pipes

    ### 非纯管道 @@ -616,13 +534,11 @@ An expensive, long-running pipe could destroy the user experience. 要在脑子里绷着这根弦，我们必须小心翼翼的实现非纯管道。 一个昂贵、迟钝的管道将摧毁用户体验。 - {@a impure-flying-heroes} -

    An impure FlyingHeroesPipe

    -### 非纯版本的*FlyingHeroesPipe* +

    非纯管道 FlyingHeroesPipe

    A flip of the switch turns the `FlyingHeroesPipe` into a `FlyingHeroesImpurePipe`. The complete implementation is as follows: @@ -630,7 +546,6 @@ The complete implementation is as follows: 我们把`FlyingHeroesPipe`换成了`FlyingHeroesImpurePipe`。 下面是完整的实现： - @@ -643,8 +558,6 @@ The complete implementation is as follows: - - You inherit from `FlyingHeroesPipe` to prove the point that nothing changed internally. The only difference is the `pure` flag in the pipe metadata. @@ -655,25 +568,18 @@ This is a good candidate for an impure pipe because the `transform` function is 这是一个很好地非纯管道候选者，因为它的`transform`函数又小又快。 - - - You can derive a `FlyingHeroesImpureComponent` from `FlyingHeroesComponent`. 我们可以从`FlyingHeroesComponent`派生出一个`FlyingHeroesImpureComponent`。 - - - - The only substantive change is the pipe in the template. You can confirm in the that the _flying heroes_ display updates as you add heroes, even when you mutate the `heroes` array. @@ -681,16 +587,11 @@ display updates as you add heroes, even when you mutate the `heroes` array. 唯一的重大改动就是管道。 我们可以在中确认，当我们输入新的英雄甚至修改#[code heroes]数组时，这个#[i 会飞的英雄]的显示也跟着更新了。 - {@a async-pipe} +

    The impure AsyncPipe

    - -

    - 非纯 AsyncPipe -

    - - +

    非纯管道 AsyncPipe

    The Angular `AsyncPipe` is an interesting example of an impure pipe. The `AsyncPipe` accepts a `Promise` or `Observable` as input @@ -711,13 +612,10 @@ This next example binds an `Observable` of message strings 在下面例子中，我们使用该`async`管道把一个消息字符串(`message$`)的`Observable`绑定到视图中。 - - - The Async pipe saves boilerplate in the component code. The component doesn't have to subscribe to the async data source, extract the resolved values and expose them for binding, @@ -748,51 +646,44 @@ The code uses the [Angular http](guide/http) client to retrieve data: 这个管道只有当所请求的URL发生变化时才会向服务器发起请求。它会缓存服务器的响应。 代码如下，它使用[Angular http](guide/http)客户端来接收数据 - - - Now demonstrate it in a harness component whose template defines two bindings to this pipe, both requesting the heroes from the `heroes.json` file. 接下来我们用一个测试台组件演示一下它，该组件的模板中定义了两个使用到此管道的绑定，他们都从`heroes.json`文件中取得英雄数据。 - - - The component renders as the following: 组件渲染起来是这样的： -
    + Hero List +
    - - A breakpoint on the pipe's request for data shows the following: 这个管道上的断点请求数据的过程显示： * Each binding gets its own pipe instance. - 每个绑定都有它自己的管道实例。 - + 每个绑定都有它自己的管道实例。 + * Each pipe instance caches its own URL and data. - 每个管道实例都缓存了它自己的URL和数据。 - + 每个管道实例都缓存了它自己的URL和数据。 + * Each pipe instance only calls the server once. - 每个管道实例都只调用一次服务器。 + 每个管道实例都只调用一次服务器。

    JsonPipe

    @@ -802,40 +693,29 @@ It displays the same hero data in JSON format by chaining through to the built-i 第二个绑定除了用到`FetchPipe`之外还链接了更多管道。 我们把获取数据的结果同时显示在第一个绑定和第二个绑定中。第二个绑定中，我们通过链接到一个内置管道`JsonPipe`把它转成了JSON格式。 -
    - -
    + Debugging with the json pipe -
    - - -
    借助json管道进行调试 +
    - - The [JsonPipe](api/common/JsonPipe) provides an easy way to diagnosis a mysteriously failing data binding or inspect an object for future binding. [JsonPipe](api/common/JsonPipe)为你诊断数据绑定的某些神秘错误或为做进一步绑定而探查数据时，提供了一个简单途径。 -
    - - {@a pure-pipe-pure-fn} -

    Pure pipes and pure functions

    -### 纯管道与纯函数 +

    纯管道与纯函数

    A pure pipe uses pure functions. Pure functions process inputs and return values without detectable side effects. @@ -861,8 +741,6 @@ Otherwise, you'll see many console errors regarding expressions that changed aft 但是一个*纯管道*必须总是用*纯函数*实现。忽略这个警告将导致失败并带来一大堆这样的控制台错误：表达式在被检查后被变更。 - - ## Next steps ## 下一步 @@ -880,11 +758,8 @@ Try writing a custom pipe and perhaps contributing it to the community. 要浏览Angular的所有内置管道，请到[API参考手册](api?type=pipe)。 学着写写自定义管道，并贡献给开发社区。 - {@a no-filter-pipe} - - ## Appendix: No *FilterPipe* or *OrderByPipe* ## 附录：没有*FilterPipe*或者*OrderByPipe* @@ -922,15 +797,13 @@ The list might be sorted by hero `name` and `planet` of origin properties in the 虽然不是很明显，但代码最小化方面也存在风险。想象一个用于英雄列表的排序管道。我们可能根据英雄原始属性中的`name`和`planet`进行排序，就像这样： - + <!-- NOT REAL CODE! --> <div *ngFor="let hero of heroes | orderBy:'name,planet'"></div> - - You identify the sort fields by text strings, expecting the pipe to reference a property value by indexing (such as `hero['name']`). Unfortunately, aggressive minification manipulates the `Hero` property names so that `Hero.name` and `Hero.planet` @@ -962,4 +835,5 @@ Angular开发组和一些有经验的Angular开发者强烈建议你：把你的 If these performance and minification considerations don't apply to you, you can always create your own such pipes (similar to the [FlyingHeroesPipe](guide/pipes#impure-flying-heroes)) or find them in the community. -如果你不需要顾虑这些性能和最小化问题，也可以创建自己的管道来实现这些功能(参考[FlyingHeroesPipe](guide/pipes#impure-flying-heroes)中的写法)或到社区中去找找。 + +如果你不需要顾虑这些性能和最小化问题，也可以创建自己的管道来实现这些功能(参考[FlyingHeroesPipe](guide/pipes#impure-flying-heroes)中的写法)或到社区中去找找。 \ No newline at end of file diff --git a/aio/content/guide/practical-observable-usage.md b/aio/content/guide/practical-observable-usage.md index 9c0f4ba4ee..58ee8eb26f 100644 --- a/aio/content/guide/practical-observable-usage.md +++ b/aio/content/guide/practical-observable-usage.md @@ -7,9 +7,13 @@ Here are some examples of domains in which observables are particularly useful. Observables can simplify the implementation of type-ahead suggestions. Typically, a type-ahead has to do a series of separate tasks: * Listen for data from an input. + * Trim the value (remove whitespace) and make sure it’s a minimum length. + * Debounce (so as not to send off API requests for every keystroke, but instead wait for a break in keystrokes). + * Don’t send a request if the value stays the same (rapidly hit a character, then backspace, for instance). + * Cancel ongoing AJAX requests if their results will be invalidated by the updated results. Writing this in full JavaScript can be quite involved. With observables, you can use a simple series of RxJS operators: @@ -21,3 +25,4 @@ Writing this in full JavaScript can be quite involved. With observables, you can Exponential backoff is a technique in which you retry an API after failure, making the time in between retries longer after each consecutive failure, with a maximum number of retries after which the request is considered to have failed. This can be quite complex to implement with promises and other methods of tracking AJAX calls. With observables, it is very easy: + diff --git a/aio/content/guide/providers.md b/aio/content/guide/providers.md index 10ebcc7940..bbf7478ec4 100644 --- a/aio/content/guide/providers.md +++ b/aio/content/guide/providers.md @@ -1,7 +1,11 @@ # Providers #### Prerequisites: + +#### 前提条件： + * A basic understanding of [Bootstrapping](guide/bootstrapping). + * Familiarity with [Frequently Used Modules](guide/frequent-ngmodules). For the final sample app using the provider that this page describes, @@ -10,6 +14,7 @@ see the .
    ## Create a service + You can provide services to your app by using the `providers` array in an NgModule. Consider the default app generated by the CLI. In order to add a user service to it, you can generate one by entering the following command in the terminal window: @@ -23,14 +28,13 @@ app's injector. Update `app.module.ts` by importing it with your other import st of the file and adding it to the `providers` array: - + ## Provider scope When you add a service provider to the `providers` array of the root module, it’s available throughout the app. Additionally, when you import a module that has providers, those providers are also available to all the classes in the app as long they have the lookup token. For example, if you import the `HttpClientModule` into your `AppModule`, its providers are then available to the entire app and you can make HTTP requests from anywhere in your app. - ## Limiting provider scope by lazy loading modules In the basic CLI generated app, modules are eagerly loaded which means that they are all loaded when the app launches. Angular uses an injector system to make things available between modules. In an eagerly loaded app, the root application injector makes all of the providers in all of the modules available throughout the app. @@ -45,7 +49,6 @@ Any component created within a lazy loaded module’s context, such as by router Though you can provide services by lazy loading modules, not all services can be lazy loaded. For instance, some modules only work in the root module, such as the Router. The Router works with the global location object in the browser. - ## Limiting provider scope with components Another way to limit provider scope is by adding the service you want to limit to the component’s @@ -55,8 +58,8 @@ Providing a service in the component limits the service only to that component ( the same module can’t access it.) - + ## Providing services in modules vs. components @@ -67,12 +70,14 @@ The router works at the root level so if you put providers in a component, even Register a provider with a component when you must limit a service instance to a component and its component tree, that is, its child components. For example, a user editing component, `UserEditorComponent`, that needs a private copy of a caching `UserService` should register the `UserService` with the `UserEditorComponent`. Then each new instance of the `UserEditorComponent` gets its own cached service instance. -
    ## More on NgModules You may also be interested in: + * [Singleton Services](guide/singleton-services), which elaborates on the concepts covered on this page. + * [Lazy Loading Modules](guide/lazy-loading-ngmodules). + * [NgModule FAQ](guide/ngmodule-faq). diff --git a/aio/content/guide/quickstart.md b/aio/content/guide/quickstart.md index 8fe6f3ac43..2e6b7ad7aa 100644 --- a/aio/content/guide/quickstart.md +++ b/aio/content/guide/quickstart.md @@ -30,31 +30,24 @@ And you can also 下载这个例子。

    + Step 1. Set up the Development Environment -

    - - -

    步骤1. 设置开发环境 +

    - - You need to set up your development environment before you can do anything. 在开始工作之前，我们必须设置好开发环境。 - + Install **[Node.js® and npm](https://nodejs.org/en/download/)** if they are not already on your machine. -如果你的机器上还没有**[Node.js®和npm](https://nodejs.org/en/download/)**，请先安装它们。 - +如果你的电脑里没有Node.js®和npm，请安装**[它们](https://nodejs.org/en/download/)**。
    - - **Verify that you are running at least node `6.9.x` and npm `3.x.x`** by running `node -v` and `npm -v` in a terminal/console window. Older versions produce errors, but newer versions are fine. @@ -63,90 +56,69 @@ Older versions produce errors, but newer versions are fine. **来验证一下你正在运行 node `6.9.x` 和 npm `3.x.x` 以上的版本。** 更老的版本可能会出现错误，更新的版本则没问题。 -
    - - Then **install the [Angular CLI](https://github.com/angular/angular-cli)** globally. 然后全局安装 **[Angular CLI](https://github.com/angular/angular-cli)** 。 - + npm install -g @angular/cli - - -

    + Step 2. Create a new project -

    - - -

    步骤2. 创建新项目 +

    - - Open a terminal window. 打开终端窗口。 - Generate a new project and skeleton application by running the following commands: 运行下列命令来生成一个新项目以及应用的骨架代码： - + ng new my-app - -
    - - Patience, please. It takes time to set up a new project; most of it is spent installing npm packages. 请耐心等待。 创建新项目需要花费很多时间，大多数时候都是在安装那些npm包。 -
    - - -

    + Step 3: Serve the application -

    -

    步骤3. 启动开发服务器 -

    + Go to the project directory and launch the server. 进入项目目录，并启动服务器。 - + cd my-app ng serve --open + - - The `ng serve` command launches the server, watches your files, and rebuilds the app as you make changes to those files. @@ -162,24 +134,19 @@ Your app greets you with a message: 本应用会用一条消息来跟你打招呼：
    + The app works! +
    - - -

    + Step 4: Edit your first Angular component -

    - - -

    步骤4. 编辑我们的第一个Angular组件 +

    - - The CLI created the first Angular component for you. This is the _root component_ and it is named `app-root`. You can find it in `./src/app/app.component.ts`. @@ -194,8 +161,6 @@ Open the component file and change the `title` property from _Welcome to app!!_ - - The browser reloads automatically with the revised title. That's nice, but it could look better. 浏览器会自动刷新，而我们会看到修改之后的标题。不错，不过它还可以更好看一点。 @@ -206,20 +171,16 @@ Open `src/app/app.component.css` and give the component some style. - -
    + Output of QuickStart app +
    - - Looking good! 漂亮！ - - ## What's next? ## 接下来呢？ @@ -237,8 +198,6 @@ Or you can stick around a bit longer to learn about the files in your brand new 或者，你也可以稍等一会儿，学学在这个新项目中的文件都是干什么用的。 - - ## Project file review ## 项目文件概览 @@ -262,8 +221,6 @@ Some of the generated files might be unfamiliar to you. 有些生成的文件你可能觉得陌生。接下来我们就讲讲它们。 - - ### The `src` folder ### `src`文件夹 @@ -276,71 +233,110 @@ Any files outside of this folder are meant to support building your app. 所有的Angular组件、模板、样式、图片以及你的应用所需的任何东西都在那里。 这个文件夹之外的文件都是为构建应用提供支持用的。 -
    +
    src
    +
    +
    app
    +
    +
    app.component.css
    +
    app.component.html
    +
    app.component.spec.ts
    +
    app.component.ts
    +
    app.module.ts
    +
    +
    assets
    +
    +
    .gitkeep
    +
    +
    environments
    +
    +
    environment.prod.ts
    +
    environment.ts
    +
    +
    favicon.ico
    +
    index.html
    +
    main.ts
    +
    polyfills.ts
    +
    styles.css
    +
    test.ts
    +
    tsconfig.app.json
    +
    tsconfig.spec.json
    +
    +
    - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + File - + 文件 - + + Purpose - + 用途 - +
    `app/app.component.{ts,html,css,spec.ts}` Defines the `AppComponent` along with an HTML template, CSS stylesheet, and a unit test. @@ -349,47 +345,60 @@ Any files outside of this folder are meant to support building your app. 使用HTML模板、CSS样式和单元测试定义`AppComponent`组件。 它是**根**组件，随着应用的成长它会成为一棵组件树的根节点。 - +
    `app/app.module.ts` Defines `AppModule`, the [root module](guide/bootstrapping "AppModule: the root module") that tells Angular how to assemble the application. Right now it declares only the `AppComponent`. Soon there will be more components to declare. - 定义`AppModule`，这个[根模块](guide/bootstrapping "AppModule: 根模块")会告诉Angular如何组装该应用。 + 定义`AppModule`，[根模块](guide/bootstrapping "AppModule: 根模块")为 Angular 描述如何组装应用。 目前，它只声明了`AppComponent`。 - 稍后它还会声明更多组件。 - + 不久，它将声明更多组件。 +
    `assets/*` A folder where you can put images and anything else to be copied wholesale when you build your application. 这个文件夹下你可以放图片等任何东西，在构建应用时，它们全都会拷贝到发布包中。 +
    `environments/*` This folder contains one file for each of your destination environments, @@ -407,13 +416,17 @@ Any files outside of this folder are meant to support building your app. 所有这些，CLI都替你考虑到了。
    `favicon.ico` Every site wants to look good on the bookmark bar. @@ -421,14 +434,19 @@ Any files outside of this folder are meant to support building your app. 每个网站都希望自己在书签栏中能好看一点。 请把它换成你自己的图标。 +
    `index.html` The main HTML page that is served when someone visits your site. @@ -439,15 +457,19 @@ Any files outside of this folder are meant to support building your app. 这是别人访问你的网站是看到的主页面的HTML文件。 大多数情况下你都不用编辑它。 在构建应用时，CLI会自动把所有`js`和`css`文件添加进去，所以你不必在这里手动添加任何 `