From aad6313ff2baaa335de7dcdae3e93d4785748244 Mon Sep 17 00:00:00 2001 From: Zhicheng Wang Date: Mon, 16 May 2016 23:10:23 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E5=9F=BA=E7=A1=80=E7=9F=A5=E8=AF=86-?= =?UTF-8?q?=E9=A3=8E=E6=A0=BC=E6=8C=87=E5=8D=97=20=E4=BA=8C=E5=AE=A1?= =?UTF-8?q?=E5=AE=8C=E6=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- public/docs/ts/latest/guide/style-guide.jade | 556 ++++++++++--------- 1 file changed, 294 insertions(+), 262 deletions(-) diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade index d0c06ffce5..5c9f6a9555 100644 --- a/public/docs/ts/latest/guide/style-guide.jade +++ b/public/docs/ts/latest/guide/style-guide.jade @@ -10,11 +10,11 @@ include ../_util-fns If you are looking for an opinionated style guide for syntax, conventions, and structuring Angular applications, then step right in. - 如果你在为语法、公约和Angular应用程序结构寻找特定的风格指南，那么你来到了正确的地方。 + 如果你在寻找一份关于语法、约定和Angular应用程序的组织结构的风格指南，那你就来对了。 The purpose of this style guide is to provide guidance on building Angular applications by showing the conventions we use and, more importantly, why we choose them. - 本指南的目的是为开发Angular应用程序提供风格指导原则，展示我们遵循的公约，更重要的，解释我们为什么要选择这些公约。 + 本指南的目的是为开发Angular应用程序提供指导原则，展示我们所遵循的约定，更重要的是，解释我们为什么要选择这些约定。 .l-main-section @@ -24,46 +24,46 @@ include ../_util-fns Each guideline describes either a good or bad practice, and all have a consistent presentation. - 每个指导原则描述好的或者坏的做法，所有指导原则都照相呼应，保持了一致连贯性。 + 每个指导原则都会描述好的或者坏的做法，所有指导原则都相互呼应，保持一致。 The wording of each guideline indicates how strong the recommendation is. - 指导原则使用词汇来标志我们推荐的强度。 + 指导原则中使用的词汇表明我们推荐的强度。 .s-rule.do :marked **Do** is one that should always be followed. _Always_ might be a bit too strong of a word. Guidelines that literally should always be followed are extremely rare. On the other hand, we need a really unusual case for breaking a *Do* guideline. - **坚持** 标志着总是应该遵循的公约。_总是_ 可能有点太强。应该 _总是_ 遵循的指导原则非常少见。但是，我们需要非常不寻常的情况来打破 *坚持* 的原则。 + **坚持**意味着总是应该遵循的约定。_总是_可能有点太强。应该_总是_遵循的指导原则非常少见。但是，只有遇到非常不寻常的情况才能打破*坚持*的原则。 .s-rule.consider :marked **Consider** guidelines should generally be followed. - **考虑** 标志着通常应该遵循的指导原则。 + **考虑**标志着通常应该遵循的指导原则。 If you fully understand the meaning behind the guideline and have a good reason to deviate, then do so. Please strive to be consistent. - 如果你能完全理解指导原则背后的意思，并且有很好的理由越轨，那就可以打破该指导原则。但是请保持一致连贯性。 + 如果你能完全理解指导原则背后的含义，并且很好的理由打破它，那就可以打破该指导原则。但是请保持一致。 .s-rule.avoid :marked **Avoid** indicates something we should almost never do. Code examples to *avoid* have an unmistakeable red header. - **避免** 标志着我们决不应该做的事。需要*避免*的代码例子会有不会被错过红色标题。 + **避免**标志着我们决不应该做的事。需要*避免*的代码范例会有不会被忽视的红色标题。 .l-main-section :marked ## File Structure Conventions - ## 文件结构公约 + ## 文件结构约定 Some code examples display a file that has one or more similarly named companion files. (e.g. hero.component.ts and hero.component.html). - 在一些代码例子中，有文件拥有一个或多个相似名字的伴随文件。（比如，hero.component.ts和hero.component.html)。 + 在一些代码例子中，有的文件拥有一个或多个相似名字的伴随文件。（比如，hero.component.ts和hero.component.html)。 The guideline will use the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse. - 本指南将会使用像`hero.component.ts|html|css|spec`的简写来表示上面描述的多个文件，目的保持本指南的简洁性，增加对文件结构描述的阅读性。 + 本指南将会使用像`hero.component.ts|html|css|spec`的简写来表示上面描述的多个文件，目的是保持本指南的简洁性，增加文件结构描述时的可读性。 .l-main-section a(id='toc') @@ -78,11 +78,11 @@ a(id='toc') 1. [Naming](#naming) - 1. [命名公约](#naming) + 1. [命名约定](#naming) 1. [Coding Conventions](#coding-conventions) - 1. [代码公约](#coding-conventions) + 1. [代码约定](#coding-conventions) 1. [Application Structure](#application-structure) @@ -124,7 +124,7 @@ a(id='toc') We apply the [Single Responsibility Principle](https:\/\/en.wikipedia.org/wiki/Single_responsibility_principle) to all Components, Services, and other symbols we create. This helps make our app cleaner, easier to read and maintain, and more testable. - 我们应用[单一职责原则](https:\/\/en.wikipedia.org/wiki/Single_responsibility_principle)来创建的所有组件、服务和其它标志等。这样能帮助我们把应用程序弄的干净整洁，易于阅读、维护和测试。 + 我们遵循[单一职责原则](https:\/\/en.wikipedia.org/wiki/Single_responsibility_principle)来创建的所有组件、服务和其它标志等。这样能帮助我们把应用程序弄的干净整洁，易于阅读、维护和测试。 ### Rule of One ### 单一法则 @@ -135,31 +135,31 @@ a(id='toc') :marked **Do** define one thing (e.g. service or component) per file. - **坚持** 每个文件只定义一样东西（比如服务或者组件）。 + **坚持**每个文件只定义一样东西（比如服务或者组件）。 .s-rule.consider :marked **Consider** limiting files to 400 lines of code. - **考虑** 限制文件大小为400行代码之内。 + **考虑**把文件大小限制在400行代码以内。 .s-why :marked **Why?** One component per file makes it far easier to read, maintain, and avoid collisions with teams in source control. - **为何？** 单组件文件可以让它非常易于阅读、维护，并且能防止在版本控制里与团队冲突。 + **为何？**单组件文件非常容易阅读、维护，并能防止在版本控制系统里与团队冲突。 .s-why :marked **Why?** One component per file avoids hidden bugs that often arise when combining components in a file where they may share variables, create unwanted closures, or unwanted coupling with dependencies. - **为何？** 单组件文件可以防止一些隐蔽的程序缺陷，这些缺陷错误经常在合并一些共享变量的组件到一个文件时发生，造成讨厌的闭包或者依赖联结。 + **为何？**单组件文件可以防止一些隐蔽的程序缺陷，当把多个组件合写在同一个文件中时，可能造成共享变量、创建意外的闭包，或者与依赖之间产生意外耦合等情况。 .s-why.s-why-last :marked **Why?** A single component can be the default export for its file which facilitates lazy loading with the Component Router. - **为何？** 单独的组件通常是该文件默认的输出，支持利用组件路由器按需加载。 + **为何？**单独的组件通常是该文件默认的输出，这样就可以利用组件路由器实现按需加载。 :marked The key is to make the code more reusable, easier to read, and less mistake prone. @@ -174,7 +174,7 @@ a(id='toc') :marked Better to redistribute the component and supporting activities into their own dedicated files. - 将组件和其支持部件重新分配到它们自己独立的文件会更好。 + 将组件及其支撑部件重新分配到独立的文件中会更好。 +makeTabs( `style-guide/ts/01-01/app/main.ts, @@ -206,47 +206,47 @@ a(href="#toc") 回到顶部 ### 小函数 #### Style 01-02 - ### 风格01-02 + #### 风格01-02 .s-rule.do :marked **Do** define small functions - **坚持** 定义小的函数 + **坚持**定义小函数 .s-rule.consider :marked **Consider** limiting to no more than 75 lines. - **考虑** 限制在75行之内 + **考虑**限制在75行之内 .s-why :marked **Why?** Small functions are easier to test, especially when they do one thing and serve one purpose. - **为何？** 小函数更加易于测试，特别是当它们只做一件事，只为一个目的服务的时候。 + **为何？**小函数更易于测试，特别是当它们只做一件事，只为一个目的服务的时候。 .s-why :marked **Why?** Small functions promote reuse. - **为何？** 小函数促进了代码的重用。 + **为何？**小函数促进了代码的重用。 .s-why :marked **Why?** Small functions are easier to read. - **为何？** 小函数更加易于阅读。 + **为何？**小函数更加易于阅读。 .s-why :marked **Why?** Small functions are easier to maintain. - **为何？** 小函数更加易于维护。 + **为何？**小函数更加易于维护。 .s-why.s-why-last :marked **Why?** Small functions help avoid hidden bugs that come with large functions that share variables with external scope, create unwanted closures, or unwanted coupling with dependencies. - **为何？** 小函数帮助避免一些大函数与外界互相共享变量时，容易造成的令人讨厌的闭包和依赖联结等隐蔽错误。 + **为何？**小函数帮助避免一些大函数容易产生的那些与外界共享变量、创建意外的闭包或与依赖之间产生意外耦合等隐蔽的错误。 a(href="#toc") Back to top @@ -255,11 +255,11 @@ a(href="#toc") 回到顶部 .l-main-section :marked ## Naming - ## 命名公约 + ## 命名约定 Naming conventions are hugely important to maintainability and readability. This guide recommends naming conventions for the file name and the symbol name. - 命名公约对维护性和可读性非常重要。本指南为文件和标志命名推荐了一个命名公约。 + 命名约定对维护性和可读性非常重要。本指南为文件和标志命名推荐了一套命名约定。 .l-main-section :marked @@ -273,32 +273,32 @@ a(href="#toc") 回到顶部 :marked **Do** use consistent names for all symbols. - **坚持** 为所有标志使用一致的命名规则。 + **坚持**为所有符号使用一致的命名规则。 .s-rule.do :marked **Do** follow a pattern that describes the symbol's feature then its type. The recommended pattern is `feature.type.ts`. - **坚持** 遵循一个模式来描述标志的特性和类型。推荐的模式为`feature.type.ts`。 + **坚持**遵循同一个模式来描述符号的特性和类型。推荐的模式为`feature.type.ts`。 .s-why :marked **Why?** Naming conventions help provide a consistent way to find content at a glance. Consistency within the project is vital. Consistency with a team is important. Consistency across a company provides tremendous efficiency. - **为何？** 命名公约帮助我们提供了一致连贯的方法来一眼锁定内容。在整个项目内保持一致性是至关重要的。在团队内保持一致性也很重要。在公司内部保持一致性可以大幅提高效率。 + **为何？**命名约定提供了一致的方法来帮助我们一眼锁定内容。在整个项目内保持一致性是至关重要的。在团队内保持一致性也很重要。在公司内部保持一致性可以大幅提高效率。 .s-why :marked **Why?** The naming conventions should simply help us find our code faster and make it easier to understand. - **为何？** 命名公约的单纯目的是：帮助我们快速找到我们的代码并让它们更加易于理解。 + **为何？**命名约定最直接的目的是：帮我们快速找到代码并让它们更容易理解。 .s-why.s-why-last :marked **Why?** Names of folders and files should clearly convey their intent. For example, `app/heroes/hero-list.component.ts` may contain a component that manages a list of heroes. - **为何？** 目录和文件的名字应该清楚的说明它们的用途。比如`app/heroes/hero-list.component.ts`包含了一个用来维护英雄列表的组件。 + **为何？**目录和文件的名字应该清楚的说明它们的用途。比如`app/heroes/hero-list.component.ts`包含了一个用来维护英雄列表的组件。 a(href="#toc") Back to top @@ -317,43 +317,43 @@ a(href="#toc") 回到顶部 :marked **Do** use dashes to separate words. - **坚持** 使用横杠来分隔单词。 + **坚持**使用横杠来分隔单词。 .s-rule.do :marked **Do** use dots to separate the descriptive name from the type. - **坚持** 使用点来分隔描述性名字和类型名字。 + **坚持**使用点来分隔描述性名字和类型名。 .s-rule.do :marked **Do** use consistent names for all components following a pattern that describes the component's feature then its type. A recommended pattern is `feature.type.ts`. - **坚持** 对所有组件使用一致的命名规则，遵循这个模式：先描述组件的特征，再描述它的类型。推荐的模式为`feature.type.ts`。 + **坚持**对所有组件使用一致的命名规则，遵循这个模式：先描述组件的特性，再描述它的类型。推荐的模式为`feature.type.ts`。 .s-rule.do :marked **Do** use conventional suffixes for the types including `*.service.ts`, `*.component.ts`, `*.pipe.ts`. Invent other suffixes where desired, but take care in having too many. - **坚持** 使用惯例后缀来描述类型，比如`*.service.ts`、`*.component.ts`、`*.pipe.ts`。如果愿意，你可以发明其它的后缀，但是注意不要太多。 + **坚持**使用惯用的后缀来描述类型，比如`*.service.ts`、`*.component.ts`、`*.pipe.ts`。如果你愿意，也可以发明其它后缀，但注意不要太多。 .s-why :marked **Why?** Provides a consistent way to quickly identify what is in the file. - **为何？** 提供一致的方法来快速的识别文件是什么。 + **为何？**提供一致的方法来快速的识别文件是什么。 .s-why :marked **Why?** Provides a consistent way to quickly find a specific file using an editor or IDE's fuzzy search techniques. - **为何？** 提供一致的方法，利用编辑器或者IDE的模糊搜索功能，快速找到特定文件。 + **为何？**提供一致的方法，利用编辑器或者IDE的模糊搜索功能，快速找到特定文件。 .s-why.s-why-last :marked **Why?** Provides pattern matching for any automated tasks. - **为何？** 与自动任务的模式匹配。 + **为何？**与自动化任务的模式匹配。 a(href="#toc") Back to top @@ -372,46 +372,50 @@ a(href="#toc") 回到顶部 :marked **Do** use consistent names for all assets named after what they represent. - **坚持** 为所有东西使用一致的命名公约：以它们所代表的东西命名。 + **坚持**为所有东西使用一致的命名约定：以它们所代表的东西命名。 .s-rule.do :marked **Do** use upper camel case for symbols. Match the name of the symbol to the naming of the file. - **坚持** 使用大写驼峰命名法来命名所有符号（类）。保持符号的名字和它所在的文件名字相同。 + **坚持**使用大写驼峰命名法来命名所有符号（类）。保持符号的名字与它所在的文件名字相同。 .s-rule.do :marked **Do** append the symbol name with the suffix that it represents. - **坚持** 把符号的类型（比如组件、服务、指令等）附加到符号名字右面。 + **坚持**把符号的类型（比如组件、服务、指令等）附加到符号名的后面。 .s-why :marked **Why?** Provides a consistent way to quickly identify and reference assets. - **为何？** 提供前后一致的方法迅速辨识和引用东西。 + **为何？**提供前后一致的方法迅速辨识和引用东西。 .s-why :marked **Why?** Upper camel case is conventional for identifying objects that can be instantiated using a constructor. - **为何？** 大写驼峰命名法是用来辨识可以利用构造函数来实例化的对象的公约。 + **为何？**大写驼峰命名法约定用来辨识出那些可通过构造函数来实例化的对象。 .s-why.s-why-last :marked **Why?** The `Component` suffix is more commonly used and is more explicitly descriptive. - **为何？** `Component`后缀是常见的用法，它具有精准的描述性。 + **为何？**`Component`后缀是常见的用法，它具有精准的描述性。 - var top="vertical-align:top" table(width="100%") col(width="50%") col(width="50%") tr - th Symbol Name - th File Name + th + p Symbol Name + p 符号名 + th + p File Name + p 文件名 tr(style=top) td code-example. @@ -461,7 +465,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Service Names - ### 服务名字 + ### 服务名 #### Style 02-04 #### 风格02-04 @@ -470,45 +474,49 @@ a(href="#toc") 回到顶部 :marked **Do** use consistent names for all services named after their feature. - **坚持** 使用前后一致的命名规则来命名服务，以它们的特性来命名。 + **坚持**使用前后一致的命名规则来命名服务，以它们的特性来命名。 .s-rule.do :marked **Do** use upper camel case for services. - **坚持** 使用大写驼峰命名法来命名服务。 + **坚持**使用大写驼峰命名法来命名服务。 .s-rule.do :marked **Do** suffix services with `Service` when it is not clear what they are (e.g. when they are nouns). - **坚持** 当不能从它们的名字里清楚的看出它们是什么的时候（比如它们的名字是名词时），添加`Service`后缀。 + **坚持**当不能从它们的名字里清楚的看出它们是什么的时候（比如它们的名字是名词时），添加`Service`后缀。 .s-why :marked **Why?** Provides a consistent way to quickly identify and reference services. - **为何？** 提供前后一致的方法来快速识别和引用服务。 + **为何？**提供前后一致的方法来快速识别和引用服务。 .s-why :marked **Why?** Clear service names such as `logger` do not require a suffix. - **为何？** 清楚的服务名字比如`logger`不需要后缀。 + **为何？**清楚的服务名，比如`logger`不需要后缀。 .s-why.s-why-last :marked **Why?** Service names such as `Credit` are nouns and require a suffix and should be named with a suffix when it is not obvious if it is a service or something else. - **为何？** 服务名字是名词，比如`Credit`，需要一个后缀。当名字不能很明显的标示它是服务还是其他东西的时候，应该添加后缀。 + **为何？**如果服务名字是名词时，比如`Credit`，需要一个后缀。当名字不能很明显的标示出它是服务还是其它东西的时候，应该添加后缀。 - var top="vertical-align:top" table(width="100%") col(width="50%") col(width="50%") tr - th Symbol Name - th File Name + th + p Symbol Name + p 符号名 + th + p File Name + p 文件名 tr(style=top) td code-example. @@ -551,25 +559,25 @@ a(href="#toc") 回到顶部 :marked **Do** put bootstrapping and platform logic for the app in a file named `main.ts`. - **坚持** 把应用的引导程序和平台逻辑放到名字为`main.ts`的文件里。 + **坚持**把应用的引导程序和平台相关的逻辑放到名为`main.ts`的文件里。 .s-rule.avoid :marked **Avoid** putting app logic in the `main.ts`. Instead consider placing it in a Component or Service. - **避免** 把应用逻辑放到`main.ts`里。考虑把它放到组件或服务里面。 + **避免**把应用逻辑放到`main.ts`里。考虑把它放到组件或服务里面。 .s-why :marked **Why?** Follows a consistent convention for the startup logic of an app. - **为何？** 遵循前后一致的公约来处理应用的启动逻辑。 + **为何？**遵循前后一致的约定来处理应用的启动逻辑。 .s-why.s-why-last :marked **Why?** Follows a familiar convention from other technology platforms. - **为何？** 从其他技术平台借鉴一个熟悉的公约。 + **为何？**这是从其它技术平台借鉴的一个常用约定。 a(href="#toc") Back to top @@ -588,19 +596,19 @@ a(href="#toc") 回到顶部 :marked **Do** Use lower camel case for naming the selectors of our directives. - **坚持** 使用小驼峰命名法来命名指令的选择器。 + **坚持**使用小驼峰命名法来命名指令的选择器。 .s-why :marked **Why?** Keeps the names of the properties defined in the directives that are bound to the view consistent with the attribute names. - **为何？** 保持指令里定义的属性名字与它们绑定的视图HTML属性名字一致。 + **为何？**保持指令里定义的属性名字与它们绑定的视图HTML属性名字一致。 .s-why.s-why-last :marked **Why?** The Angular 2 HTML parser is case sensitive and will recognize lower camel case. - **为何？** Angular 2 HTML剖析器是大小写敏感的，它识别小写驼峰写法。 + **为何？**Angular 2 HTML解析器是大小写敏感的，它识别小写驼峰写法。 a(href="#toc") Back to top @@ -619,31 +627,31 @@ a(href="#toc") 回到顶部 :marked **Do** use a custom prefix for the selector of our components. For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the prefix `admin` represents an admin feature area. - **坚持** 为组件的选择器使用自定义前缀。比如，前缀`tod`是从**T**our **o**f **H**eros来的，前缀`admin`代表了admin的特征区域。 + **坚持**为组件的选择器使用自定义前缀。比如，前缀`tod`是从**T**our **o**f **H**eros来的，前缀`admin`代表了admin的特性区域。 .s-rule.do :marked **Do** use a prefix that identifies the feature area or the app itself. - **坚持** 使用前缀来识别特征区域或者应用程序本身。 + **坚持**使用前缀来识别特性区域或者应用程序本身。 .s-why :marked **Why?** Prevents name collisions. - **为何？** 防止名字冲突。 + **为何？**防止名字冲突。 .s-why :marked **Why?** Makes it easier to promote and share our feature in other apps. - **为何？** 在其他程序里面推广和共享我们的程序变得更加容易。 + **为何？**把我们的代码推广和共享到其它应用中会更容易。 .s-why.s-why-last :marked **Why?** Our Components and elements are easily identified. - **为何？** 我们组件和元素更加容易被识别。 + **为何？**我们组件和元素更容易被识别。 +makeExample('style-guide/ts/02-07/app/heroes/hero.component.avoid.ts', 'example', 'app/heroes/hero.component.ts')(avoid=1) :marked @@ -668,19 +676,19 @@ a(href="#toc") 回到顶部 :marked **Do** use a custom prefix for the selector of our directives (for instance below we use the prefix `toh` from **T**our **o**f **H**eroes). - **坚持** 为指令的选择器使用自定义的前缀（比如下面例子用，我们使用前缀`toh`，取自**T**our **o**f **H**eroes)。 + **坚持**为指令的选择器使用自定义的前缀（比如下面例子中，我们使用前缀`toh`，取自**T**our **o**f **H**eroes)。 .s-why :marked **Why?** Prevents name collisions. - **为何？** 防止名字冲突。 + **为何？**防止名字冲突。 .s-why.s-why-last :marked **Why?** Our Directives are easily identified. - **为何？** 指令更加容易被识别。 + **为何？**指令更加容易被识别。 +makeExample('style-guide/ts/02-08/app/shared/validate.directive.avoid.ts', 'example', 'app/shared/validate.directive.ts')(avoid=1) :marked @@ -695,7 +703,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Pipe Names - ### 管道名字 + ### 管道名 #### Style 02-09 #### 风格02-09 @@ -704,21 +712,25 @@ a(href="#toc") 回到顶部 :marked **Do** use consistent names for all pipes, named after their feature. - **坚持** 为所有管道使用前后一致的命名公约，用它们的特性来命名。 + **坚持**为所有管道使用前后一致的命名约定，用它们的特性来命名。 .s-why.s-why-last :marked **Why?** Provides a consistent way to quickly identify and reference pipes. - **为何？** 提供一致的方法快速识别和引用管道。 + **为何？**提供一致的方法快速识别和引用管道。 - var top="vertical-align:top" table(width="100%") col(width="50%") col(width="50%") tr - th Symbol Name - th File Name + th + p Symbol Name + p 符号名 + th + p File Name + p 文件名 tr(style=top) td code-example. @@ -753,25 +765,25 @@ a(href="#toc") 回到顶部 :marked **Do** name test specification files the same as the component they test. - **坚持** 测试配置文件的名字应该和被测试的组件名字一样。 + **坚持**测试规范文件的名字应该和被测试的组件名字一样。 .s-rule.do :marked **Do** name test specification files with a suffix of `.spec`. - **坚持** 测试配置文件命名应该跟随后缀`.spec`。 + **坚持**测试配置文件命名应该跟随后缀`.spec`。 .s-why :marked **Why?** Provides a consistent way to quickly identify tests. - **为何？** 提供一致的方法来快速识别测试。 + **为何？**提供一致的方法来快速识别测试。 .s-why.s-why-last :marked **Why?** Provides pattern matching for [karma](http://karma-runner.github.io/) or other test runners. - **为何？** 提供一个与[karma](http://karma-runner.github.io/)或者其他测试运行器相配的命名模式。 + **为何？**提供一个与[karma](http://karma-runner.github.io/)或者其他测试运行器相配的命名模式。 :marked - var top="vertical-align:top" @@ -779,12 +791,18 @@ table(width="100%") col(width="50%") col(width="50%") tr - th Symbol Name - th File Name + th + p Symbol Name + p 符号名 + th + p File Name + p 文件名 tr(style=top) td :marked Components + + 组件 td :marked heroes.component.spec.ts @@ -796,6 +814,8 @@ table(width="100%") td :marked Services + + 服务 td :marked logger.service.spec.ts @@ -807,6 +827,8 @@ table(width="100%") td :marked Pipes + + 管道 td :marked ellipsis.pipe.spec.ts @@ -816,10 +838,12 @@ table(width="100%") a(href="#toc") Back to top +a(href="#toc") 回到顶部 + .l-main-section :marked ### End to End Test File Names - ### 端对端测试文件命名 + ### 端到端测试文件命名 #### Style 02-11 #### 风格02-11 @@ -828,19 +852,19 @@ a(href="#toc") Back to top :marked **Do** name end-to-end test specification files after the feature they test with a suffix of `.e2e-spec`. - **坚持** 端对端测试配置文件应该和它们所测试的特征同名，并加上后缀`.e2e-spec`。 + **坚持**端到端测试配置文件应该和它们所测试的特性同名，并加上后缀`.e2e-spec`。 .s-why :marked **Why?** Provides a consistent way to quickly identify end-to-end tests. - **为什么？** 提供一致的方法快速识别端对端测试文件。 + **为何？**提供一致的方法快速识别端到端测试文件。 .s-why.s-why-last :marked **Why?** Provides pattern matching for test runners and build automation. - **为何？** 提供一个与测试运行器和构建自动化相配的模式。 + **为何？**提供一个与测试运行器和构建自动化相配的模式。 :marked :marked @@ -849,12 +873,18 @@ table(width="100%") col(width="50%") col(width="50%") tr - th Symbol Name - th File Name + th + p Symbol Name + p 符号名 + th + p File Name + p 文件名 tr(style=top) td :marked End to End Tests + + 端到端测试 td :marked app.e2e-spec.ts @@ -869,11 +899,11 @@ a(href="#toc") 回到顶部 .l-main-section :marked ## Coding Conventions - ## 编程公约 + ## 编程约定 Have consistent set of coding, naming, and whitespace conventions. - 坚持一套前后一致的编程、命名和空格的公约。 + 坚持一套前后一致的编程、命名和空格的约定。 .l-main-section :marked @@ -887,19 +917,19 @@ a(href="#toc") 回到顶部 :marked **Do** use upper camel case when naming classes. - **坚持** 使用大写驼峰命名法来命名类。 + **坚持**使用大写驼峰命名法来命名类。 .s-why :marked **Why?** Follows conventional thinking for class names. - **为何？** 遵循类命名传统公约。 + **为何？**遵循类命名传统约定。 .s-why.s-why-last :marked **Why?** Classes can be instantiated and construct an instance. We often use upper camel case to indicate a constructable asset. - **为何？** 类可以被实例化。我们通常使用大写驼峰命名公约来标示可以构造的东西。 + **为何？**类可以被实例化。我们通常使用大写驼峰命名约定来标示可被构造出来的东西。 +makeExample('style-guide/ts/03-01/app/shared/exception.service.avoid.ts', 'example', 'app/shared/exception.service.ts')(avoid=1) :marked @@ -924,19 +954,19 @@ a(href="#toc") 回到顶部 :marked **Do** use uppercase with underscores when naming constants. - **坚持** 使用全大写，用下划线隔开单词的方法来命名常量。 + **坚持**使用全大写，用下划线隔开单词的方法来命名常量。 .s-why :marked **Why?** Follows conventional thinking for constants. - **为何？** 遵循传统的常量命名方法。 + **为何？**遵循传统的常量命名方法。 .s-why.s-why-last :marked **Why?** Constants can easily be identified. - **为何？** 常量更容易被识别。 + **为何？**常量更容易被识别。 +makeExample('style-guide/ts/03-02/app/shared/data.service.avoid.ts', 'example', 'app/shared/data.service.ts')(avoid=1) :marked @@ -961,19 +991,19 @@ a(href="#toc") 回到顶部 :marked **Do** name an interface using upper camel case. - **坚持** 使用大写驼峰命名法来命名接口。 + **坚持**使用大写驼峰命名法来命名接口。 .s-rule.do :marked **Consider** naming an interface without an `I` prefix. - **考虑** 不要在接口名字前面加`I`前缀。 + **考虑**不要在接口名字前面加`I`前缀。 .s-why.s-why-last :marked **Why?** When we use types, we can often simply use the class as the type. - **为何？** 当我们使用类型时，我们经常简单地使用类来作为类型。 + **为何？**当我们使用类型时，我们经常简单地使用类来作为类型。 +makeExample('style-guide/ts/03-03/app/shared/hero-collector.service.avoid.ts', 'example', 'app/shared/hero-collector.service.ts')(avoid=1) :marked @@ -989,7 +1019,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Properties and Methods - ### 属性和方法命名 + ### 属性和方法名 #### Style 03-04 #### 风格03-04 @@ -998,31 +1028,31 @@ a(href="#toc") 回到顶部 :marked **Do** use lower camel case to name properties and methods. - **坚持** 使用小写驼峰命名法来命名属性和方法。 + **坚持**使用小写驼峰命名法来命名属性和方法。 .s-rule.avoid :marked **Avoid** prefixing private properties and methods with an underscore. - **避免** 使用下划线为前缀来命名私有属性和方法。 + **避免**使用下划线为前缀来命名私有属性和方法。 .s-why :marked **Why?** Follows conventional thinking for properties and methods. - **为何？** 遵循传统属性和方法的命名公约。 + **为何？**遵循传统属性和方法的命名约定。 .s-why :marked **Why?** JavaScript lacks a true private property or method. - **为何？** JavaScript不支持真正的私有属性和方法。 + **为何？**JavaScript不支持真正的私有属性和方法。 .s-why.s-why-last :marked **Why?** TypeScript tooling makes it easy to identify private vs public properties and methods. - **为何？** TypeScript工具使识别私有或公有属性和方法变得很简单。 + **为何？**TypeScript工具让识别私有或公有属性和方法变得很简单。 +makeExample('style-guide/ts/03-04/app/shared/toast/toast.service.avoid.ts', 'example', 'app/shared/toast/toast.service.ts')(avoid=1) :marked @@ -1038,7 +1068,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Import Destructuring Spacing - ### 导入声明解构的空格 + ### 导入语句解构表达式中的空格 #### Style 03-05 #### 风格03-05 @@ -1047,13 +1077,13 @@ a(href="#toc") 回到顶部 :marked **Do** leave one whitespace character inside of the `import` statements' curly braces when destructuring. - **坚持** 在解构时，`import`声明的大括号里面留一个空格字符。 + **坚持**解构时，在`import`声明的大括号里留一个空格字符。 .s-why.s-why-last :marked **Why?** Whitespace makes it easier to read the imports. - **为何？** 空格让导入声明更易于阅读。 + **为何？**空格让import声明更易于阅读。 +makeExample('style-guide/ts/03-05/app/+heroes/shared/hero.service.avoid.ts', 'example', 'app/+heroes/shared/hero.service.ts')(avoid=1) :marked @@ -1068,7 +1098,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Import Line Spacing - ### 导入声明空行 + ### 导入语句中的空行 #### Style 03-06 #### 风格03-06 @@ -1077,31 +1107,31 @@ a(href="#toc") 回到顶部 :marked **Do** leave one empty line between third party imports and imports of code we created. - **坚持** 在第三方导入和自己代码的导入之间留一行空行。 + **坚持**在第三方导入和自己代码的导入之间留一个空行。 .s-rule.do :marked **Do** list import lines alphabetized by the module. - **坚持** 按模块名字的字母顺排列导入行。 + **坚持**按模块名字的字母顺排列导入行。 .s-rule.do :marked **Do** list destructured imported assets alphabetically. - **坚持** 按字母顺序排列解构导入行。 + **坚持**在解构表达式中按字母顺序排列导入的东西。 .s-why :marked **Why?** The empty line makes it easy to read and locate imports. - **为何？** 空行可以让阅读和定位本地导入变得更加容易。 + **为何？**空行可以让阅读和定位本地导入变得更加容易。 .s-why.s-why-last :marked **Why?** Alphabetizing makes it easier to read and locate imports. - **为何？** 按字母顺序排列可以让阅读和定位本地导入更加容易。 + **为何？**按字母顺序排列可以让阅读和定位本地导入更加容易。 +makeExample('style-guide/ts/03-06/app/+heroes/shared/hero.service.avoid.ts', 'example', 'app/+heroes/shared/hero.service.ts')(avoid=1) :marked @@ -1121,11 +1151,12 @@ a(href="#toc") 回到顶部 Have a near term view of implementation and a long term vision. Start small but keep in mind where the app is heading down the road. - 准备一个短期和一个长期的实施方案。从零开始，但是时刻考虑应用程序接下来要走的路。 + 准备一个短期和一个长期的实施方案。从零开始，但要时刻考虑应用程序接下来要走的路。 All of the app's code goes in a folder named `app`. All content is 1 feature per file. Each component, service, and pipe is in its own file. All 3rd party vendor scripts are stored in another folder and not in the `app` folder. We didn't write them and we don't want them cluttering our app. Use the naming conventions for files in this guide. - 把所有的应用程序的源代码都放到名叫`app`的目录里。所有内容都遵循每个文件单个特征的原则。每个组件、服务和管道都在自己的文件里。所有第三方程序包都被保存到其他目录里而不在`app`目录里，我们不会修改它们，所以不希望它们弄乱我们的应用程序。使用本指南介绍的文件命名公约。 + 把所有应用程序的源代码都放到名叫`app`的目录里。所有内容都遵循每个文件单个特性的原则。每个组件、服务和管道都在自己的文件里。 + 所有第三方程序包都被保存到其它目录里而不在`app`目录里，我们不会修改它们，所以不希望它们弄乱我们的应用程序。使用本指南介绍的文件命名约定。 a(href="#toc") Back to top @@ -1135,7 +1166,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### LIFT - ### LIFT (定位`L`ocate、识别`I`dentity、平坦`F`lattest、尝试`T`ry遵循不重复自己DRY - Do Not Repeat Yourself公约) + ### LIFT (定位`L`ocate、识别`I`dentity、平面化`F`lattest、尝试`T`ry遵循不重复自己DRY - Do Not Repeat Yourself约定) #### Style 04-01 #### 风格04-01 @@ -1144,19 +1175,19 @@ a(href="#toc") 回到顶部 :marked **Do** structure the app such that we can `L`ocate our code quickly, `I`dentify the code at a glance, keep the `F`lattest structure we can, and `T`ry to be DRY. - **坚持** 组织应用的结构，达到这些目的：快速定位(`L`ocate)代码、一眼识别(`I`dentify)代码、尽量保持结构平坦(`F`lattest)和尝试`T`ry遵循不重复自己DRY - Do Not Repeat Yourself公约。 + **坚持**组织应用的结构，达到这些目的：快速定位(`L`ocate)代码、一眼识别(`I`dentify)代码、尽量保持平面化结构(`F`lattest)和尝试`T`ry遵循不重复自己DRY - Do Not Repeat Yourself约定。 .s-rule.do :marked **Do** define the structure to follow these four basic guidelines, listed in order of importance. - **坚持** 遵循四个基本指导原则来定义文件结构，上面四个基本原则是按重要顺序排列的。 + **坚持**遵循四个基本指导原则来定义文件结构，上面四个基本原则是按重要顺序排列的。 .s-why.s-why-last :marked **Why?** LIFT Provides a consistent structure that scales well, is modular, and makes it easier to increase developer efficiency by finding code quickly. Another way to check our app structure is to ask ourselves: How quickly can we open and work in all of the related files for a feature? - **为何？** LIFT提供了前后一致的结构，它具有扩展行强、模块化的特征。由于易于快速锁定代码，所以提高了开发者效率。另外检查应用结构的方法是质问自己：我们打开和编辑与某个特征相关的所有文件的速度如何？ + **为何？**LIFT提供了前后一致的结构，它具有扩展性强、模块化的特性。因为容易快速锁定代码，所以提高了开发者的效率。另外，检查应用结构的方法是问问自己：我们打开和编辑与某个特性相关的所有文件的速度如何？ a(href="#toc") Back to top a(href="#toc") 回到顶部 @@ -1173,13 +1204,13 @@ a(href="#toc") 回到顶部 :marked **Do** make locating our code intuitive, simple and fast. - **坚持** 直观、简单和快速的定位我们的代码。 + **坚持**直观、简单和快速的定位我们的代码。 .s-why.s-why-last :marked **Why?** We find this to be super important for a project. If we cannot find the files we need to work on quickly, we will not be able to work as efficiently as possible, and the structure needs to change. We may not know the file name or where its related files are, so putting them in the most intuitive locations and near each other saves a ton of time. A descriptive folder structure can help with this. - **为何？** 定位对项目是非常重要的。如果我们不能快速找到需要工作的文件，我们就不可能在最佳效率状态下面工作，结构就需要更换。我们可能不知道文件的名称或者文件所在目录名，所以我们把它们放到直观的地方，一个挨着一个，这样可以节省很多时间。坚持说明性强的文件结构会有很大帮助。 + **为何？**定位对项目是非常重要的。如果我们不能快速找到需要工作的文件，我们就不可能在最佳效率状态下面工作，结构就需要更换。我们可能不知道文件的名称或者文件所在目录名，所以我们把它们放到直观的地方，一个挨着一个，这样可以节省很多时间。坚持说明性强的文件结构会有很大帮助。 a(href="#toc") Back to top @@ -1197,31 +1228,31 @@ a(href="#toc") 回到顶部 :marked **Do** name the file such that we instantly know what it contains and represents. - **坚持** 命名文件到这个程度：可以从名字立刻知道它包含了什么，代表了什么。 + **坚持**命名文件到这个程度：可以从名字立刻知道它包含了什么，代表了什么。 .s-rule.do :marked **Do** be descriptive with file names and keeping the contents of the file to exactly one component. - **坚持** 文件名要具有说明性，并保证文件只包含一个组件。 + **坚持**文件名要具有说明性，并保证文件中只包含一个组件。 .s-rule.avoid :marked **Avoid** files with multiple components, multiple services, or a mixture. - **避免** 创建包含很多组件、服务或者混合体的文件。 + **避免**创建包含很多组件、服务或者混合体的文件。 .s-why.s-why-last :marked **Why?** We spend less time hunting and pecking for code, and become more efficient. If this means we want longer file names, then so be it. - **为何？** 我们花费更少的时间来查找和琢磨代码，工作更有效率。如果这意味着更长的文件名，那就让它去吧。 + **为何？**我们花费更少的时间来查找和琢磨代码，工作更有效率。如果这意味着更长的文件名，长就长吧。 .l-sub-section :marked There are deviations of the 1 per file rule when we have a set of very small features that are all related to each other, as they are still easily identifiable. - 当我们有一套非常小并且互相关联的特征时，我们可能不坚持单文件单组件的公约，因为它们任然非常易于被识别。 + 当我们有一套非常小并且互相关联的特性时，我们可能不必坚持单文件单组件的约定，因为它们仍然非常易于被识别。 a(href="#toc") Back to top @@ -1231,7 +1262,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Flat - ### 平坦 + ### 平面化 #### Style 04-04 #### 风格04-04 @@ -1240,19 +1271,19 @@ a(href="#toc") 回到顶部 :marked **Do** keep a flat folder structure as long as possible. - **坚持** 尽可能保持平坦的目录结构。 + **坚持**尽可能保持平面化的目录结构。 .s-rule.consider :marked **Consider** creating fodlers when we get to seven or more files. - **考虑** 当我们有7个或更多的文件时才新建目录。 + **考虑**当我们有7个或更多文件时才新建目录。 .s-why.s-why-last :marked **Why?** Nobody wants to search seven levels of folders to find a file. In a folder structure there is no hard and fast number rule, but when a folder has seven to ten files, that may be time to create subfolders. We base it on our comfort level. Use a flatter structure until there is an obvious value (to help the rest of LIFT) in creating a new folder. - **为何？** 没有人愿意搜索7层目录来找一个文件。在目录结构中，没有硬数字公约，但是当目录有七到十个文件时，就是需要新建子目录的时候了。这是基于舒适级别来定的。以平坦结构未开始，在有很明显的需求是再新建目录（来配合其他LIFT公约） + **为何？**没有人愿意搜索7层目录来找一个文件。在目录结构中，没有硬数字约定，但是当目录有七到十个文件时，就是需要新建子目录的时候了。这是基于舒适级别而定的。以平面化结构开始，在有很明显的需求时再新建目录（来配合其他LIFT约定） a(href="#toc") Back to top @@ -1261,7 +1292,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### T-DRY (Try to be DRY) - ### T-DRY （尝试遵循不重复自己DRY的公约） + ### T-DRY（尝试遵循不重复自己DRY的约定） #### Style 04-05 #### 风格04-05 @@ -1270,19 +1301,19 @@ a(href="#toc") 回到顶部 :marked **Do** be DRY (Don't Repeat Yourself) - **坚持** 不要重复自己（DRY） + **坚持**不要重复自己（DRY） .s-rule.avoid :marked **Avoid** being so DRY that we sacrifice readability. - **避免** 过度DRY，以致牺牲了阅读性。 + **避免**过度DRY，以致牺牲了阅读性。 .s-why.s-why-last :marked **Why?** Being DRY is important, but not crucial if it sacrifices the others in LIFT, which is why we call it T-DRY. We don’t want to type `hero-view.component.html` for a view because, well, it’s obviously a view. If it is not obvious or by convention, then we name it. - **为何？** 虽然不重复自己公约很重要，但是如果要牺牲其他的LIFT公约，它就不是最重要的，这就是为什么我们说**尝试**不重复自己(T-DRY)。我们不愿意为了视图使用`hero-view.component.html`，因为它明显是一个试图。如果它不是很明显，那么我们就把视图单词加到它的名字里。 + **为何？**虽然不重复自己约定很重要，但是如果要牺牲其他的LIFT约定，它就不是最重要的，这就是为什么我们说**尝试**不重复自己(T-DRY)。我们不愿意为了视图使用`hero-view.component.html`，因为它很明显就是一个视图。如果它不是很明显，那么我们就把视图单词加到它的名字里。 a(href="#toc") Back to top @@ -1300,37 +1331,37 @@ a(href="#toc") 回到顶部 :marked **Do** start small but keep in mind where the app is heading down the road. - **坚持** 从零开始，但是时刻考虑应用程序接下来要走的路。 + **坚持**从零开始，但要时刻考虑应用程序接下来要走的路。 .s-rule.do :marked **Do** have a near term view of implementation and a long term vision. - **坚持** 有一个短期和一个长期的实施方案。 + **坚持**有一个短期和一个长期的实施方案。 .s-rule.do :marked **Do** put all of the app's code in a folder named `app`. - **坚持** 把所有源代码都放到名为`app`的目录里。 + **坚持**把所有源代码都放到名为`app`的目录里。 .s-rule.consider :marked **Consider** creating a folder for each component including its `.ts`, `.html`, `.css` and `.spec` file. - **考虑** 为每个组件新建一个目录，保存它的`.ts`, `.html`, `.css`, `.spec`等文件。 + **考虑**为每个组件新建一个目录，保存它的`.ts`,`.html`,`.css`,`.spec`等文件。 .s-why :marked **Why?** Helps us keep the app structure small and easy to maintain in the early stages, while being easy to evolve as the app grows. - **为何？**　帮助我们在早期保持应用结构精简和维护性，同时保证在应用程序成长的过程中，结构易于演化。 + **为何？**　帮助我们在早期保持应用结构的精简与可维护性，同时保证在应用程序成长的过程中，结构易于演化。 .s-why.s-why-last :marked **Why?** Components often have four files (e.g. `*.html`, `*.css`, `*.ts`, and `*.spec.ts`) and can clutter a folder quickly. - **为什么?** 组件经常有四个文件（例如`*.html`、 `*.css`、 `*.ts` 和 `*.spec.ts`），它们很容易把一个目录弄乱。 + **为何?**组件通常有四个文件（例如`*.html`、 `*.css`、 `*.ts` 和 `*.spec.ts`），它们很容易把一个目录弄乱。 .example-title Overall Folder and File Structure 整体目录和文件结构 .filetree @@ -1368,7 +1399,7 @@ a(href="#toc") 回到顶部 :marked While we prefer our Components to be in their own dedicated folder, another option for small apps is to keep Components flat (not in a dedicated folder). This adds up to four files to the existing folder, but also reduces the folder nesting. Be consistent. - 虽然我们比较喜欢把组件放到它自己独立的目录里面，但是对于很小应用来说，另一个选项是保持结构平坦（不在自己独立的目录里）。这样我们添加最多四个文件到一个已有的目录，但是同时减少的目录的嵌套。保持前后一致就好。 + 虽然我们比较喜欢把组件放到它自己独立的目录里面，但是对于很小应用来说，另一个选项是保持平面化结构（不在自己独立的目录里）。这样我们添加最多四个文件到一个已有的目录，但是同时减少的目录的嵌套。保持前后一致就好。 a(href="#toc") Back to top @@ -1387,25 +1418,25 @@ a(href="#toc") 回到顶部 :marked **Do** put all shared files within a component feature in a `shared` folder. - **坚持** 在单个特征范围内，把所有共享的文件放到`shared`目录。 + **坚持**在单个特性范围内，把所有共享的文件放到`shared`目录。 .s-rule.consider :marked **Consider** creating a folder for each component including its `.ts`, `.html`, `.css` and `.spec` file. - **考虑** 为每个组件新建一个目录，保存它的.ts`、`.html`、`.css`和`.spec` 文件。 + **考虑**为每个组件新建一个目录，保存它的`.ts`、`.html`、`.css`和`.spec` 文件。 .s-why :marked **Why?** Separates shared files from the components within a feature. - **为何？** 在一个特征范围内，分离出组件共享的文件。 + **为何？**在一个特性范围内，分离出组件共享的文件。 .s-why.s-why-last :marked **Why?** Makes it easier to locate shared files within a component feature. - **为何？** 使得在一个特征范围内，更加易于定位共享文件。 + **为何？**使得在一个特性范围内，更加易于定位共享文件。 .example-title Shared Folder 共享的目录 .filetree @@ -1451,7 +1482,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Folders-by-Feature Structure - ### 单特征目录结构 + ### 根据特性划分的目录结构 #### Style 04-08 #### 风格04-08 @@ -1460,31 +1491,31 @@ a(href="#toc") 回到顶部 :marked **Do** create folders named for the feature they represent. - **坚持** 把目录的名字命名为它包含的特征名字。 + **坚持**把目录的名字命名为它包含的特性名字。 .s-why :marked **Why?** A developer can locate the code, identify what each file represents at a glance, the structure is as flat as it can be, and there is no repetitive nor redundant names. - **为何？** 开发者能定位代码，一眼就能识别每个文件是干什么的，结构尽可能平坦，并且没有重复或者多余的名字。 + **为何？**开发者能定位代码，一眼就能看出每个文件是干什么的，结构尽可能平面化，并且没有重复或多余的名字。 .s-why :marked **Why?** The LIFT guidelines are all covered. - **为何？** 遵循LIFT指导原则。 + **为何？**遵循LIFT指导原则。 .s-why :marked **Why?** Helps reduce the app from becoming cluttered through organizing the content and keeping them aligned with the LIFT guidelines. - **为何？** 在管理应用内容时，帮助减少把程序结构弄的很杂乱的可能性，确保它们向LIFT指导原则看齐。 + **为何？**在管理应用内容时，帮助减少把程序结构弄得很杂乱的可能性，确保它们向LIFT指导原则看齐。 .s-why.s-why-last :marked **Why?** When there are a lot of files (e.g. 10+) locating them is easier with a consistent folder structures and more difficult in flat structures. - **为何？** 当有很多文件（10个以上）的时候，在一致的目录结构下面，比平坦结构下面定位它们容易的多。 + **为何？**当有很多文件（10个以上）的时候，在一致的目录结构下面，比在平面化结构下面定位它们要容易得多。 :marked Below is an example of a small app with folders per component. @@ -1551,25 +1582,25 @@ a(href="#toc") 回到顶部 :marked **Do** put components that define the overall layout in a `shared` folder. - **坚持** 把定义总体布局的组件放到`shared`目录。 + **坚持**把定义总体布局的组件放到`shared`目录。 .s-rule.do :marked **Do** put shared layout components in their own folder, under the `shared` folder. - **坚持** 把共享的布局组件放到`shared`目录下自己独立的目录里。 + **坚持**把共享的布局组件放到`shared`目录下它自己的独立目录里。 .s-why :marked **Why?** We need a place to host our layout for our app. Our navigation bar, footer, and other aspects of the app that are needed for the entire app. - **为何？** 我们需要一个地方来存放应用程序的布局，比如导航条、页脚和其他整个应用都需要的东西。 + **为何？**我们需要一个地方来存放应用程序的布局，比如导航条、页脚和其它整个应用中都需要的东西。 .s-why.s-why-last :marked **Why?** Organizes all layout in a consistent place re-used throughout the application. - **为何？** 在前后一致的地方管理所有布局，在整个应用程序范围内重复使用。 + **为何？**在前后一致的地方管理所有布局，在整个应用程序范围内重复使用。 .example-title Folder for Layout Components 布局组件目录 .filetree @@ -1615,31 +1646,31 @@ a(href="#toc") 回到顶部 :marked **Do** create a file that imports, aggregates, and re-exports items. We call this technique a **barrel**. - **坚持** 新建一个文件，用来导入、并集和再导出项目。该技巧被称作为**封装桶**。 + **坚持**新建一个文件，用来导入、归集和重新导出项目。该技巧被称作**封装桶**。 .s-rule.do :marked **Do** name this barrel file `index.ts`. - **坚持** 把该封装桶文件命名为`index.ts`。 + **坚持**把该封装桶文件命名为`index.ts`。 .s-why :marked **Why?** A barrel aggregates many imports into a single import. - **为何？** 封装桶把多个导入合并到一个单独的导入。 + **为何？**封装桶把多个导入合并成一个单独的导入。 .s-why :marked **Why?** A barrel reduces the number of imports a file may need. - **为何？** 封装桶减少文件可能需要导入的数量。 + **为何？**封装桶减少文件可能需要导入的数量。 .s-why.s-why-last :marked **Why?** A barrel shortens import statements. - **为何？** 封装桶精简了导入声明。 + **为何？**封装桶精简了导入声明。 +makeTabs( `style-guide/ts/04-10/app/shared/index.ts, @@ -1703,25 +1734,25 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Lazy Loaded Folders - ### 懒惰加载目录 + ### 惰性加载目录 #### Style 04-11 #### 风格04-11 A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts. - 一个独特的应用程序特征或者工作流程可能被**懒惰加载**或者**按需加载**，而非在应用程序启动时全部加载。 + 一个独特的应用程序特性或者工作流可能被**惰性加载**或**按需加载**，而非在应用程序启动时就全部加载。 .s-rule.do :marked **Do** put the contents of lazy loaded features in a *lazy loaded folder*. A typical *lazy loaded folder* contains a *routing component*, its child components, and their related assets and modules. - **坚持** 把懒惰加载特征的文件放到**懒惰加载目录**。典型的*懒惰加载目录*包含*路由组件*、子级组件和相关的东西和模块。 + **坚持**把惰性加载特性的文件放到**惰性加载目录**。典型的*惰性加载目录*中包含*路由组件*、子级组件和相关的东西和模块。 .s-why.s-why-last :marked **Why?** The folder makes it easy to identify and isolate the feature content. - **为何？** 该文件夹易于识别和隔离特征内容。 + **为何？**该文件夹易于识别和隔离特性内容。 a(href="#toc") Back to top @@ -1731,7 +1762,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Prefix Lazy Loaded Folders with + - ### 为懒惰加载目录名字加前缀+ + ### 为惰性加载目录名字加前缀+ #### Style 04-12 #### 风格04-12 @@ -1740,27 +1771,27 @@ a(href="#toc") 回到顶部 :marked **Do** prefix the name of a *lazy loaded folder* with a (+) e.g., `+dashboard/`. - **坚持** 使用一个(+)来前缀*懒惰加载目录*名字，比如`+dashboard/`。 + **坚持**使用一个(+)前缀来标记*惰性加载目录*名字，比如`+dashboard/`。 .s-why :marked **Why?** Lazy loaded code paths are easily identifiable by their `+` prefix. - **为何？** 通过前缀`+`，懒惰加载源代码可以很容易被识别。 + **为何？**通过`+`前缀，惰性加载的源代码可以很容易被识别。 .s-why :marked **Why?** Lazy loaded code paths are easily distinguishable from non lazy loaded paths. - **为什么？ 懒惰加载路径和非懒惰加载的路径很容易被区分开来。 + **为何？**惰性加载路径和非惰性加载的路径很容易被区分开来。 .s-why.s-why-last :marked **Why?** If we see an `import` path that contains a `+`, we can quickly refactor to use lazy loading. - **为何？** 如果看到包含`+`的`导入`路径，我们能快速重构，使用懒惰加载。 + **为何？**如果看到包含`+`的`import`路径，我们能快速使用惰性加载进行重构。 -.example-title Lazy Loaded Folders 懒惰加载目录 +.example-title Lazy Loaded Folders 惰性加载目录 .filetree .file src .children @@ -1779,7 +1810,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Never Directly Import Lazy Loaded Folders - ### 决不直接导入懒惰加载目录 + ### 决不直接导入惰性加载目录 #### Style 04-13 #### 风格 @@ -1788,13 +1819,13 @@ a(href="#toc") 回到顶部 :marked **Avoid** allowing modules in sibling and parent folders to directly import a module in a *lazy loaded feature*. - **避免** 允许姐妹或者父级目录里的模块直接导入*懒惰加载特征*模块。 + **避免**允许兄弟或者父目录里的模块直接导入*惰性加载特性*模块。 .s-why.s-why-last :marked **Why?** Directly importing a module loads it immediately when our intention is to load it on demand. - **为何？** 直接导入模块会立刻加载它，但是我们的原意是按需加载。 + **为何？**直接导入模块会立刻加载它，但是我们的原意是按需加载。 +makeExample('style-guide/ts/04-13/app/app.component.avoid.ts', 'example', 'app/app.component.ts')(avoid=1) :marked @@ -1806,7 +1837,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Lazy Loaded Folders May Import From a Parent - ### 懒惰加载目录可以导入父级 + ### 惰性加载目录可以导入父级 #### Style 04-14 #### 风格04-14 @@ -1815,13 +1846,13 @@ a(href="#toc") 回到顶部 :marked **Do** allow lazy loaded modules to import a module from a parent folder. - **坚持** 允许懒惰加载模块导入父级目录的模块。 + **坚持**允许惰性加载模块导入父级目录的模块。 .s-why.s-why-last :marked **Why?** A parent module has already been loaded by the time the lazy loaded module imports it. - **为何？** 在懒惰加载模块导入父级模块的时候，父级模块早已经被加载。 + **为何？**在惰性加载模块导入父级模块的时候，父级模块早已经被加载了。 +makeExample('style-guide/ts/04-14/app/heroes/heroes.component.ts', 'example', 'app/heroes/heroes.component.ts') :marked @@ -1834,7 +1865,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Use Component Router to Lazy Load - ### 使用组件路由器来懒惰加载 + ### 使用组件路由器来惰性加载 #### Style 04-15 #### 风格04-15 @@ -1843,13 +1874,13 @@ a(href="#toc") 回到顶部 :marked **Do** use the Component Router to lazy load routable features. - **坚持** 使用组件路由器来懒惰加载可以路由的特征。 + **坚持**使用组件路由器来惰性加载可以路由的特性。 .s-why.s-why-last :marked **Why?** That's the easiest way to load a module on demand. - **为何？** 这是最简单的按需加载模块的方法。 + **为何？**这是最简单的按需加载模块的方法。 a(href="#toc") Back to top @@ -1870,13 +1901,13 @@ a(href="#toc") 回到顶部 :marked **Do** use `kebab-case` for naming the element selectors of our components. - **坚持** 使用`烤串命名法`来命名组件的元素选择器。 + **坚持**使用`烤串命名法（中线命名法）`来命名组件的元素选择器。 .s-why.s-why-last :marked **Why?** Keeps the element names consistent with the specification for [Custom Elements](https://www.w3.org/TR/custom-elements/). - **为何？** 保持元素命名与[自定义元素](https://www.w3.org/TR/custom-elements/)命名规范一致。 + **为何？**保持元素命名与[自定义元素](https://www.w3.org/TR/custom-elements/)命名规范一致。 +makeExample('style-guide/ts/05-02/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1) :marked @@ -1905,25 +1936,25 @@ a(href="#toc") 回到顶部 :marked **Do** define Components as elements via the selector. - **坚持** 通过选择器来定义充当元素的组件。 + **坚持**通过选择器来定义充当元素的组件。 .s-why :marked **Why?** Components have templates containing HTML and optional Angular template syntax. They are most associated with putting content on a page, and thus are more closely aligned with elements. - **为何？** 组件有模板，包含HTML和可能有的Angular模板语法。它们大多数都是用来在页面上面放置内容的，所以与元素更加类似。 + **为何？**组件有模板，包含HTML和可能有的Angular模板语法。它们大多数都是用来在页面上面放置内容的，所以与元素更加类似。 .s-why :marked **Why?** Components are derived from Directives, and thus their selectors can be elements, attributes, or other selectors. Defining the selector as an element provides consistency for components that represent content with a template. - **为何？** 组件是从指令衍生的，所以它们的选择器可以是元素、特性或者其他选择器。把选择器当做元素来定义，统一了通过模块提供内容的组件。 + **为何？**组件是从指令衍生的，所以它们的选择器可以是元素、特性或者其他选择器。把选择器作为元素来定义，统一了通过模块提供内容的组件。 .s-why.s-why-last :marked **Why?** It is easier to recognize that a symbol is a component vs a directive by looking at the template's html. - **为何？** 查看组件是否有模板HTML文件，是最简单的识别一个符号是组件还是指令的方法。 + **为何？**查看组件是否有模板HTML文件，是最简单的识别一个符号是组件还是指令的方法。 +makeExample('style-guide/ts/05-03/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/hero-button/hero-button.component.ts')(avoid=1) :marked @@ -1946,7 +1977,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Extract Template and Styles to Their Own Files - ### 提取模板和样式到它们自己的文件 + ### 把模板和样式提取到它们自己的文件 #### Style 05-04 #### 风格05-04 @@ -1955,31 +1986,31 @@ a(href="#toc") 回到顶部 :marked **Do** extract templates and styles into a separate file, when more than 3 lines. - **坚持** 当超过三行的时候，提取模板和样式到一个单独的文件。 + **坚持**当超过三行的时候，把模板和样式提取到一个单独的文件。 .s-rule.do :marked **Do** name the template file `[component-name].component.html`, where [component-name] is our component name. - **坚持** 当组件名字为[component-name]的时候，命名它的模板为`[component-name].component.html`。 + **坚持**当组件名字为[component-name]的时候，命名它的模板为`[component-name].component.html`。 .s-rule.do :marked **Do** name the style file `[component-name].component.css`, where [component-name] is our component name. - **坚持** 当组件名字为[component-name]时，命名它的样式为`[component-name].component.css`。 + **坚持**当组件名字为[component-name]时，命名它的样式为`[component-name].component.css`。 .s-why :marked **Why?** Syntax hints for inline templates in (*.js and *.ts) code files are not supported by some editors. - **为何？** 在(*.js和*.ts)代码里面内嵌模板时，一些编辑器不支持语法提示。 + **为何？**在(*.js和*.ts)代码里面内联模板时，一些编辑器不支持语法提示。 .s-why.s-why-last :marked **Why?** A component file's logic is easier to read when not mixed with inline template and styles. - **为何？** 当没有与内嵌模板和样式混合的时候，组件文件里的逻辑更加易于阅读。 + **为何？**当没有与内联模板和样式混合的时候，组件文件里的逻辑更加易于阅读。 +makeExample('style-guide/ts/05-04/app/heroes/heroes.component.avoid.ts', 'example', 'app/heroes/heroes.component.ts')(avoid=1) :marked @@ -2002,7 +2033,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Decorate Input and Output Properties Inline - ### 内嵌Input和Output属性装饰 + ### 内联Input和Output属性装饰 #### Style 05-12 #### 风格05-12 @@ -2011,37 +2042,37 @@ a(href="#toc") 回到顶部 :marked **Do** use [`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html) and [`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html) instead of the `inputs` and `outputs` properties of the [`@Directive`](https://angular.io/docs/ts/latest/api/core/Directive-decorator.html) and [`@Component`](https://angular.io/docs/ts/latest/api/core/Component-decorator.html) decorators: - **坚持** 使用[`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html)和[`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html), 而非[`@Directive`](https://angular.io/docs/ts/latest/api/core/Directive-decorator.html) 和 [`@Component`](https://angular.io/docs/ts/latest/api/core/Component-decorator.html) 装饰器里面的`inputs`和`outputs`属性。 + **坚持**使用[`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html)和[`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html), 而非[`@Directive`](https://angular.io/docs/ts/latest/api/core/Directive-decorator.html) 和 [`@Component`](https://angular.io/docs/ts/latest/api/core/Component-decorator.html) 装饰器里面的`inputs`和`outputs`属性。 .s-rule.do :marked **Do** place the `@Input()` or `@Output()` on the same line as the property they decorate. - **坚持** 把`@Input()`或者`@Output()`放到它们装饰的属性的同一行。 + **坚持**把`@Input()`或者`@Output()`放到它们装饰的属性的同一行。 .s-why :marked **Why?** It is easier and more readable to identify which properties in a class are inputs or outputs. - **为何？** 这样易于在类里面识别哪个属性是inputs或outputs。 + **为何？**这样易于在类里面识别哪个属性是inputs或outputs。 .s-why :marked **Why?** If we ever need to rename the property or event name associated to [`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html) or [`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html) we can modify it on a single place. - **为何？** 如果我们需要重命名[`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html) 或 [`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html)关的属性或者事件，我们可以在一个地方修改。 + **为何？**如果我们需要重命名[`@Input`](https://angular.io/docs/ts/latest/api/core/Input-var.html) 或 [`@Output`](https://angular.io/docs/ts/latest/api/core/Output-var.html)关的属性或者事件，我们可以在一个地方修改。 .s-why :marked **Why?** The metadata declaration attached to the directive is shorter and thus more readable. - **为何？** 依附到指令的元数据声明会比较简短，更易于阅读。 + **为何？**依附到指令的元数据声明会比较简短，更易于阅读。 .s-why.s-why-last :marked **Why?** Placing the decorator on the same line makes for shorter code and still easily identifies the property as an input or output. - **为何？** 把装饰器放到同一行可以精简代码，同时更易于识别input或output属性。 + **为何？**把装饰器放到同一行可以精简代码，同时更易于识别输入或输出属性。 +makeExample('style-guide/ts/05-12/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1) :marked @@ -2056,7 +2087,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Avoid Renaming Inputs and Outputs - ### 避免重命名Inputs和Outputs + ### 避免重命名输入和输出 #### Style 05-13 #### 风格05-13 @@ -2065,13 +2096,13 @@ a(href="#toc") 回到顶部 :marked **Avoid** renaming inputs and outputs, when possible. - **避免** 重命名inputs和outputs。 + **避免**重命名输入和输出。 .s-why.s-why-last :marked **Why?** May lead to confusion when the output or the input properties of a given directive are named a given way but exported differently as a public API. - **为何？** 可能导致混乱，造成指令的output或input属性的名字和导出的公共API名字不一样。 + **为何？**可能导致混乱，造成指令的输入或输出属性的名字与导出的公共API名字不一样。 +makeExample('style-guide/ts/05-13/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1) :marked @@ -2104,19 +2135,19 @@ a(href="#toc") 回到顶部 :marked **Do** place properties up top followed by methods. - **坚持** 把属性成员放到顶部，方法成员紧跟。 + **坚持**把属性成员放到顶部，方法成员紧随其后。 .s-rule.do :marked **Do** place private members after public members, alphabetized. - **坚持** 按照字母顺序排列，先放公共成员，再放私有成员。 + **坚持**先放公共成员，再放私有成员，并按照字母顺序排列。 .s-why.s-why-last :marked **Why?** Placing members in a consistent sequence makes it easy to read and helps we instantly identify which members of the component serve which purpose. - **为何？** 使用一致的顺序放置成员，可以增加阅读性，并帮助我们立刻识别组件里面哪个成员是干什么的。 + **为何？**使用一致的顺序放置成员，可以增加阅读性，并帮助我们立刻识别出组件里面哪个成员是干什么的。 +makeExample('style-guide/ts/05-14/app/shared/toast/toast.component.avoid.ts', 'example', 'app/shared/toast/toast.component.ts')(avoid=1) :marked @@ -2140,37 +2171,37 @@ a(href="#toc") 回到顶部 :marked **Do** limit logic in a component to only that required for the view. All other logic should be delegated to services. - **坚持** 限制组件类的逻辑数量到只有视图需要的逻辑。所有其它逻辑都应该被放到服务。 + **坚持**把组件类中的逻辑限制到只有视图需要的逻辑。所有其它逻辑都应该被放到服务。 .s-rule.do :marked **Do** move reusable logic to services and keep components simple and focused on their intended purpose. - **坚持** 把可以重复使用的逻辑放到服务里，并保持组件简单并聚焦到它们预期目的。 + **坚持**把可以重复使用的逻辑放到服务里，保持组件简单并聚焦于它们预期目的。 .s-why :marked **Why?** Logic may be reused by multiple components when placed within a service and exposed via a function. - **为何？** 当逻辑被放置到服务里并以函数的形式暴露时，它可以被多个组件重复使用。 + **为何？**当逻辑被放置到服务里并以函数的形式暴露时，它可以被多个组件重复使用。 .s-why :marked **Why?** Logic in a service can more easily be isolated in a unit test, while the calling logic in the component can be easily mocked. - **为何？** 在单元测试时，服务里的逻辑更加容易被隔离。在组件里调用它的逻辑也很容易被模仿。 + **为何？**在单元测试时，服务里的逻辑更加容易被隔离。在组件里调用它的逻辑也很容易被模仿Mock。 .s-why :marked **Why?** Removes dependencies and hides implementation details from the component. - **为何？** 从组件移除依赖并隐藏实施细节。 + **为何？**从组件移除依赖并隐藏实施细节。 .s-why.s-why-last :marked **Why?** Keeps the component slim, trim, and focused. - **为何？** 保持组件苗条、精简和聚焦 + **为何？**保持组件苗条、精简和聚焦 +makeExample('style-guide/ts/05-15/app/heroes/hero-list/hero-list.component.avoid.ts', '', 'app/heroes/hero-list/hero-list.component.ts')(avoid=1) :marked @@ -2186,7 +2217,7 @@ a(href="#toc") 回到顶部 .l-main-section :marked ### Don't Prefix Output Properties - ### 不要前缀Outpu属性 + ### 不要给输出属性加前缀 #### Style 05-16 #### 风格05-16 @@ -2195,25 +2226,25 @@ a(href="#toc") 回到顶部 :marked **Do** name events without the prefix `on`. - **坚持** 命名事件时，不带前缀`on`。 + **坚持**命名事件时，不要带前缀`on`。 .s-rule.do :marked **Do** name our event handler methods with the prefix `on` followed by the event name. - **坚持** 命名事件处理方法时，带前缀`on`，紧跟事件名字。 + **坚持**命名事件处理方法时，带前缀`on`，紧跟事件名字。 .s-why :marked **Why?** This is consistent with built-in events such as button clicks. - **为何？** 与内建事件命名一致，比如按钮点击。 + **为何？**与内建事件命名一致，比如按钮点击。 .s-why.s-why-last :marked **Why?** Angular allows for an [alternative syntax](https://angular.io/docs/ts/latest/guide/template-syntax.html#!#binding-syntax) `on-*`. If the event itself was prefixed with `on` this would result in an `on-onEvent` binding expression. - **为什么？** Angular允许[可选语法](https://angular.io/docs/ts/latest/guide/template-syntax.html#!#binding-syntax) `on-*`。如果事件的名字本身带有前缀`on`，那么绑定的表达式可能是`on-onEvent`。 + **为何？**Angular允许[可选语法](https://angular.io/docs/ts/latest/guide/template-syntax.html#!#binding-syntax) `on-*`。如果事件的名字本身带有前缀`on`，那么绑定的表达式可能是`on-onEvent`。 +makeExample('style-guide/ts/05-16/app/heroes/hero.component.avoid.ts', 'example', 'app/heroes/hero.component.ts')(avoid=1) :marked @@ -2245,19 +2276,19 @@ a(href="#toc") 回到顶部 :marked **Do** put presentation logic in the Component class, and not in the template. - **坚持** 把展示逻辑放到组件类里，而非模板里。 + **坚持**把展示逻辑放到组件类里，而非模板里。 .s-why :marked **Why?** Logic will be contained in one place (the Component class) instead of being spread in two places. - **为何？** 所有逻辑都被放置到一个地方（组件类），而不被分离到两个地方。 + **为何？**所有逻辑都被放置到一个地方（组件类），而不被分离到两个地方。 .s-why.s-why-last :marked **Why?** Keeping the component's presentation logic in the class instead of the template improves testability, maintainability, and reusability. - **为何？** 将组件的展示逻辑放到组件类里而非模板里，可以增强测试性、维护性和重复使用性。 + **为何？**将组件的展示逻辑放到组件类而非模板里，可以增强测试性、维护性和重复使用性。 +makeExample('style-guide/ts/05-17/app/heroes/hero-list/hero-list.component.avoid.ts', 'example', 'app/heroes/hero-list/hero-list.component.ts')(avoid=1) :marked @@ -2266,6 +2297,7 @@ a(href="#toc") 回到顶部 :marked a(href="#toc") Back to top + a(href="#toc") 回到顶部 .l-main-section @@ -2290,19 +2322,19 @@ a(href="#toc") 回到顶部 :marked **Do** use attribute directives when you have presentation logic without a template. - **坚持** 当你需要有无模板的展示逻辑时，使用特征指令。 + **坚持**当你需要有无模板的展示逻辑时，使用Attribute指令。 .s-why :marked **Why?** Attributes directives don't have an associated template. - **为何？** 特征指令没有配套的模板。 + **为何？**Attribute指令没有配套的模板。 .s-why.s-why-last :marked **Why?** An element may have more than one attribute directive applied. - **为何？** 一个元素可能使用多个特征指令。 + **为何？**一个元素可能使用多个Attribute指令。 +makeExample('style-guide/ts/06-01/app/shared/highlight.directive.ts', 'example', 'app/shared/highlight.directive.ts') :marked @@ -2326,19 +2358,19 @@ a(href="#toc") 回到顶部 :marked **Do** use @HostListener and @HostBinding instead of the host property of the @Directive and @Component decorators: - **坚持** 使用@HostListener和@HostBinding，而非@Directive和@Component装饰器的宿主属性。 + **坚持**使用@HostListener和@HostBinding，而非@Directive和@Component装饰器的宿主属性。 .s-why :marked **Why?** The property or method name associated with @HostBinding or respectively @HostListener should be modified only in a single place - in the directive's class. In contrast if we use host we need to modify both the property declaration inside the controller, and the metadata associated to the directive. - **为何？** 与属性或方法名字相关联的@HostBinding或者@HostListener应该只在一个地方被修改：在指令的类里。反过来，如果我们使用宿主属性，我们需要在控制器内修改属性声明，然后在指令相关的元数据里修改。 + **为何？**与属性或方法名字相关联的@HostBinding或者@HostListener应该只在一个地方被修改：在指令的类里。反过来，如果我们使用宿主属性，我们需要在控制器内修改属性声明，然后在指令相关的元数据里修改。 .s-why.s-why-last :marked **Why?** The metadata declaration attached to the directive is shorter and thus more readable. - **为何？** 指令附带的元数据声明会简短一些，易于阅读。 + **为何？**指令附带的元数据声明会简短一些，易于阅读。 +makeExample('style-guide/ts/06-03/app/shared/validate.directive.avoid.ts', 'example', 'app/shared/validate.directive.ts')(avoid=1) :marked @@ -2365,19 +2397,19 @@ a(href="#toc") 回到顶部 :marked **Do** use services as singletons within the same injector. Use them for sharing data and functionality. - **坚持** 在同一个注入器内，把服务当做单例使用。使用它们来共享数据和功能。 + **坚持**在同一个注入器内，把服务当做单例使用。使用它们来共享数据和功能。 .s-why :marked **Why?** Services are ideal for sharing methods across a feature area or an app. - **为何？** 服务是在一个特性范围或一个应用内理想的共享函数方法的理想载体。 + **为何？**服务是在一个特性范围或一个应用内理想的共享函数方法的理想载体。 .s-why.s-why-last :marked **Why?** Services are ideal for sharing stateful in-memory data. - **为何？** 服务是共享状态性内存数据的理想方法。 + **为何？**服务是共享状态性内存数据的理想方法。 +makeExample('style-guide/ts/07-01/app/heroes/shared/hero.service.ts', 'example', 'app/heroes/shared/hero.service.ts') :marked @@ -2398,25 +2430,25 @@ a(href="#toc") 回到顶部 :marked **Do** create services with a single responsibility that is encapsulated by its context. - **坚持** 新建单一职责的服务，把它封装在自己的环境内。 + **坚持**新建单一职责的服务，把它封装在自己的环境内。 .s-rule.do :marked **Do** create a new service once the service begins to exceed that singular purpose. - **坚持** 当服务成长到超出一个用意时，新建一个服务。 + **坚持**当服务成长到超出单一用途时，新建一个服务。 .s-why :marked **Why?** When a service has multiple responsibilities, it becomes difficult to test. - **为何？** 当服务有多个职责时，它很难被测试。 + **为何？**当服务有多个职责时，它很难被测试。 .s-why.s-why-last :marked **Why?** When a service has multiple responsibilities, every Component or Service that injects it now carries the weight of them all. - **为何？** 当服务有多个职责时，每个注入它的组件或者服务都会被迫承担它们的（多个职责）所有的重量。 + **为何？**当服务有多个职责时，每个注入它的组件或者服务都会被迫承担它们的（多个职责）所有的重量。 a(href="#toc") Back to top @@ -2434,30 +2466,30 @@ a(href="#toc") 回到顶部 :marked **Do** provide services to the Angular 2 injector at the top-most component where they will be shared. - **坚持** 在被共享范围内的顶级组件里，将服务提供到Angular 2的注入器里。 + **坚持**在被共享范围内的顶级组件里，将服务提供到Angular 2的注入器里。 .s-why :marked **Why?** The Angular 2 injector is hierarchical. - **为何？** Angular 2注入器是层次性的。 + **为何？**Angular 2注入器是层次性的。 .s-why :marked **Why?** When providing the service to a top level component, that instance is shared and available to all child components of that top level component. - **为何？** 在顶层组件提供服务时，该服务实例在所有该顶级组件的子级组件中能见并共享。 + **为何？**在顶层组件提供服务时，该服务实例在所有该顶级组件的子级组件中可见并共享。 .s-why :marked **Why?** This is ideal when a service is sharing methods or state. - **为何？** 服务共享函数方法或状态的理想方法。 + **为何？**服务是共享函数方法或状态的理想方法。 .s-why.s-why-last :marked **Why?** This is not ideal when two different components need different instances of a service. In this scenario it would be better to provide the service at the component level that needs the new and separate instance. - **为何？** 当不同的两个组件需要一个服务的不同的实例时，上面的方法这就不理想了。在这种情况下，我们最好在需要崭新和单独服务实例的组件里提供服务。 + **为何？**当不同的两个组件需要一个服务的不同的实例时，上面的方法这就不理想了。在这种情况下，我们最好在需要崭新和单独服务实例的组件里提供服务。 +makeTabs( `style-guide/ts/07-03/app/app.component.ts, @@ -2483,19 +2515,19 @@ a(href="#toc") 回到顶部 :marked **Do** use the `@Injectable` class decorator instead of the `@Inject` parameter decorator when using types as tokens for the dependencies of a service. - **坚持** 当使用类型作为令牌来注入服务的依赖时，使用`@Injectable`类装饰器，而非`@Inject`参数装饰器。 + **坚持**当使用类型作为Token来注入服务的依赖时，使用`@Injectable`类装饰器，而非`@Inject`参数装饰器。 .s-why :marked **Why?** The Angular DI mechanism resolves all the dependencies of our services based on their types declared with the services' constructors. - **为何？** Angular的依赖注入机制，是根据在服务的构造函数里面的类型的声明，来解析所有服务的依赖的。 + **为何？**Angular的依赖注入机制，是根据在服务的构造函数里面的类型的声明，来解析所有服务的依赖的。 .s-why.s-why-last :marked **Why?** When a service accepts only dependencies associated with type tokens, the `@Injectable()` syntax is much less verbose compared to using `@Inject()` on each individual constructor parameter. - **为何？** 当服务只接受类型令牌相关的依赖时，比起在每个构造函数参数上使用`@Inject()`，`@Injectable()`的语法简洁多了。 + **为何？**当服务只接受类型Token相关的依赖时，比起在每个构造函数参数上使用`@Inject()`，`@Injectable()`的语法简洁多了。 +makeExample('style-guide/ts/07-04/app/heroes/shared/hero-arena.service.avoid.ts', 'example', 'app/heroes/shared/hero-arena.service.ts')(avoid=1) :marked @@ -2522,31 +2554,31 @@ a(href="#toc") 回到顶部 :marked **Do** refactor logic for making data operations and interacting with data to a service. - **坚持** 把数据操作和数据互动重构到服务里。 + **坚持**把数据操作和数据互动重构到服务里。 .s-rule.do :marked **Do** make data services responsible for XHR calls, local storage, stashing in memory, or any other data operations. - **坚持** 让数据服务来负责XHR调用、本地储存、内存储存或者其他数据操作。 + **坚持**让数据服务来负责XHR调用、本地储存、内存储存或者其他数据操作。 .s-why :marked **Why?** The component's responsibility is for the presentation and gathering of information for the view. It should not care how it gets the data, just that it knows who to ask for it. Separating the data services moves the logic on how to get it to the data service, and lets the component be simpler and more focused on the view. - **为何？** 组件的职责是为视图展示或收集信息。它应该不用理会如何得到数据，它只知道向谁要数据。把如何取得数据的逻辑移动到数据服务里，简化了组件，让其聚焦到视图。 + **为何？**组件的职责是为视图展示或收集信息。它不应该理会如何得到数据，它只需要知道向谁要数据。把如何取得数据的逻辑移动到数据服务里，简化了组件，让其聚焦于视图。 .s-why :marked **Why?** This makes it easier to test (mock or real) the data calls when testing a component that uses a data service. - **为何？** 在测试使用数据服务的组件时，可以让数据调用更容易被测试（模仿或者真实）。 + **为何？**在测试使用数据服务的组件时，可以让数据调用更容易被测试（模仿或者真实）。 .s-why.s-why-last :marked **Why?** Data service implementation may have very specific code to handle the data repository. This may include headers, how to talk to the data, or other services such as `Http`. Separating the logic into a data service encapsulates this logic in a single place hiding the implementation from the outside consumers (perhaps a component), also making it easier to change the implementation. - **为何？** 数据服务的实施可能有非常特定的代码来处理数据仓库，包括数据头（headers）、如何与数据交谈或者其他服务（比如`Http`)。把逻辑分离到数据服务可以把该逻辑封装到一个地方，对外部使用者（比如组件）隐藏具体的实施细节。 + **为何？**数据服务的实现可能有非常具体的代码来处理数据仓库，包括数据头（headers）、如何与数据交谈或者其他服务（比如`Http`)。把逻辑分离到数据服务可以把该逻辑封装到一个地方，对外部使用者（比如组件）隐藏具体的实施细节。 a(href="#toc") Back to top @@ -2560,7 +2592,7 @@ a(href="#toc") 回到顶部 Use Lifecycle Hooks to tap into important events exposed by Angular. - 使用生命周期钩子来插入到Angular暴露的重要事件里。 + 使用生命周期钩子来介入到Angular暴露的重要事件里。 a(href="#toc") Back to top @@ -2576,13 +2608,13 @@ a(href="#toc") Back to top :marked **Do** implement the lifecycle hook interfaces. - **坚持** 实现生命周期钩子的接口。 + **坚持**实现生命周期钩子接口。 .s-why.s-why-last :marked **Why?** We avoid unintentionally not calling the hook if we misspell the method. - **为何？** 避免在方法名字拼写错误时，造成无意间没有调用钩子的可能。 + **为何？**避免在方法名字拼写错误时，造成无意间没有调用钩子的可能。 +makeExample('style-guide/ts/09-01/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1) :marked @@ -2601,7 +2633,7 @@ a(href="#toc") 回到顶部 Client-side routing is important for creating a navigation flow between a component tree hierarchy, and composing components that are made of many other child components. - 在组件树阶层间创建导航流和并集多个子级组件时，客户端路由很重要。 + 在组件树层级间创建导航流和组合多个子组件时，客户端路由很重要。 a(href="#toc") Back to top @@ -2619,37 +2651,37 @@ a(href="#toc") 回到顶部 :marked **Do** separate route configuration into a routing component file, also known as a component router. - **坚持** 分离路由设置到一个路由组件文件，也叫作组件路由器。 + **坚持**分离路由设置到一个路由组件文件，也叫作组件路由器。 .s-rule.do :marked **Do** use a `` in the component router, where the routes will have their component targets display their templates. - **坚持** 在组件路由器里使用一个``，标识路由的组件在哪儿显示它们模板。 + **坚持**在组件路由器里使用一个``，来告诉路由组件在哪儿显示它们模板。 .s-rule.do :marked **Do** focus the logic in the component router to the routing aspects and its target components. - **坚持** 把组件路由器的逻辑聚焦到路由方面和它的目标组件。 + **坚持**把组件路由器的逻辑聚焦于路由和它的目标组件方面。 .s-rule.do :marked **Do** extract other logic to services and other components. - **坚持** 把其他逻辑分离到服务或者其他组件里。 + **坚持**把其它逻辑分离到服务或者其他组件里。 .s-why :marked **Why?** A component that handles routing is known as the component router, thus this follows the Angular 2 routing pattern. - *为何？** 处理路由的组件被称作组件路由器，它遵循Angular 2的路由模式。 + *为何？**处理路由的组件被称作组件路由器，它遵循Angular 2的路由模式。 .s-why.s-why-last :marked **Why?** The `` indicates where the template should be displayed for the target route. - **为何？** ``标识目标路由组件应该在哪儿显示它们的模板。 + **为何？**``标识目标路由组件应该在哪儿显示它们的模板。 +makeExample('style-guide/ts/10-01/app/app.component.ts', '', 'app/app.component.ts') :marked @@ -2683,13 +2715,13 @@ a(href="#toc") 回到顶部 :marked **Do** use [codelyzer](https://www.npmjs.com/package/codelyzer) to follow this guide. - **坚持** 使用[codelyzer](https://www.npmjs.com/package/codelyzer)来实施本指南。 + **坚持**使用[codelyzer](https://www.npmjs.com/package/codelyzer)来实施本指南。 .s-rule.consider :marked **Consider** adjusting the rules in codelyzer to suit your needs. - **考虑** 调整codelyzer的规则来满足你的需求。 + **考虑**调整codelyzer的规则来满足你的需求。 a(href="#toc") Back to top @@ -2707,13 +2739,13 @@ a(href="#toc") 回到顶部 :marked **Do** use file templates or snippets to help follow consistent styles and patterns. Here are templates and/or snippets for some of the web development editors and IDEs. - **坚持** 使用文件模板或代码片段来帮助实现一致的风格和模式。下面是为一些网络开发编辑器和IDE准备的模板和/或代码片段： + **坚持**使用文件模板或代码片段来帮助实现一致的风格和模式。下面是为一些网络开发编辑器和IDE准备的模板和/或代码片段： .s-rule.consider :marked **Consider** using [snippets](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2) for [Visual Studio Code](https://code.visualstudio.com/) that follow these styles and guidelines. - **考虑** 使用[Visual Studio Code](https://code.visualstudio.com/)的[代码片段](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2)来实施本风格指南。 + **考虑**使用[Visual Studio Code](https://code.visualstudio.com/)的[代码片段](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2)来实施本风格指南。 :marked [![Use Extension](https://github.com/johnpapa/vscode-angular2-snippets/raw/master/images/use-extension.gif)](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2) From fd69ea327004b1093422fce1b6403310b9844964 Mon Sep 17 00:00:00 2001 From: Zhicheng Wang Date: Mon, 16 May 2016 23:15:02 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E6=8A=8A=E9=83=A8=E5=88=86expose=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E8=AF=91=E4=B8=BA=E6=9A=B4=E9=9C=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- public/docs/ts/latest/cookbook/component-communication.jade | 2 +- public/docs/ts/latest/cookbook/set-document-title.jade | 2 +- public/docs/ts/latest/tutorial/toh-pt2.jade | 2 +- public/docs/ts/latest/tutorial/toh-pt5.jade | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/public/docs/ts/latest/cookbook/component-communication.jade b/public/docs/ts/latest/cookbook/component-communication.jade index 68e6708ff6..33358e1b27 100644 --- a/public/docs/ts/latest/cookbook/component-communication.jade +++ b/public/docs/ts/latest/cookbook/component-communication.jade @@ -202,7 +202,7 @@ figure.image-display 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`属性，当事情发生时，子级组件利用该属性`散发`事件。父级绑定这个事件属性，并在事件发生时作出回应。 + 子级组件暴露一个`EventEmitter`属性，当事情发生时，子级组件利用该属性`emits`事件。父级绑定这个事件属性，并在事件发生时作出回应。 The child's `EventEmitter` property is an ***output property***, typically adorned with an [@Output decoration](../guide/template-syntax.html#inputs-outputs) as seen in this `VoterComponent`: diff --git a/public/docs/ts/latest/cookbook/set-document-title.jade b/public/docs/ts/latest/cookbook/set-document-title.jade index f3dd6885c1..21399f5a7b 100644 --- a/public/docs/ts/latest/cookbook/set-document-title.jade +++ b/public/docs/ts/latest/cookbook/set-document-title.jade @@ -88,7 +88,7 @@ code-example(format='') Let's inject the `Title` service into the root `AppComponent` and expose a bindable `setTitle` method that calls it: - 让我们把`Title`服务注入到根`AppComponent`组件，并暴漏可以绑定的`setTitle`方法来调用该服务： + 让我们把`Title`服务注入到根`AppComponent`组件，并暴露可以绑定的`setTitle`方法来调用该服务： +makeExample( "cb-set-document-title/ts/app/app.component.ts", "class", "app/app.component.ts (class)" )(format='.') :marked diff --git a/public/docs/ts/latest/tutorial/toh-pt2.jade b/public/docs/ts/latest/tutorial/toh-pt2.jade index 752a41abb7..8c72b5d3fe 100644 --- a/public/docs/ts/latest/tutorial/toh-pt2.jade +++ b/public/docs/ts/latest/tutorial/toh-pt2.jade @@ -85,7 +85,7 @@ code-example(format="." language="bash"). ### 导出英雄们 Let’s create a property in `AppComponent` that exposes the heroes for binding. - 我们在`AppComponent`上创建一个属性，用来导出这些英雄，以供绑定。 + 我们在`AppComponent`上创建一个属性，用来暴露这些英雄，以供绑定。 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'hero-array-1', 'app.component.ts (英雄数组属性)') diff --git a/public/docs/ts/latest/tutorial/toh-pt5.jade b/public/docs/ts/latest/tutorial/toh-pt5.jade index bce990c11c..f46baf0c16 100644 --- a/public/docs/ts/latest/tutorial/toh-pt5.jade +++ b/public/docs/ts/latest/tutorial/toh-pt5.jade @@ -169,7 +169,7 @@ code-example(format="." language="bash"). * `export` it so we can reference it during bootstrapping in `main.ts`. * `export`它，以便我们能在`main.ts`的启动期间引用它。 * expose an application `title` property. - * 导出应用的`title`属性。 + * 暴露应用的`title`属性。 * add the `@Component` metadata decorator above the class with a `my-app` selector. * 在类的上方添加`@Component`元数据装饰器，装饰器中带有`my-app`选择器。 * add a template with `

` tags surrounding a binding to the `title` property.