` element will be the attribute **host**. - 这个例子中，`AppComponent`是用来测试`HighlightDirective`的一个壳。 - 我们来给它一个新的模板，把这个指令作为属性应用到一个段落(`p`)元素上。 + 要使用这个新的`HighlightDirective`，创建一个模板，把这个指令作为属性应用到一个段落(`p`)元素上。 用Angular的话说，`
`元素就是这个属性型指令的**宿主**。 p | Put the template in its own @@ -275,23 +221,14 @@ p +makeExample('attribute-directives/ts/app/app.component.1.html',null,'app/app.component.html')(format=".") :marked Now reference this template in the `AppComponent`: - A separate template file is clearly overkill for a 2-line template. - Hang in there; we're going to expand it later. - Meanwhile, we'll revise the `AppComponent` to reference this template. - - 对于一个只有两行的模板来说，使用一个独立的模板文件确实有点过分了。 - 先别管它，我们后面很快就会扩展它。 - 同时，要修改`AppComponent`，使其引用这个模板。 + 现在，引用`AppComponent`的模板： +makeExample('attribute-directives/ts/app/app.component.ts',null,'app/app.component.ts') :marked Next, add an `import` statement to fetch the `Highlight` directive and add that class to the `declarations` NgModule metadata. This way Angular recognizes the directive when it encounters `myHighlight` in the template. - We'll add an `import` statement to fetch the 'Highlight' directive and, - added that class to the `declarations` NgModule metadata so that Angular - will recognize our directive when it encounters `myHighlight` in the template. - 我们添加了一个`import`语句来获得'Highlight'指令类，并把这个类添加到`AppComponent`组件的`declarations`数组中。 + 接下来，添加了一个`import`语句来获得'Highlight'指令类，并把这个类添加到`AppComponent`组件的`declarations`数组中。 这样，当Angular在模板中遇到`myHighlight`时，就能认出这是指令了。 +makeExample('attribute-directives/ts/app/app.module.ts',null,'app/app.module.ts') @@ -299,8 +236,6 @@ p :marked Now when the app runs, the `myHighlight` directive highlights the paragraph text. - We run the app and see that our directive highlights the paragraph text. - 运行应用，就会看到我们的指令确实高亮了段落中的文本。 figure.image-display @@ -308,7 +243,7 @@ figure.image-display .l-sub-section :marked ### Your directive isn't working? - ### Your directive isn't working? + ### 你的指令没生效？ Did you remember to add the directive to the the `declarations` attribute of `@NgModule`? It is easy to forget! @@ -329,27 +264,16 @@ figure.image-display in the array, Angular knows to check the import statements and from there, to go to `highlight.directive.ts` to find out what `myHighlight` does. - Angular detects that we're trying to bind to *something* but it doesn't know what. - We have to tell it by listing `HighlightDirective` in the `declarations` metadata array. - - 这是因为Angular检测到我们正在尝试绑定到*某些东西*，但它不认识。 - 我们必需把`HighlightDirective`列在元数据的`declarations`数组中，来告诉它有这样一个指令。 + Angular检测到你正在尝试绑定到*某些东西*，但它不认识。所以它在`declarations`元数据数组中查找。 + 把`HighlightDirective`列在元数据的这个数组中，Angular就会检查对应的导入语句，从而找到`highlight.directive.ts`，并了解`myHightlight`的功能。 :marked To summarize, Angular found the `myHighlight` attribute on the `
` element. It created an instance of the `HighlightDirective` class, injecting a reference to the element into the constructor where the `
` element's background style is set to yellow. - Let's recap what happened. - 我们来概括一下发生了什么。 - - Angular found the `myHighlight` attribute on the `
` element. It created - an instance of the `HighlightDirective` class, - injecting a reference to the element into the constructor - where we set the `
` element's background style to yellow. - - Angular在`
`元素上发现了一个`myHighlight`属性。 + 总结：Angular在`
`元素上发现了一个`myHighlight`属性。 然后它创建了一个`HighlightDirective`类的实例，并把所在元素的引用注入到了指令的构造函数中。 在构造函数中，我们把`
`元素的背景设置为了黄色。 @@ -357,76 +281,60 @@ figure.image-display a#respond-to-user :marked ## Respond to user-initiated events - ## Respond to user action - ## 响应用户的操作 + ## 响应用户引发的事件 Currently, `myHighlight` simply sets an element color. The directive should set the color when the user hovers over an element. + + 当前，`myHighlight`只是简单的设置元素的颜色。 + 这个指令应该在用户鼠标悬浮一个元素时，设置它的颜色。 This requires two things: - 1. detecting when the user hovers into and out of the element. - 2. responding to those actions by setting and clearing the highlight color. - - To do this, you can apply the `@HostListener` !{_decorator} to methods which are called when an event is raised. - We are not satisfied to simply set an element color. - Our directive should set the color in response to a user action. - Specifically, we want to set the color when the user hovers over an element. - - 我们不能满足于设置元素的颜色。 - 我们的指令要响应用户的操作而设置颜色。 - 确切的说，希望在用户的鼠标滑过当前元素时设置颜色。 - - We'll need to 我们需要： + 1. detecting when the user hovers into and out of the element. - 1. detect when the user hovers into and out of the element, 1. 检测用户的鼠标啥时候进入和离开这个元素。 - 2. respond to those actions by setting and clearing the highlight color, respectively. - 2. 通过设置和清除高亮色来响应这些操作。 - We apply the `@HostListener` !{_decorator} to methods which are called when an event is raised. + 2. responding to those actions by setting and clearing the highlight color. + + 2. 通过设置和清除高亮色来响应这些操作。 + + To do this, you can apply the `@HostListener` !{_decorator} to methods which are called when an event is raised. - 从事件检测开始吧。 把`host`属性加入指令的元数据中，并给它一个配置对象，用来指定两个鼠标事件，并在它们被触发时，调用指令中的方法： +makeExample('attribute-directives/ts/app/highlight.directive.2.ts','host')(format=".") .l-sub-section - :marked The `@HostListener` !{_decorator} refers to the DOM element that hosts an attribute directive, the `
` in this case. - It is possible to attach event listeners by manipulating the host DOM element directly, but - The `@HostListener` !{_decorator} refers to the DOM element that hosts our attribute directive, the `
` in our case. - `@HostListener`装饰器引用的是我们这个属性型指令的宿主元素，在这个例子中就是`
`。 - - We could have attached event listeners by manipulating the host DOM element directly, but + + It is possible to attach event listeners by manipulating the host DOM element directly, but + + 可以通过直接操纵DOM元素的方式给宿主DOM元素挂上一个事件监听器，但是 + there are at least three problems with such an approach: + + 但这种方法至少有三个问题： 1. You have to write the listeners correctly. + + 1. 必须正确的书写事件监听器。 + 1. The code must *detach* the listener when the directive is destroyed to avoid memory leaks. + + 1. 当指令被销毁的时候，必须*摘掉*事件监听器，否则就会导致内存泄露。 + 1. Talking to DOM API directly isn't a best practice. - - 可以通过直接操纵DOM元素的方式给宿主DOM元素挂上一个事件监听器。 - 但这种方法至少有三个问题： - 1. We have to write the listeners correctly. - 1. 必须正确的书写事件监听器。 - 1. We must *detach* our listener when the directive is destroyed to avoid memory leaks. - 1. 当指令被销毁的时候，必须*摘掉*事件监听器，否则就会导致内存泄露。 - 1. We'd be talking to DOM API directly which, we learned, is something to avoid. - 1. 必须直接和DOM API打交道，但正如我们学过的那样，应该避免这样做。 - - Let's roll with the `@HostListener` !{_decorator}. - - 我们还是围绕`@HostListener`装饰器来吧。 + 1. 必须直接和DOM API打交道，但正如我们学过的那样，应该避免这样做。 :marked Now implement the two mouse event handlers: - Now we implement the two mouse event handlers: 现在，我们实现那两个鼠标事件处理器： @@ -440,7 +348,6 @@ a#respond-to-user 我们要修改构造函数，来把`ElementRef.nativeElement`存进这个私有变量。 +makeExample('attribute-directives/ts/app/highlight.directive.2.ts','ctor')(format=".") - :marked Here's the updated directive: @@ -461,20 +368,17 @@ figure.image-display a#bindings :marked ## Pass values into the directive using data binding - - ## Configure the directive with binding - ## 通过绑定来配置指令 + + ## 通过绑定来传递值到指令中 Currently the highlight color is hard-coded within the directive. That's inflexible. A better practice is to set the color externally with a binding as follows: - We should set the color externally with a binding like this: 现在的高亮颜色是在指令中硬编码进去的。这样没有弹性。 我们应该通过绑定从外部设置这个颜色。就像这样： +makeExample('attribute-directives/ts/app/app.component.html','pHost') :marked You can extend the directive class with a bindable **input** `highlightColor` property and use it to highlight text. - We'll extend our directive class with a bindable **input** `highlightColor` property and use it when we highlight text. 我们将给指令类增加一个可绑定**输入**属性`highlightColor`，当需要高亮文本的时候，就用它。 @@ -499,10 +403,6 @@ a#input property binding under the `myHighlight` alias. Without this input metadata Angular rejects the binding. See the [appendix](#why-input) below for more information. - `@Input` adds metadata to the class that makes the `highlightColor` property available for - property binding under the `myHighlight` alias. - We must add this input metadata or Angular will reject the binding. - See the [appendix](#why-input) below to learn why. `@Input`把元数据添加到了类上，这让`highlightColor`能被以`myHighlight`为别名进行绑定。 必须添加这个input元数据，否则Angular会拒绝绑定。 @@ -510,113 +410,72 @@ a#input .l-sub-section :marked ### @Input(_alias_) - Currently, the code **aliases** the `highlightColor` property with the attribute name by - ### @Input(_alias_) + ### @Input(_别名_) - The developer who uses this directive expects to bind to the attribute name, `myHighlight`. - The directive property name is `highlightColor`. That's a disconnect. - 使用这个指令的开发人员会期望绑定到属性名`myHighlight`上， - 而指令中的属性名是`highlightColor`。两者联系不起来。 - - We could resolve the discrepancy by renaming the property to `myHighlight` and define it as follows: - - 我们可以通过把属性名改为`myHighlight`来解决这个矛盾，就像这样： - - +makeExcerpt('app/highlight.directive.ts', 'highlight', '') - :marked - Maybe we don't want that property name inside the directive perhaps because it - doesn't express our intention well. - We can **alias** the `highlightColor` property with the attribute name by + Currently, the code **aliases** the `highlightColor` property with the attribute name by passing `myHighlight` into the `@Input` #{_decorator}: - 但我们可能在指令中不想要那样一个属性名，因为它不能很好的表示我们的意图。 - 可以通过把`myHighlight`传给`@Input`#{_decoratorCn}来把这个属性名作为`highlightColor`属性的别名。 + 当前，代码通过将`myHighlight`传递到`@Input`装饰器，把`myHighlight`属性**别名**到属性名字上。 +makeExcerpt('app/highlight.directive.ts', 'color', '') :marked The code binds to the attribute name, `myHighlight`, but the the directive property name is `highlightColor`. That's a disconnect. + + 代码绑定到`myHighlight`属性名，但是指令属性名为`highlightColor`。这是一个断点。 You can resolve the discrepancy by renaming the property to `myHighlight` and define it as follows: + + 你可以通过重命名属性名到`myHighlight`来移除这个区别，像这样： +makeExcerpt('app/highlight.directive.ts', 'highlight', '') - :marked Now that you're getting the highlight color as an input, modify the `onMouseEnter()` method to use it instead of the hard-coded color name and define red as the default color. - Now that we're getting the highlight color as an input, we modify the `onMouseEnter()` method to use - it instead of the hard-coded color name. - We also define red as the default color to fallback on in case - the user neglects to bind with a color. - 现在，通过输入型属性得到了高亮的颜色，然后修改`onMouseEnter()`来使用它代替硬编码的那个颜色名。 我们还把红色定义为默认颜色，以便在用户忘了绑定颜色时作为备用。 +makeExcerpt('attribute-directives/ts/app/highlight.directive.ts', 'mouse-enter', '') - :marked To let users pick the highlight color and bind their choice to the directive, update `app.component.html` as follows: - Now we'll update our `AppComponent` template to let - users pick the highlight color and bind their choice to our directive. - - 我们这就更新`AppComponent`的模板，来让用户选择一个高亮颜色，并把选择结果绑定到指令上。 - - Here is the updated template: - - 这里是更新后的模板： + 更新`AppComponent`的模板，来让用户选择一个高亮颜色，并把选择结果绑定到指令上： +makeExcerpt('attribute-directives/ts/app/app.component.html', 'v2', '') .l-sub-section :marked ### Where is the templated *color* property? + + ### 模板的*color*属性在哪里？ You may notice that the radio button click handlers in the template set a `color` property and the code is binding that `color` to the directive. However, you never defined a color property for the host `AppComponent`. Yet this code works. Where is the template `color` value going? + + 你可能注意到，模板中的单选按钮的点击事件处理器设置了一个`color`属性，而且把`color`绑定到指令上。 + 但是，你从未在这个宿主`AppComponent`中定义`color`属性，代码仍然工作正常。模板的`color`值去哪儿了？ + Browser debugging reveals that Angular dynamically added a `color` property - ### 模板的*color*属性在哪里？ - - The eagle-eyed may notice that the radio button click handlers in the template set a `color` property - and we are binding that `color` to the directive. - We should expect to find a `color` on the host `AppComponent`. - - 眼尖的读者可能发现了，模板中的单选按钮的点击事件处理器设置了一个`color`属性，而且把`color`绑定到指令上。 - 我们会期望在这个宿主`AppComponent`上发现一个`color`属性。 - - **We never defined a color property for the host *AppComponent***! - And yet this code works. Where is the template `color` value going? - - **但我们从来没有在宿主`AppComponent`上定义过color属性**！ - 不过这段代码却能正常工作。模板中的`color`值哪去了？ - - Browser debugging reveals that Angular dynamically added a `color` property to the runtime instance of the `AppComponent`. + + 在浏览器中调试就会发现，Angular在`AppComponent`的运行期实例上添加了一个`color`属性。 This is *convenient* behavior but it is also *implicit* behavior that could be confusing. For clarity, consider adding the `color` property to the `AppComponent`. - - - 在浏览器中调试就会发现，Angular在`AppComponent`的运行期实例上添加了一个`color`属性。 - - This is *convenient* behavior but it is also *implicit* behavior that could be confusing. - While it's cool that this technique works, we recommend adding the `color` property to the `AppComponent`. - 这是一个*很便利的*行为，但它也是*隐式的*行为，这容易让人困惑。 虽然这样也可行，但我们建议你还是要把`color`属性加到`AppComponent`中。 :marked Here is the second version of the directive in action. - Here is our second version of the directive in action. - + 下面是指令操作演示的第二版。 figure.image-display img(src="/resources/images/devguide/attribute-directives/highlight-directive-v2-anim.gif" alt="Highlight v.2") @@ -625,41 +484,31 @@ figure.image-display a#second-property :marked ## Bind to a second property + + ## 绑定到第二个属性 This example directive only has a single customizable property. A real app often needs more. + + 本例的指令只有一个可定制属性，真实的引用通常需要更多。 Let's allow the template developer to set the default color—the color that prevails until the user picks a highlight color. To do this, first add a second **input** property to `HighlightDirective` called `defaultColor`: - ## 绑定到第二个属性 - Our directive only has a single, customizable property. What if we had ***two properties***? - - 我们的指令只有一个可定制属性，如果有***两个***呢？ - - Let's allow the template developer to set the default color, the color that prevails until the user picks a highlight color. - We'll add a second **input** property to `HighlightDirective` called `defaultColor`: - - 我们要让模板开发者设置一个默认颜色，直到用户选择了一个高亮颜色才失效。 + + 要让模板开发者设置一个默认颜色，直到用户选择了一个高亮颜色才失效。 给`HighlightDirective`添加第二个**输入型**属性`defaultColor`： +makeExample('attribute-directives/ts/app/highlight.directive.ts', 'defaultColor')(format=".") :marked The `defaultColor` property has a setter that overrides the hard-coded default color, "red". You don't need a getter. + + `defaultColor`属性是一个setter函数，它代替了硬编码的默认颜色“red”。不需要getter函数。 How do you bind to it? The app is already using `myHighlight` attribute name as a binding target. + + 该如何绑定到它？别忘了已经把`myHighlight`属性名用作绑定目标了。 Remember that a *component is a directive, too*. You can add as many component property bindings as you need by stringing them along in the template as in this example that sets the `a`, `b`, `c` properties to the string literals 'a', 'b', and 'c'. - We don't need a getter. - - `defaultColor`属性是一个setter函数，它代替了硬编码的默认颜色“red”。不需要getter函数。 - - How do we bind to it? We already "burned" the `myHighlight` attribute name as a binding target. - - 该如何绑定到它？别忘了已经把`myHighlight`属性名用作绑定目标了。 - - Remember that a *component is a directive too*. - We can add as many component property bindings as we need by stringing them along in the template - as in this example that sets the `a`, `b`, `c` properties to the string literals 'a', 'b', and 'c'. 记住，*组件也是指令*。 只要需要，就可以通过把它们依次串在模板中来为组件添加多个属性绑定。 @@ -668,7 +517,6 @@ code-example(format="." ). <my-component [a]="'a'" [b]="'b'" [c]="'c'"><my-component> :marked The same holds true for an attribute directive. - We do the same thing with an attribute directive. 在属性型指令中也可以这样做。 +makeExample('attribute-directives/ts/app/app.component.html', 'defaultColor')(format=".") @@ -676,13 +524,9 @@ code-example(format="." ). Here the code is binding the user's color choice to the `myHighlight` attribute as before. It is *also* binding the literal string, 'violet', to the `defaultColor`. - - Here we're binding the user's color choice to the `myHighlight` attribute as we did before. - We're *also* binding the literal string, 'violet', to the `defaultColor`. - 这里，我们像以前一样把用户选择的颜色绑定到了`myHighlight`上。 我们*还*把字符串字面量'violet'绑定到了`defaultColor`上。 - + Here is the final version of the directive in action. 下面就是该指令最终版的操作演示。 @@ -692,23 +536,19 @@ figure.image-display .l-main-section :marked ## Summary - This page covered how to: - - [Build a simple **attribute directive** to attach behavior to an HTML element](#write-directive). - - [Use that directive in a template](#apply-directive). - - [Respond to **events** to change behavior based on an event](#respond-to-user). - - [Use **binding** to pass values to the attribute directive](#bindings). + ## 总结 - We now know how to - - 现在，我们知道了该如何： - - [build a simple **attribute directive** to attach behavior to an HTML element](#write-directive), + + This page covered how to: + 本章介绍了如何： + - [Build a simple **attribute directive** to attach behavior to an HTML element](#write-directive). - [构建一个简单的**属性型指令**来为一个HTML元素添加行为](#write-directive)， - - [use that directive in a template](#apply-directive), + - [Use that directive in a template](#apply-directive). - [在模板中使用那个指令](#apply-directive)， - - [respond to **events** to change behavior based on an event](#respond-to-user), + - [Respond to **events** to change behavior based on an event](#respond-to-user). - [响应**事件**，以便基于事件改变行为](#respond-to-user)， - - and [use **binding** to pass values to the attribute directive](#bindings). - - 以及[使用**绑定**来把值传给属性型指令](#bindings)。 + - [Use **binding** to pass values to the attribute directive](#bindings). + - 以及[使用**绑定**来把值传给属性型指令](#bindings)。 The final source: @@ -735,22 +575,16 @@ a#why-input .l-main-section :marked ### Appendix: Input properties + + ### 附录：Input属性 In this demo, the `highlightColor` property is an ***input*** property of `HighlightDirective`. + + 本例中, `highlightColor`属性是`HighlightDirective`指令的一个***input***属性。 You've seen properties in bindings before but never had to declare them as anything. Why now? - ### 附录：Input属性 - - Earlier we declared the `highlightColor` property to be an ***input*** property of our - `HighlightDirective` - - 之前, 我们曾把`highlightColor`定义为`HighlightDirective`指令的一个***input***属性。 - - We've seen properties in bindings before. - We never had to declare them as anything. Why now? - 以前也见过属性绑定，但我们从没有定义过它们。为什么现在就不行了？ Angular makes a subtle but important distinction between binding **sources** and **targets**. @@ -760,16 +594,13 @@ a#why-input In all previous bindings, the directive or component property was a binding ***source***. A property is a *source* if it appears in the template expression to the ***right*** of the equals (=). - - A property is a *target* when it appears in **square brackets** ([ ]) to the **left** of the equals (=) - as it is does when binding to the `myHighlight` property of the `HighlightDirective`. 在以前的所有绑定中，指令或组件的属性都是绑定***源***。 如果属性出现在了模板表达式等号(=)的***右侧***，它就是一个*源*。 - - A property is a *target* when it appears in **square brackets** ([ ]) to the **left** of the equals (=) ... - as it is does when we bind to the `myHighlight` property of the `HighlightDirective`, - + + A property is a *target* when it appears in **square brackets** ([ ]) to the **left** of the equals (=) + as it is does when binding to the `myHighlight` property of the `HighlightDirective`. + 如果它出现在了**方括号**([ ])中，并且出现在等号(=)的**左侧**，它就是一个*目标*…… 就像在绑定到`HighlightDirective`的`myHighlight`属性时所做的那样。 +makeExample('attribute-directives/ts/app/app.component.html','pHost')(format=".") @@ -785,45 +616,31 @@ a#why-input You must declare it as an *input* property or Angular rejects the binding with a clear error. - We must declare it as an *input* property. - Angular rejects the binding with a clear error if we don't. - `[myHighlight]="color"`中的'myHighlight'就是绑定***目标***。 必须把它定义为一个*Input*属性，否则，Angular就会拒绝这次绑定，并给出一个明确的错误。 Angular treats a *target* property differently for a good reason. A component or directive in target position needs protection. + + Angular这样区别对待*目标*属性有充分的理由。 + 作为目标的组件或指令需要保护。 Imagine that `HighlightDirective` did truly wonderous things in a popular open source project. + + 假想一下，`HighlightDirective`真是一个好东西。 + 我们优雅的把它当作礼物送给全世界。 Surprisingly, some people — perhaps naively — start binding to *every* property of the directive. Not just the one or two properties you expected them to target. *Every* property. That could really mess up your directive in ways you didn't anticipate and have no desire to support. - The ***input*** declaration ensures that consumers of your directive can only bind to - the properties of the public API but nothing else. - - Angular这样区别对待*目标*属性有充分的理由。 - 作为目标的组件或指令需要保护。 - - Imagine that our `HighlightDirective` did truly wonderous things. - We graciously made a gift of it to the world. - - 假想一下，`HighlightDirective`真是一个好东西。 - 我们优雅的把它当作礼物送给全世界。 - - To our surprise, some people — perhaps naively — - started binding to *every* property of our directive. - Not just the one or two properties we expected them to target. *Every* property. - That could really mess up our directive in ways we didn't anticipate and have no desire to support. - 出乎意料的是，有些人(可能因为太天真)开始绑定到这个指令中的*每一个*属性。 不仅仅只是我们预期为绑定目标的那一两个属性，而是*每一个*。 这可能会扰乱指令的工作方式 —— 我们既不想这样做也不想支持它们这样做。 - - The *input* declaration ensures that consumers of our directive can only bind to - the properties of our public API ... nothing else. - + + The ***input*** declaration ensures that consumers of your directive can only bind to + the properties of the public API but nothing else. + 于是，这种*输入*声明可以确保指令的消费者只能绑定到公开API中的属性，其它的都不行。 diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade index 8dd9b0956c..805d671331 100644 --- a/public/docs/ts/latest/guide/style-guide.jade +++ b/public/docs/ts/latest/guide/style-guide.jade @@ -2495,7 +2495,7 @@ a(href="#toc") 回到顶部 **Why?** If you ever need to rename the property or event name associated with `@Input` or `@Output`, you can modify it a single place. - **为何？** 如果你需要重命名属性或者`@Input`或者关联的事件名字 + **为何？** 如果你需要重命名属性或者`@Input`或者`@Output`关联的事件名字，你可以在一个位置修改。 .s-why :marked