angular-cn/public/docs/ts/latest/guide/upgrade.jade

include ../_util-fns

:marked
  Having an existing Angular 1 application doesn't mean that we can't
  begin enjoying everything Angular 2 has to offer. That's because Angular 2
  comes with built-in tools for migrating Angular 1 projects over to the
  Angular 2 platform.

  已经有了一个Angular 1的程序并不表示我们就不能喜欢Angular 2提供的一切。
  这是因为Angular 2带来了一些内建工具帮助我们把Angular 1的项目迁移到Angular 2平台。

  Some applications will be easier to upgrade than others, and there are
  ways in which we can make it easier for ourselves. It is possible to
  prepare and align Angular 1 applications with Angular 2 even before beginning
  the upgrade process. These preparation steps are all about making the code
  more decoupled, more maintainable, and up to speed with modern development
  tools. That means the preparation work will not only make the eventual upgrade
  easier, but will also generally improve our Angular 1 applications.

  有些应用可能比其它的升级起来简单，还有一些方法能让我们自己把这项工作变得更简单。
  即使在正式开始升级过程之前，让Angular 1的程序提前做些准备，并向Angular 2看齐也是有可能的。
  这些准备步骤几乎都是关于如何让代码更加松耦合、更有可维护性，以及用现代开发工具提高速度的。
  这意味着，这种准备工作不仅能让最终的升级变得更简单，而且还能提升Angular 1程序的质量。

  One of the keys to a successful upgrade is to do it incrementally,
  by running the two frameworks side by side in the same application, and
  porting Angular 1 components to Angular 2 one by one. This makes it possible
  to upgrade even large and complex applications without disrupting other
  business, because the work can be done collaboratively and spread over
  a period of time. The `upgrade` module in Angular 2 has been designed to
  make incremental upgrading seamless.

  成功升级的关键之一是增量式的实现它，通过在同一个应用中一起运行这两个框架，并且逐个把Angular 1的组件迁移到Angular 2中。
  这意味着可以在不必打断其他业务的前提下，升级更大、更复杂的应用程序，因为这项工作可以多人协作完成，并能在一段时间内逐渐铺开。
  Angular 2 `upgrade`模块的设计目标就是让你渐进、无缝的完成升级。

  1. [Preparation](#preparation)
  1. [准备工作](#preparation)
      1. [Following The Angular Style Guide](#following-the-angular-style-guide)
      1. [遵循Angular风格指南](#following-the-angular-style-guide)
      2. [Using a Module Loader](#using-a-module-loader)
      2. [使用模块加载器](#using-a-module-loader)
      3. [Migrating to TypeScript](#migrating-to-typescript)
      3. [迁移到TypeScript](#migrating-to-typescript)
      4. [Using Component Directives](#using-component-directives)
      4. [使用组件型指令](#using-component-directives)
  2. [Upgrading with The Upgrade Adapter](#upgrading-with-the-upgrade-adapter)
  2. [通过升级适配器进行升级](#upgrading-with-the-upgrade-adapter)
      1. [How The Upgrade Adapter Works](#how-the-upgrade-adapter-works)
      1. [升级适配器如何工作](#how-the-upgrade-adapter-works)
      2. [Bootstrapping Hybrid Angular 1+2 Applications](#bootstrapping-hybrid-angular-1-2-applications)
      2. [引导Angular 1和2的混合(hybrid)应用](#bootstrapping-hybrid-angular-1-2-applications)
      3. [Using Angular 2 Components from Angular 1 Code](#using-angular-2-components-from-angular-1-code)
      3. [从Angular 1的代码中使用Angular 2的组件](#using-angular-2-components-from-angular-1-code)
      4. [Using Angular 1 Component Directives from Angular 2 Code](#using-angular-1-component-directives-from-angular-2-code)
      4. [从Angular 2的代码中使用Angular 1的组件](#using-angular-1-component-directives-from-angular-2-code)
      5. [Projecting Angular 1 Content into Angular 2 Components](#projecting-angular-1-content-into-angular-2-components)
      5. [把Angular 1的内容投影(project)进Angular 2组件中](#projecting-angular-1-content-into-angular-2-components)
      6. [Transcluding Angular 2 Content into Angular 1 Component Directives](#transcluding-angular-2-content-into-angular-1-component-directives)
      6. [把Angular 2的内容透传(transclude)到Angular 1的组件型指令中](#transcluding-angular-2-content-into-angular-1-component-directives)
      7. [Making Angular 1 Dependencies Injectable to Angular 2](#making-angular-1-dependencies-injectable-to-angular-2)
      7. [让Angular 1提供的依赖可以被注入到Angular 2](#making-angular-1-dependencies-injectable-to-angular-2)
      8. [Making Angular 2 Dependencies Injectable to Angular 1](#making-angular-2-dependencies-injectable-to-angular-1)
      8. [让Angular 2提供的依赖可以被注入到Angular 1](#making-angular-2-dependencies-injectable-to-angular-1)
  3. [PhoneCat Preparation Tutorial](#phonecat-preparation-tutorial)
  3. [PhoneCat准备工作教程](#phonecat-preparation-tutorial)
      1. [Switching to TypeScript And Module Loading](#switching-to-typescript-and-module-loading)
      1. [切换到TypeScript和模块加载器](#switching-to-typescript-and-module-loading)
      2. [Preparing Unit and E2E Tests](#preparing-unit-and-e2e-tests)
      2. [准备单元测试和E2E测试](#preparing-unit-and-e2e-tests)
      3. [Enjoying The Benefits of TypeScript](#enjoying-the-benefits-of-typescript)
      3. [享受TypeScript带来的好处](#enjoying-the-benefits-of-typescript)

  4. [PhoneCat Upgrade Tutorial](#phonecat-upgrade-tutorial)
  4. [PhoneCat升级教程](#phonecat-upgrade-tutorial)
      1. [Bootstrapping A Hybrid 1+2 PhoneCat](#bootstrapping-a-hybrid-1-2-phonecat)
      1. [引导Angular 1+2的混合版PhoneCat](#bootstrapping-a-hybrid-1-2-phonecat)
      2. [Upgrading the Phone factory](#upgrading-the-phone-factory)
      2. [升级Phone工厂](#upgrading-the-phone-factory)
      3. [Upgrading Controllers to Components](#upgrading-controllers-to-components)
      3. [把控制器升级为组件](#upgrading-controllers-to-components)
      4. [Switching To The Angular 2 Router And Bootstrap](#switching-to-the-angular-2-router-and-bootstrap)
      4. [切换到Angular 2的路由器并引导](#switching-to-the-angular-2-router-and-bootstrap)
      5. [Saying Goodbye to Angular 1](#saying-goodbye-to-angular-1)
      5. [再见，Angular 1！](#saying-goodbye-to-angular-1)

.l-main-section
:marked
  # Preparation
  # 准备工作

  There are many ways to structure Angular 1 applications. When we begin
  to upgrade these applications to Angular 2, some will turn out to be
  much more easy to work with than others. There are a few key techniques
  and patterns that we can apply to future proof our apps even before we
  begin the migration.

  Angular 1应用程序的组织方式有很多种。当我们想把它们升级到Angular 2的时候，
  有些做起来会比其它的更容易些。即使在我们开始升级之前，也有一些关键的技术和模式可以让我们将来升级时更轻松。

  ## Following The Angular Style Guide
  ## 遵循Angular风格指南

  The [Angular Style Guide](https://github.com/johnpapa/angular-styleguide)
  collects patterns and practices that have been proven to result in
  cleaner and more maintainable Angular 1 applications. It contains a wealth
  of information about how to write and organize Angular code - and equally
  importantly - how **not** to write and organize Angular code.

  [Angular风格指南](https://github.com/johnpapa/angular-styleguide)收集了一些
  已证明能写出干净且可维护的Angular 1程序的模式与实践。
  它包含了很多关于如何书写和组织Angular代码的有价值信息，同样重要的是，**不应该**如何书写和组织Angular代码。

  Angular 2 is a reimagined version of the best parts of Angular 1. In that
  sense, its goals are the same as the Angular Style Guide's: To preserve
  the good parts of Angular 1, and to avoid the bad parts. There's a lot
  more to Angular 2 than just that of course, but this does mean that
  *following the style guide helps make your Angular 1 app more closely
  aligned with Angular 2*.

  Angular 2是一个基于Angular 1中最好的部分构思出来的版本。在这种意义上，它的目标和Angular风格指南是一样的：
  保留Angular 1中好的部分，去掉坏的部分。当然，Angular 2还做了更多。
  说这些的意思是：*遵循这个风格指南可以让你写出的Angular 1程序更接近Angular 2程序*。

  There are a few rules in particular that will make it much easier to do
  *an incremental upgrade* using the Angular 2 `upgrade` module:

  特别是某些规则会让使用Angular 2的`upgrade`模块进行*增量升级*变得更简单：

  * The [Rule of 1](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility)
    states that there should be one component per file. This not only makes
    components easy to navigate and find, but will also allow us to migrate
    them between languages and frameworks one at a time. In this example application,
    each controller, factory, and filter is in its own source file.

  * [规则1](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility)
    规定应该每个文件中放一个组件。这不仅让组件更容易浏览和查找，而且还将允许我们逐个迁移它们的语言和框架。
    在这个范例程序中，每个控制器、工厂和过滤器都在它自己的源文件中。

  * The [Folders-by-Feature Structure](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#folders-by-feature-structure)
    and [Modularity](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#modularity)
    rules define similar principles on a higher level of abstraction: Different parts of the
    application should reside in different directories and Angular modules.

  * [按特性分目录的结构](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#folders-by-feature-structure)
    和[模块化](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#modularity)
    规则在较高的抽象层定义了一些相似的原则：应用程序中的不同部分应该被分到不同的目录和Angular模块中。

  When an application is laid out feature per feature in this way, it can also be
  migrated one feature at a time. For applications that don't already look like
  this, applying the rules in the Angular style guide is a highly recommended
  preparation step. And this is not just for the sake of the upgrade - it is just
  solid advice in general!

  如果应用程序能用这种方式把每个特性分到一个独立目录中，它也就能每次迁移一个特性。
  对于那些还没有这么做的程序，强烈建议把应用这条规则作为准备步骤。而且这也不仅仅对升级有价值，
  它还是一个通用的规则，可以让你的程序更“坚实”。

  ## Using a Module Loader
  ## 使用模块加载器

  When we break application code down into one component per file, we often end
  up with a project structure with a large number of relatively small files. This is
  a much neater way to organize things than a small number of large files, but it
  doesn't work that well if you have to load all those files to the HTML page with
  `<script>` tags. Especially when you also have to maintain those tags in the correct
  order. That's why it's a good idea to start using a *module loader*.

  当我们把应用代码分解成每个文件中放一个组件之后，我们通常会得到一个由大量相对较小的文件组成的项目结构。
  这比组织成少量大文件要整洁得多，但如果你不得不通过`<script>`标签在HTML页面中加载所有这些文件，那就不好玩儿了。
  尤其是当你不得不按正确的顺序维护这些标签时更是如此。
  这就是为什么开始使用*模块加载器*是一个好主意了。

  Using a module loader such as [SystemJS](https://github.com/systemjs/systemjs),
  [Webpack](http://webpack.github.io/), or [Browserify](http://browserify.org/)
  allows us to use the built-in module systems of the TypeScript or ES2015 languages in our apps.
  We can use the `import` and `export` features that explicitly specify what code can
  and will be shared between different parts of the application. For ES5 applications
  we can use CommonJS style `require` and `module.exports` features. In both cases,
  the module loader will then take care of loading all the code the application needs
  in the correct order.

  使用模块加载器，比如[SystemJS](https://github.com/systemjs/systemjs)、
  [Webpack](http://webpack.github.io/)或[Browserify](http://browserify.org/)，
  可以让我们在程序中使用TypeScript或ES2015语言内置的模块系统。
  我们可以使用`import`和`export`特性来明确指定哪些代码应该以及将会被在程序的不同部分之间共享。
  对于ES5程序来说，我们可以改用CommonJS风格的`require`和`module.exports`特性代替。
  无是论哪种情况，模块加载器都会按正确的顺序加载程序中用到的所有代码。

  When we then take our applications into production, module loaders also make it easier
  to package them all up into production bundles with batteries included.

  当我们的应用程序投入生产环境时，模块加载器也会让把所有这些文件打成完整的产品包变得更容易。

:marked
  ## Migrating to TypeScript
  ## 迁移到TypeScript

  If part of our Angular 2 upgrade plan is to also take TypeScript into use, it makes
  sense to bring in the TypeScript compiler even before the upgrade itself begins.
  This means there's one less thing to learn and think about during the actual upgrade.
  It also means we can start using TypeScript features in our Angular 1 code.

  Angular 2升级计划的一部分是引入TypeScript，即使在开始升级之前，引入TypeScript编译器也是有意义的。
  这意味着等真正升级的时候需要学习和思考的东西更少。
  它还意味着我们可以在Angular 1代码中开始使用TypeScript的特性。

  Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset
  of ECMAScript 5, "switching" to TypeScript doesn't necessarily require anything
  more than installing the TypeScript compiler and switching renaming files from
  `*.js` to `*.ts`. But just doing that is not hugely useful or exciting, of course.
  Additional steps like the following can give us much more bang for the buck:

  因为TypeScript是ECMAScript 2015的一个超集，而ES2015又是ECMAScript 5的一个超集。
  这意味着除了安装一个TypeScript编译器，并把文件名都从`*.js`改成`*.ts`之外，其实什么都不用做。
  当然，如果仅仅这样做也没什么大用，也没什么令人兴奋之处。
  下面这些额外步骤可以让我们抖擞起精神来：

  * For applications that use a module loader, TypeScript imports and exports
    (which are really ECMAScript 2015 imports and exports) can be used to organize
    code into modules.

  * 对那些使用了模块加载器的程序，TypeScript的导入和导出(这实际上是ECMAScript 2015导入和导出)可以把代码组织到模块中。

  * Type annotations can be gradually added to existing functions and variables
    to pin down their types and get benefits like build-time error checking,
    great autocompletion support and inline documentation.

  * 类型注解可以逐步添加到已存在的函数和变量上，以固定它们的类型，并获得其优点：比如编译期错误检查、更好的支持自动完成，以及内联式文档等。

  * JavaScript features new to ES2015, like `let`s and `const`s, default function
    parameters, and destructuring assignments can also be gradually added to make
    the code more expressive.

  * 那些ES2015中新增的特性，比如`let`、`const`、默认函数参数、解构赋值等也能逐渐添加进来，让代码更有表现力。

  * Services and controllers can be turned into *classes*. That way they'll be a step
    closer to becoming Angular 2 service and component classes, which will make our
    life easier once we do the upgrade.

  * 服务和控制器可以转成*类*。这样我们就能一步步接近Angular 2的服务和组件类了，这样等到我们开始升级时，也会更简单。

  ## Using Component Directives
  ## 使用组件型指令

  In Angular 2, components are the main primitive from which user interfaces
  are built. We define the different parts of our UIs as components, and then
  compose the UI by using components in our templates.

  在Angular 2中，组件是用来构建用户界面的主要元素。我们把UI中的不同部分定义成组件，然后通过在模板中使用这些组件最终合成为UI。

  You can also do this in Angular 1, using *component directives*. These are
  directives that define their own templates, controllers, and input/output bindings -
  the same things that Angular 2 components define. Applications built with
  component directives are much easier to migrate to Angular 2 than applications
  built with lower-level features like `ng-controller`,  `ng-include`, and scope
  inheritance.

  我们在Angular 1中也能这么做。那就是一种定义了自己的模板、控制器和输入/输出绑定的指令 —— 跟Angular 2中对组件的定义是一样的。
  要迁移到Angular 2，通过组件型指令构建的应用程序会比直接用`ng-controller`、`ng-include`和作用域继承等底层特性构建的要容易得多。

  To be Angular 2 compatible, an Angular 1 component directive should configure
  these attributes:

  要做成与Angular 2兼容的，Angular 1的组件型指令应该配置下列属性：

  * `restrict: 'E'`. Components are usually used as elements.

  * `restrict: 'E'`。组件通常会以元素的方式使用。

  * `scope: {}` - an isolate scope. In Angular 2, components are always isolated
    from their surroundings, and we should do this in Angular 1 too.

  * `scope: {}` - 一个独立作用域。在Angular 2中，组件永远是从它们的环境中被隔离出来的，在Angular 1中，我们也应该这么做。

  * `bindToController: {}`. Component inputs and outputs should be bound
    to the controller instead of using the `$scope`.

  * `bindToController: {}`。组件的输入和输出应该绑定到控制器，而不是`$scope`。

  * `controller` and `controllerAs`. Components have their own controllers.

  * `controller`和`controllerAs`。组件有它们自己的控制器。

  * `template` or `templateUrl`. Components have their own templates.

  * `template`或`templateUrl`。组件有它们自己的模板。

  Component directives may also use the following attributes:

  组件型指令还可能使用下列属性：

  * `transclude: true`, if the component needs to transclude content from elsewhere.

  * `transclude: true`：如果组件需要从其它地方透传内容，就设置它。

  * `require`, if the component needs to communicate with some parent component's
    controller.

  * `require`：如果组件需要和父组件的控制器通讯，就设置它。

  Component directives **may not** use the following attributes:

  组件型指令**不能**使用下列属性：

  * `compile`. This will not be supported in Angular 2.

  * `compile`。它在Angular 2中将不再被支持。

  * `replace: true`. Angular 2 never replaces a component element with the
    component template. This attribute is also deprecated in Angular 1.

  * `replace: true`。Angular永远不会用组件模板替换一个组件元素。这个特性在Angular 1中也同样不建议使用了。

  * `priority` and `terminal`. While Angular 1 components may use these,
    they are not used in Angular 2 and it is better not to write code
    that relies on them.

  * `priority`和`terminal`。虽然Angular 1的组件可能使用这些，但它们在Angular 2中已经没用了，并且最好不要再写依赖它们的代码。

  An Angular 1 component directive that is fully aligned with the Angular 2
  architecture may look something like this:

  Angular 1中一个完全向Angular 2架构看齐过的组件型指令看起来有点像这样：

+makeExample('upgrade-adapter/ts/app/hero-detail.directive.ts')

:marked
  Angular 1.5 introduces the [component API](https://docs.angularjs.org/api/ng/type/angular.Module)
  that makes it easier to define directives like these. It is a good idea to use
  this API for component directives for several reasons:

  Angular 1.5引入了[组件API](https://docs.angularjs.org/api/ng/type/angular.Module)，它让像这样定义指令变得更简单了。
  为组件型指令使用这个API是一个好主意，因为：

  * It requires less boilerplate code.

  * 它需要更少的样板代码。

  * It enforces the use of component best practices like `controllerAs`.

  * 它强制使用组件的最佳实践，比如`controllerAs`。

  * It has good default values for directive attributes like `scope`,
    `restrict`, and `transclude`.

  * 对于指令中像`scope`、`restrict`和`transclude`这样的属性，它有良好的默认值。

  The component directive example from above looks like this when expressed
  using the component API:

  如果使用这个组件API进行快捷定义，那么上面看到的组件型指令就变成了这样：

+makeExample('upgrade-adapter/ts/app/upgrade-io/hero-detail.component.ts')



.l-main-section
:marked
  # Upgrading with The Upgrade Adapter
  # 使用升级适配器进行升级

  The `upgrade` module in Angular 2 is a very useful tool for upgrading
  anything but the smallest of applications. With it we can mix and match
  Angular 1 and 2 components in the same application and have them interoperate
  seamlessly. That means we don't have to do the upgrade work all at once,
  since there's a natural coexistence between the two frameworks during the
  transition period.

  不管要升级什么，Angular 2中的`upgrade`模块都会是一个非常有用的工具 —— 除非是小到没功能的应用。
  借助它，我们可以在同一个应用程序中混用并匹配Angular 1和2的组件，并让它们实现无缝的互操作。
  这意味着我们不用必须一次性做完所有升级工作，因为在整个演进过程中，这两个框架可以很自然的和睦相处。

  ## How The Upgrade Adapter Works
  ## 升级适配器如何工作

  The primary tool provided by the upgrade module is called the `UpgradeAdapter`.
  This is a service that can bootstrap and manage hybrid applications that support
  both Angular 2 and Angular 1 code.

  `upgrade`模块提供的主要工具叫做`UpgradeAdapter`。这是一个服务，它可以引导并管理同时支持Angular 2和Angular 1的混合式应用程序。

  When we use `UpgradeAdapter`, what we're really doing is *running both versions
  of Angular at the same time*. All Angular 2 code is running in the Angular 2
  framework, and Angular 1 code in the Angular 1 framework. Both of these are the
  actual, fully featured versions of the frameworks. There is no emulation going on,
  so we can expect to have all the features and natural behavior of both frameworks.

  当使用`UpgradeAdapter`时，我们实际做的是*同时运行两个版本的Angular*。所有Angular 2的代码运行在Angular 2框架中，
  而Angular 1的代码运行在Angular 1框架中。所有这些都是真实的、全功能的框架版本。
  没有进行任何仿真，所以我们可以期待同时存在这两个框架的所有特性和天生的行为。

  What happens on top of this is that components and services managed by one
  framework can interoperate with those from the other framework. This happens
  in three main areas: Dependency injection, the DOM, and change detection.

  所有这些事情的背后，本质上是一个框架中管理的组件和服务能和来自另一个中的进行互操作。
  这发生在三个主要的领域：依赖注入、DOM和变更检测。

  ### Dependency Injection
  ### 依赖注入

  Dependency injection is front and center in both Angular 1 and
  Angular 2, but there are some key differences between the two
  frameworks in how it actually works.

  无论是在Angular 1中还是在Angular 2中，依赖注入都处于前沿和中心的位置，但在两个框架的工作原理上，却存在着一些关键的不同之处。

table
  tr
    th Angular 1
    th Angular 2
  tr
    td
      :marked
        Dependency injection tokens are always strings

        依赖注入的令牌(Token)永远是字符串(译注：指服务名称)。
    td
      :marked
        Tokens [can have different types](../guide/dependency-injection.html).
        They are often classes. They may also be strings.

        令牌[可能有不同的类型](../guide/dependency-injection.html)。
        通常是类，也可能是字符串。
  tr
    td
      :marked
        There is exactly one injector. Even in multi-module applications,
        everything is poured into one big namespace.

        只有一个注入器。即使在多模块的应用程序中，每样东西也都被装入一个巨大的命名空间中。
    td
      :marked
        There is a [tree hierarchy of injectors](../guide/hierarchical-dependency-injection.html),
        with a root injector and an additional injector for each component.

        有一组[树状多层注入器](../guide/hierarchical-dependency-injection.html)，有一个根注入器，每个组件也有一个额外的注入器。

:marked
  Even accounting for these differences we can still have dependency injection
  interoperability. The `UpgradeAdapter` resolves the differences and makes
  everything work seamlessly:

  就算有这么多不同点，也并不妨碍我们在依赖注入时进行互操作。`UpgradeAdapter`解决了这些差异，并让它们无缝的对接：

  * We can make Angular 1 services available for injection to Angular 2 code
    by *upgrading* them. The same singleton instance of each service is shared
    between the frameworks. In Angular 2 these services will always be in the
    *root injector* and available to all components. They will always have
    *string tokens* - the same tokens that they have in Angular 1.

  * 通过升级它们，我们就能让那些在Angular 1中能被注入的服务在Angular 2的代码中可用。
    在框架之间共享的是服务的同一个单例对象。在Angular 2中，这些外来服务总是被放在*根注入器*中，并可用于所有组件。
    它们总是具有*字符串令牌* —— 跟它们在Angular 1中的令牌相同。

  * We can also make Angular 2 services available for injection to Angular 1 code
    by *downgrading* them. Only services from the Angular 2 root injector can
    be downgraded. Again, the same singleton instances are shared between the frameworks.
    When we register a downgrade, we explicitly specify a *string token* that we want to
    use in Angular 1.

  * 通过降级它们，我们也能让那些在Angular 2中能被注入的服务在Angular 1的代码中可用。
    只有那些来自Angular 2根注入器的服务才能被降级。同样的，在框架之间共享的是同一个单例对象。
    当我们注册一个要降级的服务时，要明确指定一个打算在Angular 1中使用的*字符串令牌*。

figure.image-display
  img(src="/resources/images/devguide/upgrade/injectors.png" alt="The two injectors in a hybrid application" width="700")

:marked
  ### Components and the DOM
  ### 组件与DOM

  What we'll find in the DOM of a hybrid application are components and
  directives from both Angular 1 and Angular 2. These components
  communicate with each other by using the input and output bindings
  of their respective frameworks, which the `UpgradeAdapter` bridges
  together. They may also communicate through shared injected dependencies,
  as described above.

  在混合式应用中，我们能同时发现那些来自Angular 1和Angular 2中组件和指令的DOM。
  这些组件通过它们各自框架中的输入和输出绑定来互相通讯，它们由`UpgradeAdapter`桥接在一起。
  它们也能通过共享被注入的依赖彼此通讯，就像前面所说的那样。

  There are two key things to understand about what happens in the DOM
  of a hybrid application:

  要弄明白在一个混合式应用的DOM中发生了什么，有两点很关键：

  1. Every element in the DOM is owned by exactly one of the two
     frameworks. The other framework ignores it. If an element is
     owned by Angular 1, Angular 2 treats it as if it didn't exist,
     and vice versa.

  1. DOM中的每个元素都只能被两个框架之一拥有。另一个框架会忽略它。
     如果一个元素被Angular 1拥有，Angular 2就会当它不存在。反之亦然。

  2. The root of the application *is always an Angular 1 template*.

  2. 应用的根节点*总是来自Angular 1中的模板*。

  So a hybrid application begins life as an Angular 1 application,
  and it is Angular 1 that processes its root template. Angular 2 then steps
  into the picture when an Angular 2 component is used somewhere in
  the application templates. That component's view will then be managed
  by Angular 2, and it may use any number of Angular 2 components and
  directives.

  所以，混合式应用总是像Angular 1程序那样启动，处理根模板的也是Angular 1.
  然后，当这个应用的模板中使用到了Angular 2的组件时，Angular 2才开始参与。
  这个组件的视图由Angular 2进行管理，而且它还可以使用一系列的Angular 2组件和指令。

  Beyond that, we may interleave the two frameworks as much as we need to.
  We always cross the boundary between the two frameworks by one of two
  ways:

  更进一步说，我们可以按照需要，任意穿插使用这两个框架。
  使用下面的两种方式之一，我们可以自由穿梭于这两个框架的边界：

  1. By using a component from the other framework: An Angular 1 template
     using an Angular 2 component, or an Angular 2 template using an
     Angular 1 component.

  1. 通过使用来自另一个框架的组件：Angular 1的模板中用到了Angular 2的组件，或者Angular 2的模板中使用了Angular 1的组件。

  2. By transcluding or projecting content from the other framework. The
    `UpgradeAdapter` bridges the related concepts of  Angular 1 transclusion
     and Angular 2 content projection together.

  2. 通过透传(transclude)或投影(project)来自另一个框架的内容。`UpgradeAdapter`牵线搭桥，把Angular 1的透传概念和Angular 2的内容投影概念关联起来。

figure.image-display
 img(src="/resources/images/devguide/upgrade/dom.png" alt="DOM element ownership in a hybrid application" width="500")

:marked
  Whenever we use a component that belongs to the other framework, a
  switch between framework boundaries occurs. However, that switch only
  happens to the *children* of the component element. Consider a situation
  where we use an Angular 2 component from Angular 1 like this:

  无论什么时候，只要我们用到了来自另一个框架的组件，就会发生框架边界的切换。然而，这种切换只会发生在组件元素的*子节点*上。
  考虑一个场景，我们从Angular 1中像这样使用Angular 2的组件：

  ```
  <ng2-component></ng2-component>
  ```

  The DOM element `<ng2-component>` will remain to be an Angular 1 managed
  element, because it's defined in an Angular 1 template. That also
  means you can apply additional Angular 1 directives to it, but *not*
  Angular 2 directives. It is only in the template of the `Ng2Component`
  component where Angular 2 steps in. This same rule also applies when you
  use Angular 1 component directives from Angular 2.

  此时，`<ng2-component>`这个DOM元素仍然由Angular 1管理，因为它是在Angular 1的模板中定义的。
  这也意味着你可以往它上面添加额外的Angular 1指令，却*不能*添加Angular 2的指令。
  只有在`Ng2Component`组件的模板中才是Angular 2的天下。同样的规则也适用于在Angular 2中使用Angular 1组件型指令的情况。

:marked
  ### Change Detection
  ### 变更检测

  Change detection in Angular 1 is all about `scope.$apply()`. After every
  event that occurs, `scope.$apply()` gets called. This is done either
  automatically by the framework, or in some cases manually by our own
  code. It is the point in time when change detection occurs and data
  bindings get updated.

  Angular 1中的变更检测全是关于`scope.$apply()`的。在每个事件发生之后，`scope.$apply()`就会被调用。
  这或者由框架自动调用，或者在某些情况下由我们自己的代码手动调用。它是发生变更检测以及更新数据绑定的时间点。

  In Angular 2 things are different. While change detection still
  occurs after every event, no one needs to call `scope.$apply()` for
  that to happen. This is because all Angular 2 code runs inside something
  called the [Angular zone](../api/core/NgZone-class.html). Angular always
  knows when the code finishes, so it also knows when it should kick off
  change detection. The code itself doesn't have to call `scope.$apply()`
  or anything like it.

  在Angular 2中，事情有点不一样。虽然变更检测仍然会在每一个事件之后发生，却不再需要每次调用`scope.$apply()`了。
  这是因为所有Angular 2代码都运行在一个叫做[Angular zone](../api/core/NgZone-class.html)的地方。
  Angular总是知道什么时候代码执行完了，也就知道了它什么时候应该触发变更检测。代码本身并不需要调用`scope.$apply()`或其它类似的东西。

  In the case of hybrid applications, the `UpgradeAdapter` bridges the
  Angular 1 and Angular 2 approaches. Here's what happens:

  在这种混合式应用的案例中，`UpgradeAdapter`在Angular 1的方法和Angular 2的方法之间建立了桥梁。发生了什么呢？

  * Everything that happens in the application runs inside the Angular 2 zone.
    This is true whether the event originated in Angular 1 or Angular 2 code.
    The zone triggers Angular 2 change detection after every event.

  * 应用中发生的每件事都运行在Angular 2的zone里。
    无论事件发生在Angular 1还是Angular 2的代码中，都是如此。

  * The `UpgradeAdapter` will invoke the Angular 1 `$rootScope.$apply()` after
    every turn of the Angular zone. This also triggers Angular 1 change
    detection after every event.

  * `UpgradeAdapter`将在每一次离开Angular zone时调用Angular 1的`$rootScope.$apply()`。这样也就同样会在每个事件之后触发Angular 1的变更检测。

figure.image-display
  img(src="/resources/images/devguide/upgrade/change_detection.png" alt="Change detection in a hybrid application" width="600")

:marked
  What this means in practice is that we do not need to call `$apply()` in
  our code, regardless of whether it is in Angular 1 on Angular 2. The
  `UpgradeAdapter` does it for us. We *can* still call `$apply()` so there
  is no need to remove such calls from existing code. Those calls just don't
  have any effect in a hybrid application.

  在实践中，这意味着我们不用在自己的代码中调用`$apply()`，而不用管这段代码是在Angular 1还是Angular 2中。
  `UpgradeAdapter`都替我们做了。我们仍然*可以*调用`$apply()`，以便可以不必从现有代码中移除此调用。
  在混合式应用中，那些调用只是没有任何效果而已。

:marked
  When we downgrade an Angular 2 component and then use it from Angular 1,
  the component's inputs will be watched using Angular 1 change detection.
  When those inputs change, the corresponding properties in the component
  are set. We can also hook into the changes by implementing the
  [OnChanges](../api/core/OnChanges-interface.html) interface in the component,
  just like we could if it hadn't been downgraded.

  当我们降级一个Angular 2组件，然后把它用于Angular 1中时，组件的输入属性就会被Angular 1的变更检测体系监视起来。
  当那些输入属性发生变化时，组件中相应的属性就会被设置。我们也能通过实现[OnChanges](../api/core/OnChanges-interface.html)
  接口来挂钩到这些更改，就像它未被降级时一样。

  Correspondingly, when we upgrade an Angular 1 component and use it from Angular 2,
  all the bindings defined for the component directive's `scope` (or `bindToController`)
  will be hooked into Angular 2 change detection. They will be treated
  as regular Angular 2 inputs and set onto the scope (or controller) when
  they change.

  相应的，当我们把Angular 1的组件升级给Angular 2使用时，在这个组件型指令的`scope`(或`bindToController`)中定义的所有绑定
  都将被挂钩到Angular 2的变更检测体系中。它们将和标准的Angular 2输入属性被同等对待，并当它们发生变化时设置回scope(或控制器)上。

  ## Bootstrapping Hybrid Angular 1+2 Applications
  ## 引导Angular 1+2的混合式应用程序

  The first step to upgrading an application using the `UpgradeAdapter` is
  always to bootstrap it as a hybrid that supports both Angular 1 and
  Angular 2.

  使用`UpgradeAdapter`升级应用的第一步总是把它引导成一个同时支持Angular 1和Angular 2的混合式应用。

  Pure Angular 1 applications can be bootstrapped in two ways: By using an `ng-app`
  directive somewhere on the HTML page, or by calling
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)
  from JavaScript. In Angular 2, only the second method is possible - there is
  no `ng-app` in Angular 2. This is also the case for hybrid applications.
  Therefore, it is a good preliminary step to switch Angular 1 applications to use the
  JavaScript bootstrap method even before switching them to hybrid mode.

  纯粹的Angular 1应用可以用两种方式引导：在HTML页面中的某处使用`ng-app`指令，或者从JavaScript中调用
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)。
  在Angular 2中，只有第二种方法是可行的，因为它没有`ng-app`指令。在混合式应用中也同样只能用第二种方法。
  所以，即使在把Angular 1应用切换到混合模式之前，把它改为用JavaScript引导的方式也是一个不错的起点。

  Say we have an `ng-app` driven bootstrap such as this one:

  比如说我们有个由`ng-app`驱动的引导过程，就像这个：

+makeExample('upgrade-adapter/ts/index-ng-app.html', null, null, {otl: /(ng-app.*ng-strict-di)/})

:marked
  We can remove the `ng-app` and `ng-strict-di` directives from the HTML
  and instead switch to calling `angular.bootstrap` from JavaScript, which
  will result in the same thing:

  我们可以从HTML中移除`ng-app`和`ng-strict-di`指令，改为从JavaScript中调用`angular.bootstrap`，它能达到同样效果：

+makeExample('upgrade-adapter/ts/app/1-bootstrap/app.module.ts', 'bootstrap')

:marked
  To then switch the application into hybrid mode, we must first
  install Angular 2 to the project. Follow the instructions in
  [the QuickStart](../quickstart.html) for some pointers on this.
  When we have Angular 2 installed, we can import and instantiate
  the `UpgradeAdapter`, and then call its `bootstrap` method. It
  is designed to take the exact same arguments as
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)
  so that it is easy to make the switch:

  要把这个应用切换到混合模式，我们得先把Angular 2安装到项目中。遵循[“快速起步”](../quickstart.html)中给出的步骤完成它。
  安装完Angular 2之后，我们可以导入和实例化`UpgradeAdapter`类，然后调用它的`bootstrap`方法。
  它被设计成接受与[angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)完全相同的参数。
  所以，做这种切换很简单：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'bootstrap')

:marked
  At this point we'll be running a hybrid Angular 1+2 application! All the
  existing Angular 1 code will work as it always did, but we are now ready
  to run Angular 2 code as well.

  这时，我们就要开始运行Angular 1+2的混合式应用程序了！所有现存的Angular 1代码会像以前一样正常工作，但是我们现在也同样可以运行Angular 2代码了。

.alert.is-helpful
  :marked
    One notable difference between `angular.bootstrap` and
    `upgradeAdapter.bootstrap` is that the latter works *asynchronously*.
    This means that we cannot assume that the application has been instantiated
    immediately after the bootstrap call returns.

    在`angular.bootstrap`和`upgradeAdapter.bootstrap`之间一个显著的不同点是：后者是*异步*工作的。
    这意味着当这次`bootstrap`调用刚刚返回时，我们不能假设应用程序已经被初始化过了。

:marked
  As we begin to migrate components to Angular 2, we'll be using the
  `UpgradeAdapter` for more than just bootstrapping. It'll be important
  to use the **same** instance of the adapter across the whole application,
  because it stores internal information about what's going on in the application.
  It'll be useful to have a module for a shared `UpgradeAdapter` instance in
  the project:

  当我们开始把组件移植到Angular 2时，我们还将使用`UpgradeAdapter` —— 不止是进行引导。
  在整个应用程序中使用此适配器的**同一个**实例是非常重要的，因为它保存了关于该应用程序当前状态的内部信息：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-shared-adapter-bootstrap/upgrade_adapter.ts', null, 'upgrade_adapter.ts')

:marked
  This shared instance can then be pulled in to all the modules that need it:

  然后这个共享的实例就能被所有需要它的模块获取到：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-shared-adapter-bootstrap/app.module.ts', 'bootstrap')

:marked
  ## Using Angular 2 Components from Angular 1 Code
  ## 在Angular 1的代码中使用Angular 2的组件
figure
  img(src="/resources/images/devguide/upgrade/a1-to-a2.png" alt="Using an Angular 2 component from Angular 1 code" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  Once we're running a hybrid app, we can start the gradual process of upgrading
  code. One of the more common patterns for doing that is to use an Angular 2 component
  in an Angular 1 context. This could be a completely new component or one that was
  previously Angular 1 but has been rewritten for Angular 2.

  一旦我们开始运行混合式应用，我们就可以开始逐渐升级代码了。做这件事的一种更常见的模式就是在Angular 1的上下文中使用Angular 2的组件。
  该组件可能是全新的，也可能是把原本Angular 1的组件用Angular 2重写而成的。

  Say we have a simple Angular 2 component that shows information about a hero:

  假设我们有一个简单的用来显示英雄信息的Angular 2组件：

+makeExample('upgrade-adapter/ts/app/downgrade-static/hero-detail.component.ts', null, 'hero-detail.component.ts')

:marked
  If we want to use this component from Angular 1, we need to *downgrade* it
  using the upgrade adapter. What we get when we do that is an Angular 1
  *directive*, which we can then register into our Angular 1 module:

  如果我们想在Angular 1中使用这个组件，我们就得用“升级适配器”把它*降级*。如果我们这么做，就会得到一个Angular 1的*指令*，
  我们可以把它注册到Angular 1的模块中：

+makeExample('upgrade-adapter/ts/app/downgrade-static/app.module.ts', 'downgradecomponent')

:marked
  What we have here is an Angular 1 directive called `heroDetail`, which we can
  use like any other directive in our Angular 1 templates.

  这里我们得到的是一个叫做`heroDetail`的Angular 1指令，我们可以像用其它指令一样把它用在Angular 1模板中。

+makeExample('upgrade-adapter/ts/index-downgrade-static.html', 'usecomponent')

.alert.is-helpful
  :marked
    Note that since Angular 1 directives are matched based on their name,
    *the selector metadata of the Angular 2 component is not used in Angular 1*.
    It is matched as an element directive (`restrict: 'E'`) called `heroDetail`.

    注意，由于Angular 1的指令是基于它们的名字进行匹配的，*Angular 2组件元数据中的`selector`不会被用在Angular 1中*。
    它会像一个名叫`heroDetail`的元素型指令(`restrict: 'E'`)一样被匹配。

:marked
  Most components are not quite this simple, of course. Many of them
  have *inputs and outputs* that connect them to the outside world. An
  Angular 2 hero detail component with inputs and outputs might look
  like this:

  当然，大多数组件都不像这个这么简单。它们中很多都有*输入属性和输出属性*，来把它们连接到外部世界。
  Angular 2的英雄详情组件带有像这样的输入属性与输出属性：

+makeExample('upgrade-adapter/ts/app/downgrade-io/hero-detail.component.ts', null, 'hero-detail.component.ts')

:marked
  These inputs and outputs can be supplied from the Angular 1 template, and the
  `UpgradeAdapter` takes care of bridging them over:

  这些输入属性和输出属性的值来自于Angular 1的模板，而`UpgradeAdapter`负责桥接它们：

+makeExample('upgrade-adapter/ts/index-downgrade-io.html', 'usecomponent')

:marked
  Note that even though we are in an Angular 1 template, **we're using Angular 2
  attribute syntax to bind the inputs and outputs**. This is a requirement for downgraded
  components. The expressions themselves are still regular Angular 1 expressions.

  注意，虽然我们正在Angular 1的模板中，**但却在使用Angular 2的属性(Attribute)语法来绑定到输入属性与输出属性**。
  这是降级的组件本身要求的。而表达式本身仍然是标准的Angular 1表达式。

  The `$event` variable can be used in outputs to gain access to the
  object that was emitted. In this case it will be the `Hero` object, because
  that is what was passed to `this.deleted.emit()`.

  `$event`变量能被用在输出属性里，以访问这个事件所发出的对象。这个案例中它是`Hero`对象，因为`this.deleted.emit()`函数曾把它传了出来。

  Since this is an Angular 1 template, we can still use other Angular 1
  directives on the element, even though it has Angular 2 binding attributes on it.
  For  example, we can easily make multiple copies of the component using `ng-repeat`:

  由于这是一个Angular 1模板，虽然它已经有了Angular 2中绑定的属性(Attribute)，我们仍可以在这个元素上使用其它Angular 1指令。
  例如，我们可以用`ng-repeat`简单的制作该组件的多份拷贝：

+makeExample('upgrade-adapter/ts/index-downgrade-io.html', 'userepeatedcomponent')

:marked
  ## Using Angular 1 Component Directives from Angular 2 Code
  ## 从Angular 2代码中使用Angular 1组件型指令
figure
  img(src="/resources/images/devguide/upgrade/a2-to-a1.png" alt="Using an Angular 1 component from Angular 2 code" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  So, we can write an Angular 2 component and then use it from Angular 1
  code. This is very useful when we start our migration from lower-level
  components and work our way up. But in some cases it is more convenient
  to do things in the opposite order: To start with higher-level components
  and work our way down. This too can be done using the `UpgradeAdapter`.
  We can *upgrade* Angular 1 component directives and then use them from
  Angular 2.

  现在，我们已经能在Angular 2中写一个组件，并把它用于Angular 1代码中了。
  当我们从低级组件开始移植，并往上走时，这非常有用。但在另外一些情况下，从相反的方向进行移植会更加方便：
  从高级组件开始，然后往下走。这也同样能用`UpgradeAdapter`完成。
  我们可以*升级*Angular 1组件型指令，然后从Angular 2中用它们。

  Not all kinds of Angular 1 directives can be upgraded. The directive
  really has to be a *component directive*, with the characteristics
  [described in the preparation guide above](#using-component-directives).
  Our safest bet for ensuring compatibility is using the
  [component API](https://docs.angularjs.org/api/ng/type/angular.Module)
  introduced in Angular 1.5.

  不是所有种类的Angular 1指令都能升级。该指令必须是一个严格的*组件型指令*，具有[上面的准备指南中描述的](#using-component-directives)那些特征。
  确保兼容性的最安全的方式是ANgular 1.5中引入的[组件API](https://docs.angularjs.org/api/ng/type/angular.Module)。

  A simple example of an upgradable component is one that just has a template
  and a controller:

  可升级组件的简单例子是只有一个模板和一个控制器的指令：

+makeExample('upgrade-adapter/ts/app/upgrade-static/hero-detail.component.ts', null, 'hero-detail.component.ts')

:marked
  We can *upgrade* this component to Angular 2 using the `UpgradeAdapter`'s
  `upgradeNg1Component` method. It takes the name of an Angular 1 component
  directive and returns an Angular 2 **component class**. When we then
  want to use it from an Angular 2 component, we list it the in the `directives`
  metadata of the component and then just use it in the Angular 2 template:

  我们可以使用`UpgradeAdapter`的`upgradeNg1Component`方法来把这个组件*升级*到Angular 2。
  它接受Angular 1组件型指令的名字，并返回一个Angular 2**组件类**。
  当我们以后想从Angular 2组件中用它时，只要把它列在组件的`directives`元数据中，然后直接在Angular 2模板中用它就可以了：

+makeExample('upgrade-adapter/ts/app/upgrade-static/container.component.ts', null, 'container.component.ts')

.alert.is-helpful
  :marked
    Upgraded components always have an element selector, which is based
    on the original name of the original Angular 1 component directive.


    升级后的组件总会有一个元素选择器，它就是原Angular 1组件型指令的原始名字。


:marked
  An upgraded component may also have inputs and outputs, as defined by
  the scope/controller bindings of the original Angular 1 component
  directive. When we use the component from an Angular 2 template,
  we provide the inputs and outputs using **Angular 2 template syntax**,
  with the following rules:

  升级后的组件也可能有输入属性和输出属性，它们是在原Angular 1组件型指令的scope/controller绑定中定义的。
  当我们从Angular 2模板中使用该组件时，我们要使用**Angular 2模板语法**来提供这些输入属性和输出属性，但要遵循下列规则：

table
  tr
    th
    th
      p Binding definition
      p 绑定定义
    th
      p Template syntax
      p 模板语法
  tr
    th
      p Attribute binding
      p 属性(Attribute)绑定
    td
      :marked
        `myAttribute: '@myAttribute'`
    td
      :marked
        `<my-component myAttribute="value">`
  tr
    th
      p Expression binding
      p 表达式绑定
    td
      :marked
        `myOutput: '&myOutput'`
    td
      :marked
        `<my-component (myOutput)="action()">`
  tr
    th
      p Two-way binding
      p 双向绑定
    td
      :marked
        `myValue: '=myValue'`
    td
      :marked
        As input: `<my-component [myValue]="anExpression">` or
        as two-way binding: `<my-component [(myValue)]="anExpression"`

        用作输入：`<my-component [myValue]="anExpression">` 或
        用作双向绑定：`<my-component [(myValue)]="anExpression"`

:marked
  As an example, say we have a hero detail Angular 1 component directive
  with one input and one output:

  举个例子，假设我们在Angular 1中有一个表示“英雄详情”的组件型指令，它带有一个输入属性和一个输出属性：

+makeExample('upgrade-adapter/ts/app/upgrade-io/hero-detail.component.ts', null, 'hero-detail.component.ts')

:marked
  We can upgrade this component to Angular 2, and then provide the input
  and output using Angular 2 template syntax:

  我们可以把这个组件升级到Angular 2，然后使用Angular 2的模板语法提供这个输入属性和输出属性：

+makeExample('upgrade-adapter/ts/app/upgrade-io/container.component.ts', null, 'container.component.ts')


:marked
  ## Projecting Angular 1 Content into Angular 2 Components
  ## 把Angular 1的内容投影到Angular 2组件中
figure
  img(src="/resources/images/devguide/upgrade/a1-to-a2-with-projection.png" alt="Projecting Angular 1 content into Angular 2" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  When we are using a downgraded Angular 2 component from an Angular 1
  template, the need may arise to *transclude* some content into it. This
  is also possible. While there is no such thing as transclusion in Angular 2,
  there is a very similar concept called *content projection*. The `UpgradeAdapter`
  is able to make these two features interoperate.

  如果我们正在从Angular 1模板中使用降级后的Angular 2组件，可能会需要把模板中的一些内容投影进那个组件。
  这也是可能的，虽然在Angular 2中并没有透传(transclude)这样的东西，但它有一个非常相似的概念，叫做*内容投影*。
  `UpgradeAdapter`也能让这两个特性实现互操作。

  Angular 2 components that support content projection make use of an `<ng-content>`
  tag within them. Here's an example of such a component:

  Angular 2的组件通过使用`<ng-content>`标签来支持内容投影。下面是这类组件的一个例子：

+makeExample('upgrade-adapter/ts/app/1-to-2-projection/hero-detail.component.ts', null, 'hero-detail.component.ts')

:marked
  When using the component from Angular 1, we can supply contents for it. Just
  like they would be transcluded in Angular 1, they get projected to the location
  of the `<ng-content>` tag in Angular 2:

  当从Angular 1中使用该组件时，我们可以为它提供内容。正如它们将在Angular 1中被透传一样，
  它们也在Angular 2中被投影到了`<ng-content>`标签所在的位置：

+makeExample('upgrade-adapter/ts/index-1-to-2-projection.html', 'usecomponent')

.alert.is-helpful
  :marked
    When Angular 1 content gets projected inside an Angular 2 component, it still
    remains in "Angular 1 land" and is managed by the Angular 1 framework.

    当Angular 1的内容被投影到Angular 2组件中时，它仍然留在“Angular 1王国”中，并被Angular 1框架管理着。

:marked
  ## Transcluding Angular 2 Content into Angular 1 Component Directives
  ## 把Angular 2的内容透传进Angular 1的组件型指令
figure
  img(src="/resources/images/devguide/upgrade/a2-to-a1-with-transclusion.png" alt="Projecting Angular 2 content into Angular 1" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  Just like we can project Angular 1 content into Angular 2 components,
  we can *transclude* Angular 2 content into Angular 1 components, whenever
  we are using upgraded versions from them.

  就像我们能把Angular 1的内容投影进Angular 2组件一样，我们也能把Angular 2的内容*透传*进Angular 1的组件，
  但不管怎样，我们都要使用它们升级过的版本。

  When an Angular 1 component directive supports transclusion, it may use
  the `ng-transclude` directive in its template to mark the transclusion
  point:

  如果一个Angular 1组件型指令支持透传，它就会在自己的模板中使用`ng-transclude`指令标记出透传到的位置：

+makeExample('upgrade-adapter/ts/app/2-to-1-transclusion/hero-detail.component.ts', null, 'hero-detail.component.ts')

.alert.is-helpful
  :marked
    The directive also needs to have the `transclude: true` option enabled.
    It is on by default for component directives defined with the
    1.5 component API.

    该指令还需要启用一个`transclude: true`选项。当用Angular 1.5中的组件API定义组件型指令时，该选项默认是开启的。

:marked
  If we upgrade this component and use it from Angular 2, we can populate
  the component tag with contents that will then get transcluded:

  如果我们升级这个组件，并把它用在Angular 2中，我们就能把准备透传的内容放进这个组件的标签中。

+makeExample('upgrade-adapter/ts/app/2-to-1-transclusion/container.component.ts', null, 'container.component.ts')

:marked
  ## Making Angular 1 Dependencies Injectable to Angular 2
  ## 让Angular 1中的依赖可被注入到Angular 2

  When running a hybrid app, we may bump into situations where we need to have
  some Angular 1 dependencies to be injected to Angular 2 code. This may be
  because we have some business logic still in Angular 1 services, or because
  we need some of Angular 1's built-in services like `$location` or `$timeout`.

  当运行一个混合式应用时，我们可能会遇到这种情况：我们需要把某些Angular 1的依赖注入到Angular 2代码中。
  这可能是因为某些业务逻辑仍然在Angular 1服务中，或者需要某些Angular 1的内建服务，比如`$location`或`$timeout`。

  In these situations, it is possible to *upgrade* an Angular 1 provider to
  Angular 2. This makes it possible to then inject it somewhere in Angular 2
  code. For example, we might have a service called `HeroesService` in Angular 1:

  在这些情况下，把一个Angular 1供应商*升级到*Angular 2也是有可能的。这就让它将来有可能被注入到Angular 2代码中的某些地方。
  比如，我们可能在Angular 1中有一个名叫`HeroesService`的服务：

+makeExample('upgrade-adapter/ts/app/1-to-2-providers/heroes.service.ts', null, 'heroes.service.ts')

:marked
  We can upgrade the service using the `UpgradeAdapter`'s `upgradeNg1Provider` method
  by giving it the name of the service. This adds the service into Angular 2's root injector.

  我们可以用`UpgradeAdapter`的`upgradeNg1Provider`方法来升级该服务，只要给它传入服务的名字就行了。
  这会把该服务加到Angular 2的根注入器中。

+makeExample('upgrade-adapter/ts/app/1-to-2-providers/app.module.ts', 'register', 'app.module.ts')

:marked
  We can then inject it in Angular 2 using a string token that matches
  its original name in Angular 1:

  然后我们可以使用与它在Angular 1中的原始名字相同的字符串型令牌，把它注入到Angular 2中：

+makeExample('upgrade-adapter/ts/app/1-to-2-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')

.alert.is-helpful
  :marked
    In this example we upgraded a service class, which has the added benefit that
    we can use a TypeScript type annotation when we inject it. While it doesn't
    affect how the dependency is handled, it enables the benefits of static type
    checking. This is not required though, and any Angular 1 service, factory, or
    provider can be upgraded.

    在这个例子中，我们升级了服务类。当我们注入它时，我们可以使用TypeScript类型注解来获得这些额外的好处。
    它没有影响该依赖的处理过程，同时还得到了启用静态类型检查的好处。
    任何Angular 1中的服务、工厂和供应商都能被升级 —— 尽管这不是必须的。

:marked
  ## Making Angular 2 Dependencies Injectable to Angular 1
  ## 让Angular 2的依赖能被注入到Angular 1中

  In addition to upgrading Angular 1 dependencies, we can also *downgrade*
  Angular 2 dependencies, so that we can use them from Angular 1. This can be
  useful when we start migrating services to Angular 2 or creating new services
  in Angular 2 while we still have components written in Angular 1.

  除了能升级Angular 1依赖之外，我们还能*降级*Angular 2的依赖，以便我们能在Angular 1中使用它们。
  当我们已经开始把服务移植到Angular 2或在Angular 2中创建新服务，但同时还有一些用Angular 1写成的组件时，这会非常有用。

  For example, we might have an Angular 2 service called `Heroes`:

  例如，我们可能有一个Angular 2的`Heroes`服务：

+makeExample('upgrade-adapter/ts/app/2-to-1-providers/heroes.ts', null, 'heroes.ts')

:marked
  We can again use the `UpgradeAdapter` for this, but first we need to register `Heroes`
  to the Angular 2 injector itself. In a pure Angular 2 application we would do this
  when we bootstrap the app, as described in the [dependency injection guide](dependency-injection.html#!#providers).
  But since hybrid applications are bootstrapped using the `UpgradeAdapter`, we also
  need to register our Angular 2 providers using `UpgradeAdapter`. It has a method
  called `addProvider` for this purpose.

  我们又能使用`UpgradeAdapter`处理它了，但首先我们需要把`Heroes`服务注册到Angular 2自身的注入器。
  在纯Angular 2应用中，我们会在引导应用时这么做，就像[依赖注入指南](dependency-injection.html#!#providers)中描述的那样。
  但是因为混合式应用是使用`UpgradeAdapter`引导的，所以我们还得用`UpgradeAdapter`注册Angular 2的供应商。
  它有一个`addProvider`方法就是用来做这个的。

  Once we've registered the Angular 2 provider, we can turn `Heroes` into an *Angular 1
  factory function* using `upgradeAdapter.downgradeNg2Provider()`. We can
  then plug the factory into an Angular 1 module, at which point we also choose what the
  name of the dependency will be in Angular 1:

  一旦我们注册了Angular 2的供应商，就能用`upgradeAdapter.downgradeNg2Provider()`把`Heroes`转变成一个*Angular 1的工厂函数*。
  然后我们就能把这个工厂插入到Angular 1模块中，那时，我们可以选择该依赖要在Angular 1中用的名字：

+makeExample('upgrade-adapter/ts/app/2-to-1-providers/app.module.ts', 'register', 'app.module.ts')

:marked
  After this, the service is injectable anywhere in our Angular 1 code:

  此后，该服务就能被注入到Angular 1代码中的任何地方了：

+makeExample('upgrade-adapter/ts/app/2-to-1-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')

.l-main-section
:marked
  # PhoneCat Preparation Tutorial
  # PhoneCat准备教程

  In this section and the one following it we will look at a complete example of
  preparing and upgrading an application using the `upgrade` module. The app
  we're going to work on is [Angular PhoneCat](https://github.com/angular/angular-phonecat)
  from [the original Angular 1 tutorial](https://docs.angularjs.org/tutorial),
  which is where many of us began our Angular adventures. Now we'll see how to
  bring that application to the brave new world of Angular 2.

  在本节和下节中，我们将看一个完整的例子，它使用`upgrade`模块准备和升级了一个应用程序。
  该应用就是来自[原Angular 1教程](https://docs.angularjs.org/tutorial)中的[Angular PhoneCat](https://github.com/angular/angular-phonecat)。
  那是我们很多人当初开始Angular探险之旅的起点。
  现在，我们来看看如何把该应用带入Angular 2的美丽新世界。

  During the process we'll learn how to apply the steps outlined in the
  [preparation guide](#preparation) in practice: We'll align the application
  with Angular 2 and also take both the SystemJS module loader and TypeScript
  into use.

  这期间，我们将学到如何在实践中应用[准备指南](#preparation)中列出的那些重点步骤：
  我们先让该应用向Angular 2看齐，然后为它引入SystemJS模块加载器和TypeScript。

  To follow along with the tutorial, clone the
  [angular-phonecat](https://github.com/angular/angular-phonecat) repository
  and apply the steps as we go

  要跟随本教程，请先把[angular-phonecat](https://github.com/angular/angular-phonecat)仓库clone到本地，并跟我们一起应用这些步骤。

.alert.is-important
  :marked
    If you do clone this repository, note that it doesn't look like this guide
    assumes yet. There's [a pull request](https://github.com/angular/angular-phonecat/pull/289)
    that will change this. Meanwhile, you'll find a good starting point from
    [this commit](https://github.com/teropa/angular-phonecat/commit/d6fb83e1c2db9d1812c7c478fdb8d92301ef0061).

    如果你已经克隆了这个仓库，可能会注意到它看起来和本指南中所假设的不太一样。
    有一个[Pull Request](https://github.com/angular/angular-phonecat/pull/289)就是要求改变这一点的。同时，我们找到了一个更好的起点：
    也就是[这个提交](https://github.com/teropa/angular-phonecat/commit/d6fb83e1c2db9d1812c7c478fdb8d92301ef0061)。

:marked
  In terms of project structure, this is where our work begins

  在项目结构方面，我们工作的起点是这样的：

.filetree
  .file angular-phonecat
  .children
    .file bower.json
    .file package.json
    .file app
    .children
      .file js
      .children
        .file core
        .children
          .file checkmark.filter.js
          .file core.module.js
          .file phone.factory.js
        .file phone_detail
        .children
          .file phone_detail.html
          .file phone_detail.module.js
          .file phone_detail.controller.js
        .file phone_list
        .children
          .file phone_list.html
          .file phone_list.module.js
          .file phone_list.controller.js
        .file app.module.js
      .file css
      .children
        .file animations.css
        .file app.css
      .file img
      .children
        .file  ...
      .file phones
      .children
        .file  ...
      .file index.html
    .file test
    .children
      .file e2e
      .children
        .file scenarios.js
      .file unit
      .children
        .file checkmark.filter.spec.js
        .file phone_detail.controller.spec.js
        .file phone.factory.spec.js
        .file phone_list.controller.spec.js
      .file karma.conf.js
      .file protractor-conf.js

:marked
  This is actually a pretty good starting point. In particular, this organization
  follows the [Angular Style Guide](https://github.com/johnpapa/angular-styleguide),
  which is an important [preparation step](#following-the-angular-style-guide) before
  a successful upgrade.

  这确实是一个很好地起点。特别是，该结构遵循了[Angular Style Guide](https://github.com/johnpapa/angular-styleguide)，
  要想成功升级，这是一个很重要的[准备步骤](#following-the-angular-style-guide)。

  * Each controller, factory, and filter is in its own source file, as per the
    [Rule of 1](https://github.com/johnpapa/angular-styleguide#single-responsibility).

  * 每个控制器、工厂和过滤器都在它自己的源文件中 —— 就像[规则1](https://github.com/johnpapa/angular-styleguide#single-responsibility)所要求的。

  * The `core`, `phoneDetail`, and `phoneList` modules are each in their
    own subdirectory. Those subdirectories contain the JavaScript code as well as
    the HTML templates that go with each particular feature. This is in line with the
    [Folders-by-Feature Structure](https://github.com/johnpapa/angular-styleguide#style-y152)
    and [Modularity](https://github.com/johnpapa/angular-styleguide#modularity)
    rules.

  * `core`、`phoneDetail`和`phoneList`模块都在它们自己的子目录中。那些子目录除了包含HTML模板之外，还包含JavaScript代码，它们共同完成一个特性。
    这是[按特性分目录的结构](https://github.com/johnpapa/angular-styleguide#style-y152)
    和[模块化](https://github.com/johnpapa/angular-styleguide#modularity)规则所要求的。

:marked
  ## Switching to TypeScript And Module Loading
  ## 切换到TypeScript和模块加载器

  Since we're going to be writing our Angular 2 code in TypeScript, it makes sense to
  bring in the TypeScript compiler even before we begin upgrading.

  既然我们准备用TypeScript写Angular 2代码，那么在开始升级前先引入TypeScript编译器就很有意义了。

  In order to use TypeScript's ES2015 module system to `import` and `export` code, we're
  going to need a JavaScript module loader. Our application doesn't currently
  use one, and is just using plain old `&lt;script>` tags and the global `window` scope
  instead. We'll replace this approach with the
  [SystemJS loader](https://github.com/systemjs/systemjs).

  要用TypeScript的ES2015模块系统来`import`和`export`代码，就需要一个JavaScript模块加载器。
  我们的程序目前还没用到它，它只使用了老旧的`&lt;script>`标签和全局的`window`作用域。
  我们这就把这种方式换成[SystemJS加载器](https://github.com/systemjs/systemjs)。

.alert.is-helpful
  :marked
    Angular 2 itself doesn't require either TypeScript or SystemJS.
    There will soon be other editions of this guide that show how to
    do the upgrade using ES5.

    Angular 2本身并不需要TypeScript或SystemJS。
    本指南很快就会有另一个版本来展示如何用ES5进行升级。

:marked
  We will also start to gradually phase out the Bower package manager in favor
  of NPM. We'll install all new dependencies using NPM, and will eventually be
  able to remove Bower from the project.

  我们还将开始逐步淘汰Bower包管理器，换成我们更喜欢的NPM。后面我们将使用NPM来安装新的依赖包，并最终从项目中移除Bower。

  Let's begin by installing the SystemJS and TypeScript packages to the project.
  While we're at it, let's also install the
  [Typings type definition manager](https://github.com/typings/typings).
  It will allow us to install type definitions for libraries that don't come with
  prepackaged types.

  让我们从把SystemJS和TypeScript包安装到项目中开始。同时我们还将安装[typings类型定义管理器](https://github.com/typings/typings)。
  它将允许我们为那些没有提供内置类型信息的库文件安装类型定义。

code-example(format="").
  npm i systemjs --save
  npm i typescript typings --save-dev

:marked
  Let's also add run scripts for the `tsc` TypeScript compiler and the `typings`
  tool to `package.json`:

  我们还要把用来运行TypeScript编译器`tsc`和`typings`工具的脚本添加到`package.json`中：

+makeJson('upgrade-phonecat/ts/typescript-conversion/package.1.json', {paths: 'scripts'}, 'package.json', {otl: /(\"tsc.*|\"typings.*)/g})


:marked
  We can now use Typings to install the type definitions for Angular 1 and the Jasmine
  unit test framework. This will add a `typings` directory to the project and install
  a number of `.d.ts` files under it. It will also create a `typings.json` file to the
  project, which contains metadata about the type definitions we've installed:

  现在我们可以使用typings工具来安装Angular 1和Jasmine单元测试框架的类型定义文件。这一步将会在项目中创建一个`typings`目录，
  并把一些`.d.ts`文件添加到此目录下。它还将在项目中创建一个`typings.json`文件，其中包含了我们已经安装的这些类型定义文件的元数据：

code-example(format="").
  npm run typings install jquery -- --save --global
  npm run typings install angular -- --save --global
  npm run typings install angular-route -- --save --global
  npm run typings install angular-resource -- --save --global
  npm run typings install angular-mocks -- --save --global
  npm run typings install jasmine -- --save --global

:marked
  In `index.html`, let's now enable SystemJS. Add a couple of `&lt;script>` tags that
  load the SystemJS library and then one that loads a configuration file for
  it. Then add one more `&lt;script>` tag that uses SystemJS to load our application.
  These will *replace* the various `&lt;script>` tags we had earlier for loading the
  application components:

  在`index.html`中，我们启用SystemJS。添加一组用于加载SystemJS库和一个为它加载配置文件的`&lt;script>`标签。
  然后添加更多的`&lt;script>`标签，以通过SystemJS加载我们的应用。
  它将会*替换掉*我们以前用来为应用程序加载组件的许多`&lt;script>`标签。

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/index.html', 'scripts', 'app/index.html')

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/systemjs.config.js', ull, 'app/systemjs.config.js')

:marked
  This tells SystemJS that we have a module called `app.module` that
  resides in the `js` subdirectory (relative to the `index.html` page). We then load that
  module using `System.import`. This will load and execute the `app/app.module.js` file.

  这些代码告诉SystemJS，我们有一个名叫`app.module`的模块，它被放在`js`子目录下(相对于`index.html`页面的位置)。
  然后我们使用`System.import`来加载该模块。这将加载并执行`app/app.module.js`文件。

  We should also configure the TypeScript compiler so that it can understand our
  project. We'll add a `tsconfig.json` file to the project directory, just like we did
  in the [Quickstart](../quickstart.html). It instructs the TypeScript compiler how
  to interpret our source files.

  我们还应该配置TypeScript编译器，以便它能理解我们的项目结构。我们要往项目目录下添加一个`tsconfig.json`文件，
  就像在[“快速起步”](../quickstart.html)中做过的那样。它将告诉TypeScript编译器，该如何解释我们的源文件。

+makeJson('upgrade-phonecat/ts/typescript-conversion/tsconfig.1.json', null, 'tsconfig.json')

:marked
  We are telling the TypeScript compiler to turn our TypeScript files to ES5 code
  bundled into SystemJS modules. In other words, our compiler target is something
  SystemJS can load and all major browsers are able to run.

  我们正在告诉TypeScript编译器如何把TypeScript文件转换成能在SystemJS模块中使用的ES5代码。
  换句话说，我们编译的目标是生成能被SystemJS加载且能被主流浏览器运行的东西。

  We can now launch the TypeScript compiler from the command line. It will watch
  our `.ts` source files and compile them to JavaScript on the fly. Those compiled
  `.js` files are then loaded into the browser by SystemJS. This is a process we'll
  want to have continuously running in the background as we go along.

  我们现在可以从命令行启动TypeScript编译器。它将监控`.ts`源码文件，并随时把它们编译成JavaScript。
  然后这些编译出的`.js`文件被SystemJS加载到浏览器中。当我们继续往前走的时候，这个过程能在后台持续运行。

code-example(format="").
  npm run tsc

:marked
  The next thing we'll do is convert our JavaScript files to TypeScript and define
  their imports and exports. Each file should now explicitly export the things
  it wants to expose, and import the things it needs from other files. This is a
  departure from the previous approach which just relied on things being available
  on the global `window` scope.

  我们要做的下一件事是把JavaScript文件转换成TypeScript文件，并定义它们的导入和导出项。
  每个文件都应该显式的导出它想暴露给外界的一切，并且导入它需要从别的文件中得到的东西。
  这种方法不同于以前那种把所依赖的一切都放在全局`window`作用域的方法。

  Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset
  of ECMAScript 5, we can simply switch the file extensions from `.js` to `.ts`
  and define the imports and exports. We don't need to make other changes to
  our existing code. Instead we'll introduce type annotations and other new
  features gradually over time.

  由于TypeScript是ECMAScript 2015的一个超集，而ES2015又是ECMAScript 5的超集，所以我们可以简单的把文件的扩展名从`.js`换成`.ts`，并定义导入和导出。
  我们不用对现有代码做任何其它的修改。不过，我们将在一段时间内逐步引入类型注解和其它新特性。

  Let's begin by renaming `app.module.js` to `app.module.ts`. The TypeScript
  compiler should be able to compile it successfully right away. This means we can
  move right along and go through the rest of our source files and convert them.
  We'll rename each one to a `.ts` file, and add the imports and exports it needs.

  让我们开始把`app.module.js`改名为`app.module.ts`。这个TypeScript编译器应该仍然能成功编译它。
  这意味着我们可以逐步、一点点的转换源文件中的其它部分。
  我们将把每一个改名为`.ts`文件，并在必要时添加导入和导出语句。

  Beginning from the checkmark filter, here are the converted contents:

  我们从对勾(`checkmark`)过滤器开始，下面是转换后的内容:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/core/checkmark.filter.ts', null, 'app/js/core/checkmark.filter.ts')

:marked
  This file now has the filter factory function as the default export. Apart from
  the export, there's one other major change we've applied to the file, which
  is that it does *not* contain the registration of the filter into an Angular
  module. We will do that later in the `core` module's main file.

  该文件现在以一个过滤器工厂函数作为默认导出。在离导出语句稍远的地方，我们对此文件做了另一项主要改动，那就是它*没有*把此过滤器注册到Angular模块中。
  稍后我们将在`core`模块的主文件中进行注册。

  Moving to the `Phone` factory file, it now has the factory function as the default
  export:

  再来看`Phone`工厂文件，它现在用一个工厂方法作为默认导出：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/core/phone.factory.ts', null, 'app/js/core/phone.factory.ts')

:marked
  The `core` module's main module file will now import both the checkmark filter
  and the Phone factory. This is where we actually register them into the Angular module.
  We then export the module itself as this file's default export:

  `core`模块的主文件将导入`checkmark`过滤器和`Phone`工厂。这里就是我们将把它们实际注册到Angular模块中的地方。
  然后我们把这个模块本身作为该文件的默认导出项：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  Notice that with this organization pattern, the files that hold the application
  components themselves - filters and factories - aren't concerned with the makeup
  of Angular modules. That's just something we previously *had* to do because there
  were no other good solutions. Now we use a separate file just for the purpose
  of forming the Angular module.

  注意，使用这种项目组织模式，这些文件保存程序的构造块本身(过滤器和工厂)，而不关心Angular模块之类的概念。
  Angular模块是我们以前*不得不用*的办法，因为当时还没有其它更好的解决方案。
  现在，有了模块加载器的支持，我们使用独立的文件也能达到和以前同样的效果了。

  Now switching to the phone detail module, we'll make similar changes here. In the
  controller file we export the controller function as the default export:

  现在，切换到电话详情(phone detail)模块，我们将在这里做一些类似的改动。
  在控制器文件中，我们把控制器函数作为默认导出：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.ts')

:marked
  In the main module file we import the controller and register it into the Angular
  module, which itself is then exported:

  在该模块的主文件中，我们导入了该控制器，并把它注册到Angular模块中，然后导出模块自身：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_detail/phone_detail.module.ts', null, 'app/js/phone_detail/phone_detail.module.ts')

:marked
  Then we'll repeat the same steps once more for the phone list module.
  The controller file exports the controller function:

  然后，我们又一次在电话列表(phone list)模块中重复同样的步骤。
  该控制器文件导出控制其函数：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  And the main module file imports the controller and registers it:

  该模块的主文件导入了此控制器，并注册它：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_list/phone_list.module.ts', null, 'app/js/phone_list/phone_list.module.ts')

:marked
  Finally, we can now pull everything together in `app.module.ts`. We'll
  import each of the three submodule files and register them as dependencies
  of the main application module:

  最终，我们在`app.module.ts`中把每一样东西都拉在一起。我们将导入这三个子模块文件，并把它们注册为主应用模块的依赖：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/app.module.ts', 'pre-bootstrap', 'app/js/app.module.ts')

:marked
  Note that we don't have to repeat the submodule name strings here. Since the
  modules export themselves, we can just refer to the `name` attribute of each
  of them.

  注意，我们并不用在这里重复写子模块的名称字符串。由于这些模块都导出了它们资深，因此我们只要引用它们各自的`name`属性就够了。

  Before this converted version of the application will run, we need to change the
  way we're bootstrapping it. It is currently bootstrapped using the `ng-app` directive
  attached to the `<html>` element of the host page. This will no longer work because
  `ng-app` is processed when the page loads, and our application code will not
  be available at that point yet. It is loaded asynchronously by SystemJS instead.

  在这个转换完的新版应用运行之前，我们还得修改它的引导方式。它目前是通过把`ng-app`指令附加到宿主页面的`<html>`元素上进行引导的。
  但现在这种方式不再工作，因为`ng-app`会在页面加载时被处理，而我们的应用代码在那个时间点上还是不可用的。因为这些代码已经改为用SystemJS进行异步加载了。

  We should switch to a JavaScript-driven bootstrap instead. As it happens, this is
  also how Angular 2 apps are bootstrapped, so the switch brings us one step closer
  to Angular as well. So, remove the `ng-app` attribute from `index.html`, and add
  this at the end of `app.module.ts`:

  替代方案是切换到由JavaScript驱动的引导方式，这也是Angular 2引导应用程序的方式。
  于是，这次切换让我们离Angular 2又近了一步儿。所以，从`index.html`中移除`ng-app`属性，并且把这段代码加到`app.module.ts`的末尾：

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/app.module.ts', 'bootstrap', 'app/js/app.module.ts')

:marked
  We now have a fully functional version of the application, all converted
  into TypeScript code and a modern module system! If you start the project HTTP
  server with `npm start`, you should see the fully functional application in
  your browser. On the other hand, if you were to try running the *test suite*,
  things wouldn't look quite that good yet. We also have to make our tests
  support our new module organization.

  现在，我们有了一个全功能的应用版本，完全转换成了TypeScript代码和一个现代模块化系统！
  如果通过`npm start`启动了项目的HTTP开发服务器，你就能在浏览器中看到这个全功能的应用程序了。
  另一方面，如果我们尝试运行*测试套件*，事情看起来仍然不妙。接下来，我们也要让这些测试支持新的模块组织方式。

:marked
  ## Preparing Tests
  ## 准备测试

  Our project has both E2E Protractor tests and some Karma unit tests in it.
  Of these two, E2E tests can be dealt with much quicker: By definition,
  E2E tests access our application from the *outside* by interacting with
  the various UI elements the app puts on the screen. E2E tests aren't really that
  concerned with the internal structure of the application components. That
  also means that although we've modified our project quite a bit, the E2E
  test suite should keep passing just as it was before. We haven't changed
  how the app behaves from the user's point of view.

  这个项目中同时有基于Protractor的E2E测试和一些基于Karma的单元测试。
  对这两者来说，E2E测试的转换要快得多：根据定义，E2E测试通过与应用中显示的这些UI元素互动，从*外部*访问我们的应用来进行测试。
  E2E测试实际上并不关心这些应用代码的内部结构。这也意味着，虽然我们已经修改了一点儿此应用程序，
  但是E2E测试套件仍然应该能像以前一样全部通过。因为从用户的角度来说，我们并没有改变应用的行为。

  For unit tests, on the other hand, we'll do a bit of conversion work.
  What we'll do is convert our existing unit tests to TypeScript and have them
  use `import`s to load in the code they need.

  另一方面，对单元测试来说，我们就要做一点转换工作了。
  我们要做的就是把现存的单元测试转换成TypeScript，并让它们通过`import`语句来加载所需的代码。

  We'll also need to tweak our Karma configuration so that it'll let SystemJS load
  the application files. For this we'll use a shim file that will tweak the way
  files get loaded:

  我们还需要调整一下Karma配置，以便让Karma能通过SystemJS加载应用程序中的文件。因此，我们将使用一个垫片(shim)文件，它将调整文件的加载方式：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/karma_test_shim.js', null, 'test/karma_test_shim.js')

.alert.is-important The shim is likely to be replaced by improved tooling, but is currently needed.
.alert.is-important 垫片(shim)可能会被改进过的工具所取代，但目前我们还需要它。

:marked
  We'll then update the Karma configuration file, so that it loads SystemJS and the
  shim file. We'll also change how the app and unit tests files themselves are loaded.
  We will *watch* them so that the test suite is triggered when changes occur, but we
  won't have Karma *include* them because that is now done by SystemJS and the shim.

  我们将更新Karma配置文件，以便它能加载SystemJS和垫片文件。我们还将修改应用文件和单元测试文件本身的加载方式。
  我们将*监视(`watch`)*它们的变化，以便在发生修改时自动触发测试套件，但我们不会用Karma来*包含(`include`)*这些文件，
  因为这项工作现在已经改由SystemJS和垫片来完成了。

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/karma.conf.1.js', 'files', 'test/karma.conf.js')

:marked
  Now we have the infrastructure in place and can convert the test files themselves.
  This mainly just consists for changing the file extensions of those files, and adding
  the necessary imports to them.

  现在，我们做好了基础设施，可以开始转化测试文件本身了。
  首要的工作是修改哪些文件的扩展名，并为它们添加必要的导入语句。

  In the checkmark filter spec, we'll import the core module file, so that it is
  available when we load the corresponding Angular module:

  在对勾(`checkmark`)过滤器的测试规约中，我们将导入`core`模块文件，以便当我们加载相应的Angular模块时它是可用的：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/checkmark.filter.spec.ts', 'top', 'test/unit/checkmark.filter.spec.ts')

:marked
  We'll do the exact same thing for the phone factory spec:

  我们要做的和`Phone`工厂类的规约完全一样：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone.factory.spec.ts', 'top', 'test/unit/phone.factory.spec.ts')

:marked
  In the phone detail controller spec, on the other hand, we should import
  the phone detail module:

  不过，在这个“电话详情(phone detail)”控制器的规约中，我们要导入“电话详情”模块：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone_detail.controller.spec.ts', 'top', 'test/unit/phone_detail.controller.spec.ts')

:marked
  Finally, the phone list controller spec should import the phone list
  module:

  最后，“电话列表(phone list)”控制器的规约应该导入“电话列表”模块：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone_list.controller.spec.ts', 'top', 'test/unit/phone_list.controller.spec.ts')

:marked
  There's one more issue we have in our controller tests, which is that TypeScript
  isn't happy about compiling them at the moment. This is because we're using
  the custom Jasmine matcher `toEqualData` in both of them. Because this is something
  we define ourselves, it isn't included in the Jasmine type definitions that we
  installed using Typings.

  在我们这些控制器的单元测试中还有一个问题，那就是TypeScript此刻还无法正常编译它们。
  这是因为我们正在这些文件中使用一个自定义的Jasmine匹配器`toEqualData`。
  因为这是我们自己定义的，所以它没有包含在我们通过typings工具安装的Jasmine类型定义中。

  We can add our own little type definition file for that extension, which extends
  the `jasmine.Matchers` interface and adds our custom matcher to it. This will
  satisfy the compiler and let us use our custom matcher while retaining the nice
  type safety features of TypeScript:

  我们可以为这个扩展添加一个自己的小型类型定义文件，它扩展了`jasmine.Matchers`接口，并把我们的自定义匹配器添加进去。
  这将满足编译器的要求，并且让我们的自定义匹配器能保留TypeScript中漂亮的类型安全特性：

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/jasmine_matchers.d.ts', null, 'test/jasmine_matchers.d.ts')

:marked
  And now we have a fully functional test suite for our TypeScript-enabled
  application as well.

  现在，我们启用完TypeScript的应用也有全功能的测试套件了。

:marked
  ## Enjoying The Benefits of TypeScript
  ## 享受TypeScript的优点

  Now that we have TypeScript, we can start benefiting from some of its
  other features in addition to the imports and exports that we're already using.
  There's a lot of value the language can provide in Angular 1 applications.

  现在，我们有了TypeScript，可以享用除了导入导出之外的更多优秀特性了。
  该语言的很多价值也同样可用在Angular 1程序中。

  For one thing, TypeScript is a superset of ES2015. Any app that has previously
  been written in ES5 - like the PhoneCat example has - can with TypeScript
  start incorporating all of the JavaScript features that are new to ES2015.
  These include things like `let`s and `const`s, default function parameters,
  and destructuring assignments.

  首先，TypeScript是一个ES2015的超集。任何以前用ES5写的程序（就像PhoneCat范例）都可以开始通过TypeScript
  纳入那些添加到ES2015中的新特性。
  这包括`let`、`const`、函数默认参数以及解构(destructure)赋值。

  Another thing we can do is start adding *type safety* to our code, by
  adding type annotations. For instance, we can annotate the checkmark
  filter so that it expects booleans as arguments and returns strings.
  This makes it clearer what the filter is supposed to do, and makes it
  possible for the TypeScript compiler to notify us when we're trying to
  use it with incompatible types.

  我们能做的另一件事就是通过添加类型注解来把*类型安全*添加到代码中。
  比如，我们可以给`checkmark`过滤器加上注解，表明它期待一个`boolean`类型的参数，并返回`string`。
  这可以更清楚的表明此过滤器打算做什么，而且如果我们尝试通过类型不兼容的参数使用它，TypeScript编译器就会通知我们。

+makeExample('upgrade-phonecat/ts/classes/app/js/core/checkmark.filter.ts', null, 'app/js/core/checkmark.filter.ts', {otl: /(:\w+)/g})

.l-sub-section
  :marked
    The [Angular 1.x type definitions](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/angularjs)
    we installed with Typings are not officially maintained by the Angular team,
    but are quite comprehensive. Though we're not going to do it in this
    tutorial, it is possible to make an Angular 1.x application fully
    type-annotated with the help of these definitions.

    我们用typings工具安装的这个[Angular 1.x类型定义文件](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/angularjs)
    并不是由Angular开发组维护的，但它也已经足够全面了。虽然我们并不打算在本教程中这么做，但借助这些类型定义给Angular 1.x程序全面加上类型注解也是可能的。

    If this is something we wanted to do, it would be a good idea to enable
    the `noImplicitAny` configuration option in `tsconfig.json`. This would
    cause the TypeScript compiler to display a warning when there's any code that
    does not yet have type annotations. We could use it as a guide to inform
    us about how close we are to having a fully annotated project.

    如果我们想这么做，那么在`tsconfig.json`中启用`noImplicitAny`配置项就是一个好主意。
    这样，如果遇到什么还没有类型注解的代码，TypeScript编译器就会显示一个警告。
    我们可以用它作为指南，告诉我们现在离得到一个完全类型化的项目还有多远。

:marked
  Another TypeScript feature we can make use of is *classes*. In particular, we
  can turn our controllers into classes. That way they'll be a step
  closer to becoming Angular 2 component classes, which will make our life
  easier once we do the upgrade.

  我们能用的另一个TypeScript特性是*类*。特别是，我们可以把控制器转换成类。
  这种方式下，我们离成为Angular 2组件类就又近了一步，它会令我们的升级之路变得更简单。

  Angular 1 expects controllers to be constructor functions. That's what
  ES2015/TypeScript classes really are, so that means we can just register a
  class as a controller and Angular 1 will happily use it. We also won't
  need to make any changes to our test suite as the external behavior of the
  controllers will not change.

  Angular 1期望控制器是一个构造函数。这实际上就是ES2015/TypeScript中的类，
  这也就意味着只要我们把一个类注册为控制器，Angular 1就会愉快的使用它。
  我们也不需要对测试套件做任何改变，因为该控制器的外在行为没有发生任何改变。

  Here's what our new class for the phone list controller looks like.

  新的“电话列表(phone list)”控制器类看起来是这样的：

+makeExample('upgrade-phonecat/ts/classes/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  What was previously done in the controller function is now done in the class
  constructor function. The class additionally declares three members: The
  array of phones, the name of the current sort key, and the search query. These
  are all things we have already been attaching to the controller,
  but that weren't explicitly declared anywhere. The last one of these isn't actually
  used in the TypeScript code since it's only referred to in the template, but for
  the sake of clarity we want to define all the members our controller will have.

  以前在控制器函数中实现的一切现在都改由类的构造函数来实现了。该类额外定义了三个成员：电话列表、当前排序键的名字，以及搜索条件。
  这些东西我们以前就加到了控制器上，只是从来没有在任何地方显式定义过它们。最后一个成员从未真正在TypeScript代码中用过，
  因为它只是在模板中被引用过。但为了清晰起见，我们还是该定义出此控制器应有的所有成员。

  In the Phone detail controller we'll have two members: One for the phone
  that the user is looking at and another for the URL of the currently displayed image.
  We can additionally introduce a TypeScript interface that explicitly defines
  what we expect the `$routeParams` object to contain when it is
  passed to the controller. This interface is not exported and is just used internally
  inside this module:

  在电话详情控制器中，我们有两个成员：一个是用户正在查看的电话，另一个是正在显示的图像的URL。
  我们可以额外引入一个TypeScript接口，它显式定义出当`$routeParams`对象被传给控制器时，我们期望它包含哪些参数。
  这个接口没有被导出，它只在本模块的内部使用：

+makeExample('upgrade-phonecat/ts/classes/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.ts')

:marked
  This makes our controller code look a lot more like Angular 2 already. We're
  all set to actually introduce Angular 2 into the project.

  这已经让我们的控制器代码看起来更像Angular 2了。我们所做的这些事情实际上都是在把Angular 2导入项目中。

  If we had any Angular 1 services in the project, those would also be
  a good candidate for converting to classes, since like controllers,
  they're also constructor functions. But we only have the `Phone` factory
  in this project, and that's a bit special since it's an `ngResource`
  factory. So we won't be doing anything to it in the preparation stage.
  We'll instead turn it directly into an Angular 2 service in the
  next section.







  如果项目中有任何Angular 1的服务，它们也是转换成类的优秀候选人，像控制器一样，它们也有构造函数。
  但是在本项目中，我们只有一个`Phone`工厂，这有点特别，因为它是一个`ngResource`工厂。
  所以我们不会在准备阶段中处理它，而是在下一节中直接把它转换成Angular 2服务。

.l-main-section
:marked
  # PhoneCat Upgrade Tutorial
  # PhoneCat升级指南

  Having completed our preparation work, let's get going with the Angular 2
  upgrade of PhoneCat. We'll do this incrementally with the help of the
  [upgrade module](#upgrading-with-the-upgrade-adapter) that comes with Angular 2.
  By the time we're done, we'll be able to remove Angular 1 from the project
  completely, but the key is to do this piece by piece without breaking the application.

  我们已经完成了准备工作，接下来就开始把PhoneCat升级到Angular 2。
  我们将在Angular 2 [`upgrade`模块](#upgrading-with-the-upgrade-adapter)的帮助下增量式的完成此项工作。
  等我们完成的那一刻，就能把Angular 1从项目中完全移除了，但其中的关键是在不破坏此程序的前提下一小块儿一小块儿的完成它。

.alert.is-important The project also contains some animations, which we are not yet upgrading in this version of the guide. This will change in a later release.
.alert.is-important 该项目还包含一些动画，在此指南的当前版本我们先不升级它，等到后面的发行版再改。

:marked
  Let's install Angular 2 into the project. Add the Angular 2 dependencies
  to `package.json` and `typings.json` as described in the [Quickstart](../quickstart.html).
  Then run:

  我们来把Angular 2安装到项目中。像[“快速起步”](../quickstart.html)中描述的那样，把Angular 2的依赖包添加到`package.json`和`typings.json`中。
  然后运行：

code-example(format="").
  npm install
  npm run typings install

:marked
  We should then load some Angular 2 dependencies into the application by adding
  some `&lt;script>` tags to `index.html`. They should go before the `&lt;script>` tag
  that loads `systemjs.config.js`:

  然后，通过往`index.html`中添加一些`&lt;script>`标签，我们把一些Angular 2依赖包加载到程序中。
  它们应该位于加载`systemjs.config.js`的`&lt;script>`标签之前：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/index.html', 'ng2')

:marked
  We can then load Angular 2 itself by adding its packages into the `systemjs.config.js`
  file:

  然后我们就可以把它的npm包添加到`systemjs.config.js`文件中来加载Angular 2本身：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/systemjs.config.js', null, 'app/systemjs.config.js')

:marked
  While we're at it, let's also make these files available to unit tests by
  updating the Karma config:

  既然我们已经到这里了，那就干脆同时更新一下Karma配置，让这些文件也能在单元测试中可用：

+makeExample('upgrade-phonecat/ts/ng2_initial/test/karma.conf.1.js', 'ng2', 'test/karma.conf.js')

:marked
  ## Bootstrapping A Hybrid 1+2 PhoneCat
  ## 引导PhoneCat的1+2混合式应用

  What we'll do next is bootstrap the application as a *hybrid application*
  that supports both Angular 1 and Angular 2 components. Once we've done that
  we can start converting the individual pieces to Angular 2.

  我们后面将做的就是把该应用程序引导为一个同时支持Angular 1和Angular 2的*混合式应用*。
  一旦我们做完了，就能开始把这些不可分割的小块儿转换到Angular 2了.

  At this point we need to do add the Angular 2 type definitions
  into `app.ts`, so that the TypeScript compiler knows what we're talking about
  when we use Angular 2 APIs. Unlike with Angular 1, we don't need to install
  these type definitions with Typings because Angular 2 comes with them included.
  What we do need to do is set the TypeScript compiler's `moduleResolution` option
  to `node`, so that it knows to look for these definitions from the `angular2` NPM
  package.

  此时，我们就需要把Angular 2类型定义添加到`app.ts`中了，这样当使用Angular 2 API的时候，
  TypeScript编译器才能知道我们在说什么。和Angular 1中不同，我们不需要借助typings来安装这些类型定义文件，
  因为Angular 2自带了它们。我们所要做的就是把TypeScript编译器的`moduleResolution`选项设置为`node`，
  来让编译器知道应该从`angular2`这个NPM包中查找这些类型定义。

+makeJson('upgrade-phonecat/ts/ng2_initial/tsconfig.1.json', null, 'tsconfig.json', {otl: /(\"moduleResolution.*)/})

:marked
  To boostrap a hybrid application, we first need to initialize an `UpgradeAdapter`,
  which [provides the glue](#upgrading-with-the-upgrade-adapter) that joins the two
  versions of the framework together. Let's import the `UpgradeAdapter` class into
  `app.module.ts`:

  要引导一个混合式应用，我们首先得初始化一个`UpgradeAdapter`，它[提供了“胶水”](#upgrading-with-the-upgrade-adapter)来把两个版本的框架粘在一起。
  我们来把`UpgradeAdapter`类导入`app.module.ts`中：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'adapter-import', 'app/js/app.module.ts')

:marked
  We can then make an adapter by instantiating the class:

  然后我们可以制作一个适配器来实例化这个类：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/upgrade_adapter.ts', 'adapter-init')

:marked
  Now we can use that adapter to bootstrap our application as a hybrid.
  Instead of calling `angular.bootstrap`, we must call
  `upgradeAdapter.bootstrap`, but the function arguments remain the same:
  They are still the element that will become the root of the application,
  and the names of the root Angular 1.x modules that we want to include:

  现在，我们就能使用这个适配器来把我们的应用引导为混合式应用了。我们必须调用`upgradeAdapter.bootstrap`以代替`angular.bootstrap`函数，
  但函数的参数跟以前是一样的：第一个仍然是那个将用作该应用程序根节点的元素，第二个仍然是我们要包含的那个Angular 1.x根模块的名字。

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'bootstrap')

:marked
  We are now running both Angular 1 and 2 at the same time. That's pretty
  exciting! We're not running any actual Angular 2 components yet though,
  so let's do that next.


  我们现在同时运行着Angular 1和Angular 2。漂亮！不过我们还没有运行人和实际的Angular 2组件，接下来我们就做这件事。
:marked
  ## Upgrading the Phone factory
  ## 升级`Phone`工厂

  The first piece we'll port over to Angular 2 is the `Phone` factory, which
  resides in `app/js/core/phones.factory.ts` and makes it possible for controllers
  to load phone information from the server. Right now it's implemented with
  ngResource and we're using it for two things:

  我们要移植到Angular 2的第一块儿是`Phone`工厂(位于`app/js/core/phones.factory.ts`)，
  并且让它能帮助控制器从服务器上加载电话信息。目前，它是用`ngResource`实现的，我们用它做两件事：

  * For loading the list of all phones into the phone list controller
  * 把所有电话的列表加载到电话列表控制器中。
  * For loading the details of a single phone into the phone detail controller.
  * 把一台电话的详情加载到电话详情控制器中。

  We can replace this implementation with an Angular 2 service class, while
  keeping our controllers in Angular 1 land. In the new version we'll just use
  the `Http` service from Angular 2 instead of ngResource.

  我们可以用Angular 2的服务类来替换这个实现，而把控制器继续留在Angular 1的地盘上。
  在新版本中，我们将用来自Angular 2的`Http`服务代替`ngResource`。

  Before the `Http` service is available for injection, we need to register
  it into our application's dependency injector. We should import the `HTTP_PROVIDERS`
  constant in `app.module.ts`:

  要让`Http`服务在注入时可用，我们得先把它注册进我们应用程序的依赖注入器中。我们要把`HTTP_PROVIDERS`常量导入到`app.module.ts`中：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'http-import')

:marked
  In a regular Angular 2 application we would now pass `HTTP_PROVIDERS` into
  the application bootstrap function. But we can't do that in a hybrid
  application such as the one we're working on. That's because the `bootstrap`
  method of  `UpgradeAdapter` expects Angular 1 modules as dependencies,
  not Angular 2 providers.

  在标准的Angular 2应用中，我们可以把`HTTP_PROVIDERS`传给应用程序的`bootstrap`函数。
  但是在混合式应用中我们不能这么做 —— 比如现在这个。这是因为`UpgradeAdapter`的`bootstrap`方法
  希望以Angular 1模块作为依赖，而不是Angular 2供应商。

  What we must do instead is register `HTTP_PROVIDERS` into the `UpgradeAdapter`
  separately. It has a method called `addProvider` for that purpose:

  这就是为什么我们必须单独把`HTTP_PROVIDERS`注册进`UpgradeAdapter`。为此，它提供了一个叫做`addProvider`的方法：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'add-http-providers')

:marked
  Now we're ready to upgrade the Phones factory itself. We'll put the Angular 2
  implementation in a new file called `phones.service.ts` in the core module. It will be a TypeScript
  class decorated as `@Injectable`:

  现在，我们已经准备好了升级`Phones`工厂本身。我们将把Angular 2的实现放进`core`模块中一个名叫`phones.service.ts`的新文件中。
  它将是一个带有`@Injectable`装饰器的类：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'class', 'app/js/core/phones.service.ts')

:marked
  The `@Injectable` decorator will attach some dependency injection metadata
  to the class, letting Angular 2 know about its dependencies. As described
  by our [Dependency Injection Guide](../guide/dependency-injection.html),
  this is a marker decorator we need to use for classes that have no other
  Angular 2 decorators but still need to have their dependencies injected.

  `@Injectable`装饰器将把一些依赖注入相关的元数据附加到该类上，让Angular 2知道它的依赖信息。
  就像在[依赖注入指南](../guide/dependency-injection.html)中描述过的那样，
  这是一个标记装饰器，我们要把它用在那些没有其它Angular 2装饰器但仍然有依赖需要被注入进来的类上。

  In its constructor the class expects to get the `Http` service. It will
  be injected to it and it is stored as a private field. The service is then
  used in the two instance methods, one of which loads the list of all phones,
  and the other the details of a particular phone:

  在它的构造函数中，该类期待一个`Http`服务。`Http`服务将被注入进来并存入一个私有字段。
  然后该服务在两个实例方法中被使用到，一个加载所有电话的列表，另一个加载一台指定电话的详情：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'fullclass')

:marked
  The methods now return Observables of type `Phone` and `Phone[]`. This is
  a type we don't have yet, so let's add a simple interface for it:

  该方法现在返回一个`Phone`类型或`Phone[]`类型的可观察对象(Observable)。
  这是一个我们从未用过的类型，因此我们得为它新增一个简单的接口：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'phone-interface', 'app/js/core/phones.service.ts')

:marked
  Here's the full, final code for the service:

  最终，该类的全部代码如下：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'full', 'app/js/core/phones.service.ts')

:marked
  Notice that we're importing the `map` operator of the RxJS `Observable` separately.
  We need to do this for all RxJS operators that we want to use, since Angular 2
  does not load all of them by default.

  注意，我们单独导入了RxJS `Observable`中的`map`操作符。
  我们需要对想用的所有RxJS操作符这么做，因为Angular 2默认不会加载所有RxJS操作符。

  The new `Phones` service now has the same features that the original, ngResource based
  service did. You can remove the old `phones.factory.ts` file. Now we just
  need to register the new service into the application, so that our Angular 1
  controllers will be able to use it.

  这个新的`Phones`服务现在有了和原来基于`ngResource`的服务相同的特性。你可以移除老的`phones.factory.ts`文件了。
  现在只要把这个新服务注册进应用程序，我们的Angular 1控制器就能使用它了。

  `UpgradeAdapter` has a `downgradeNg2Provider` method for the purpose of making
  Angular 2 services available to Angular 1 code. The problem is that we don't have
  our `UpgradeAdapter` available in `core.module.ts` where the `Phones` service should
  be registered. We only have it in `app.module.ts`. There should only be one
  `UpgradeAdapter` in an application, so we need to find a way to share our
  instance between the two code modules.

  `UpgradeAdapter`有个`downgradeNg2Provider`就是用于让Angular 2的服务在Angular 1的代码中可用的。
  问题是我们的`UpgradeAdapter`在将用来注册`Phones`服务的`core.module.ts`中还不可用。
  它只在`app.module.ts`中有一个实例，而且它在一个应用程序中只应该有一个，所以我们得找到一种方法把该实例在两个代码模块中共享。

  What we'll do is create a new module that instantiates `UpgradeAdapter`
  and exports the instance. We can then just pull it in wherever we need it,
  so that we're using the same object everywhere. Let's put this new file
  under `core`:

  我们要做的就是创建一个新模块，它实例化`UpgradeAdapter`，并导出其实例。然后我们还要能在需要的地方获取它，
  以便我们在任何地方都用同一个实例。我们来把这个新文件放在`core`下：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/upgrade_adapter.ts', 'full', 'app/js/core/upgrade_adapter.ts')

:marked
  In `app.module.ts` we should now just import this adapter instead of making a separate one:

  在`app.module.ts`中，我们应该导入这个适配器，而不是自己做一份独立的：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'adapter-state-import')

:marked
  Also remove the line from `app.module.ts` that is instantiating `UpgradeAdapter`. It's no
  longer needed since we import the instance from elsewhere.

  同时从`app.module.ts`中移除实例化`UpgradeAdapter`的那行。它已经无用了，因为我们在任何地方都将导入那个唯一的实例。

  We'll then do the same in `core.module.ts` as well. Then we can register the `Phones` service into it.
  While doing that, we can remove the module's dependency to `ngResource`, which
  we're no longer using.

  我们在`core.module.ts`中也做同样的事情，然后我们就能把`Phones`服务注册到它里面了。
  同时，我们可以移除该模块对`ngResource`的依赖，我们不再用它了。

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  Note that we actually needed to do two registrations here:

  注意，我们实际上做了两次注册：

  1. Register `Phones` as an **Angular 2 provider** with the `addProvider`
     method. That's the same method that we used earlier for `HTTP_PROVIDERS`.

  1. 用`addProvider`方法注册了一个名叫`Phones`的**Angular 2供应商**。这和我们以前使用`HTTP_PROVIDERS`的方法一样。

  2. Register an **Angular 1 factory** called `phones`, which will be a *downgraded*
     version of the `Phones` service.

  2. 注册了一个名叫`phones`的**Angular 1工厂**，它是一个`Phones`服务的*降级*版。

  At this point we can switch our two controllers to use the new service
  instead of the old one. We `$inject` it as the downgraded `phones` factory,
  but it's really an instance of the `Phones` class and we can annotate its type
  accordingly:

  这时，我们可以把两个控制器从使用老的服务切换成使用新的。我们像降级过的`phones`工厂一样`$inject`它，
  但它实际上是一个`Phones`类的实例，并且我们可以据此注解它的类型：

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.ts')

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  What we have here are two Angular 1 controllers using an Angular 2 service!
  The controllers don't need to be aware of this, though the fact that the
  service returns Observables and not Promises is a bit of a giveaway.
  In any case, what we've achieved is a migration of a service to Angular 2
  without having to yet migrate the controllers that use it.

  这里的两个Angular 1控制器在使用Angular 2的服务！控制器不需要关心这一点，尽管实际上该服务返回的是可观察对象(Observable)，而不是承诺(Promise)。
  无论如何，我们达到的效果都是把服务移植到Angular 2，而不用被迫移植控制器来使用它。

.alert.is-helpful
  :marked
    You could use the `toPromise` method of `Observable` to turn those Observables
    into Promises in the service to further reduce the amount of changes
    needed in controller code.

    你可以使用`Observable`的`toPromise`方法来在服务中把这些可观察对象转变成承诺，以进一步减小控制器中需要修改的代码量。

:marked
  To bring our test suite up to speed with the changes, we should update the Karma
  test shim. It'll make some of Angular 2 providers available before starting
  to load any of the spec files:

  要让我们的测试套件跟上修改的速度，我们得更新Karma的测试垫片。它将在开始加载这些规约(`spec`)文件时，让Angular 2中的供应商可用。

+makeExample('upgrade-phonecat/ts/ng2_initial/test/karma_test_shim.js', null, 'test/karma_test_shim.js')

.alert.is-important The shim is likely to be replaced by improved tooling, but is needed right now.

.alert.is-important 垫片(shim)可能会被改进过的工具所取代，但目前我们还需要它。

:marked
  Now, let's look at the tests for the service itself. What we used to have in
  `phones_factory_spec.js` was a fairly simple test that simply checks if
  the factory exists and is available for injection. We can now do that same
  test in Angular 2. Rename `phones.factory.spec.ts` to `phones.service.spec.ts` and
  set the contents as follows:

  现在，我们看看该服务本身的测试。我们要在`phones_factory_spec.js`中用到的是相当简单的测试，它用于检查该工厂是否存在，以及是否能用于注入。
  我们现在就能在Angular 2中做同样的测试。把`phones.factory.spec.ts`改名为`phones.service.spec.ts`，并写入如下代码：

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phones.service.spec.ts', null, 'test/unit/phones.service.spec.ts')

:marked
  Here we first load the `Phones` provider and then test that an instance of
  `Phones` can in fact be injected. We also need to load `HTTP_PROVIDERS` since
  it is a dependency of `Phones`.

  我们先加载`Phones`供应商，然后测试是否一个`Phones`的实例能被注入。我们还需要加载`HTTP_PROVIDERS`，因为它是`Phones`的依赖之一。

  For the controller tests, we can first of all at this point get rid of the
  custom `toEqualData` custom matcher. It was added because `ngResource` attaches
  attributes to the data that we don't want to compare in tests. We're no longer
  using `ngResource`, so we can simply use the built-in `toEqual` for comparisons.
  This means we can remove the `test/jasmine_matchers.d.ts` file at this point.

  对于这些控制器的测试，我们可以首先摆脱惯用的自定义匹配器`toEqualData`。
  当初引入它是因为`ngResource`会把一些属性加到数据上，而我们不想在测试中比较它们。
  我们不再使用`ngResource`了，所以我们可以简单地使用内建的`toEqual`函数来进行比较。
  这意味着我们这时也可以移除`test/jasmine_matchers.d.ts`文件了。

  Now, in the phone detail controller we have been testing that the phone details
  with the id given in the route params are fetched over HTTP and put on the
  scope. We can continue doing that, but we'll need to change the structure of the
  test a bit. Instead of using the Angular 1 mock HTTP backend, we'll just mock out
  the `get` method of the `Phones` service, which is what the controller is now
  using to load what it needs. As the mocked value, we're returning an Observable
  that will emit a single value - the mock phone data:

  现在，在电话详情控制器中，我们已经测试了能通过HTTP取得路由参数中的ID所指定的那款电话的详情信息，并把它放到作用域(scope)上。
  我们可以继续这样做，不过我们需要改动一点点该测试的结构。我们不再使用Angular 1模拟HTTP后端，
  而是直接模拟出`Phones`服务的`get`方法，该控制器现在就是用它来加载所需数据的。作为被模拟的值，
  我们返回一个会发出单一值的可观察对象(Observable) —— 模拟的电话数据：

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phone_detail.controller.spec.ts', null, 'test/unit/phone_detail.controller.spec.ts')

.alert.is-important
  :marked
    We're doing a manual `Phones` instantiation because hybrid apps can't be
    bootstrapped for unit tests at the moment, which means that Angular 2
    dependencies can't be made available. This is likely to change.

    我们手工实例化了`Phones`，因为目前混合式应用还不能用于在单元测试中引导，这意味着Angular 2的依赖将不可用。
    这问题将来可能会解决。

:marked
  In the phone list controller we'll do something very similar: We mock out the `query`
  method of the `Phones` service, and check that the controller makes the resulting
  value available:

  在电话列表控制器中，我们将做一些类似的事情：我们模拟出`Phones`服务的`query`方法，并检查控制器得到的值是否可用：

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phone_list.controller.spec.ts', null, 'test/unit/phone_list.controller.spec.ts')

:marked
  ## Upgrading Controllers to Components
  ## 把控制器升级成组件

  Next, let's upgrade our Angular 1 controllers to Angular 2 components. We'll
  do it one at a time, while still keeping the application in hybrid mode.
  As we make these conversions, we'll also be defining our first Angular 2 *pipes*.

  接下来，我们把Angular 1的控制器升级成Angular 2的组件。我们每次升级一个，同时仍然保持应用运行在混合模式下。
  在做转换的同时，我们还将自定义首个Angular 2*管道*。

  Let's look at the phone list controller first. Right now it is a TypeScript class,
  which is paired with an HTML template by the route configuration in `app.ts`.
  We'll be turning it into an Angular 2 component.

  首先我们来看看电话列表控制器。目前，它是一个TypeScript类，通过`app.ts`中的路由配置和一个HTML模板成对使用。
  我们将把它转变成Angular 2组件。

  Rename `phone_list.controller.ts` to `phone_list.component.ts`. Then rename the controller class
  inside to just `PhoneList` and decorate it as a `@Component`:

  把`phone_list.controller.ts`改名为`phone_list.component.ts`。然后把控制器的类名改为只剩下`PhoneList`，并且给它添加一个`@Component`装饰器：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.component.ts', 'top', 'app/js/phone_list/phone_list.component.ts')

:marked
  The `selector` attribute is a CSS selector that defines where on the page the component
  should go. It will match elements by the name of `pc-phone-list`. It is a good idea
  to always use application-specific prefixes in selectors so that they never clash with
  built-in ones, and here we're using `pc-`, which is short for "PhoneCat".

  `selector`属性是一个CSS选择器，它定义出该组件在页面中放在哪里。它将根据`pc-phone-list`这个名字来匹配元素。
  总是在选择器中使用应用特有的前缀是个好主意，这样它们就永远不会和内建的名字冲突了，这里我们使用的是`pc-`前缀，它是"PhoneCat"的缩写。

  The `templateUrl` defines the location of the component template. It points to our existing
  template file

  `templateUrl`属性定义了组件模板的位置，它指向一个现有的模板文件。

  Both of these attributes are things that were defined *externally* for the controller,
  but for the component are things that it defines *itself*. This will affect how we use
  the component in the router.

  所有这些属性都是在控制器的外部定义的，但对组件来说却是*它自己*定义的。这将影响到我们如何在路由器中使用该组件。

:marked
  We now also need to convert the template of this component into Angular 2 syntax.
  In the search controls we need to use Angular 2 syntax for the two `ngModel`s

  现在，我们得把组件的模板转换成Angular 2的语法。在搜索控件中，我们要对两个`ngModel`改用Angular 2的语法：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.html', 'controls', 'app/js/phone_list/phone_list.html')

:marked
  In the list we need to replace the `ng-repeat` with an `*ngFor` and its
  `#var of iterable` syntax, which is [described in our
  Template Syntax guide](../guide/template-syntax.html#directives).

  在列表中，我们需要把`ng-repeat`替换为`*ngFor`以及它的`let var of iterable`语法，
  该语法在[模板语法指南中讲过](../guide/template-syntax.html#directives)。

  For the images, we can replace `ng-src` with the standard `src`, but will use a
  property binding. Note that we're also adding a `name` CSS class for the phone name.
  This is something we'll need for our Protractor tests:

  对图片，我们需要把`ng-src`替换为标准的`src`，但这次将使用一个属性(property)绑定。注意，我们也为电话的名称添加了CSS类`name`。
  这个类我们将在Protractor测试中用到：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  In the module file we're going to plug this component into our application. Instead
  of registering a controller, we register a `pcPhoneList` directive.
  The directive is a downgraded version of our component, and the `UpgradeAdapter`
  handles the bridging between the two:

  在模块文件中，我们将把这个组件插入到程序中。我们不再注册控制器，而是注册一个`pcPhoneList`指令。
  该指令是我们那个组件的降级版本，`UpgradeAdapter`负责桥接它们：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.module.ts', null, 'app/js/phone_list/phone_list.module.ts')

:marked
  The `<angular.IDirectiveFactory>` type annotation here is to let the TypeScript compiler
  know that the return value of the downgrade method call will be something that can be
  used as a directive factory.

  这里的`<angular.IDirectiveFactory>`类型注解是为了让TypeScript编译器知道这个降级方法(`downgradeNg2Component`)的返回值能作为指令工厂使用。

  To complete the switch, we should change our route configuration in `app.module.ts`.
  Instead of using the controller and template, it can just instantiate our component.
  We can do that by using a simple template that uses the directive
  we just registered:

  要完成这次切换，还应该在`app.module.ts`中改变我们的路由配置。
  不使用控制器和模板，也能实例化我们的组件。借助一个带有刚注册的这个指令的简单模板，我们就能做到这一点：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'list-route')

:marked
  When the application runs, the Angular 1.x directive compiler will match
  the element in the template to the `pcPhoneList` directive, which is actually
  an Angular 2 component!

  当应用程序运行起来时，Angular 1.x的指令编译器将匹配到模板中适用于`pcPhoneList`指令的元素，它实际上是个Angular 2组件！

  The remaining issue with the phone list is the use of filters in its
  template: It is referring to the `filter` filter and the `orderBy` filter,
  and relying on them to filter and sort the phone list, respectively.
  These pipes do not exist in Angular 2, so we're going to need to do
  the filtering and sorting ourselves. Let's define a couple of pipes that
  get the job done.

  电话列表剩下的问题就是模板中过滤器的使用：它引用了`filter`过滤器和`orderBy`过滤器，
  并依靠它们来对电话列表进行过滤和排序。这些管道在Angualr 2中不存在，所以我们得自己实现过滤和排序功能。
  我们来定义两个管道来完成这项工作。

.alert.is-helpful
  :marked
    If you want to learn more about how pipes in Angular 2
    work, we have [a whole guide on the subject](../guide/pipes.html)
    available!

    如果你想学习关于Angular 2中管道的更多知识，我们在开发指南中有[一个完整的主题](../guide/pipes.html)讲它们。

:marked
  For filtering, we'll have a pipe called `PhoneFilterPipe`. It works like
  the `filter` filter in Angular 1 in that it filters a collection of objects,
  matching properties within the objects. But, as opposed to `filter`,
  this pipe is specialized to filter `Phone` objects and we can use
  type annotations to make this explicit:

  要想过滤，我们得有一个名叫`PhoneFilterPipe`的管道。它工作起来就像Angular 1中的`filter`过滤器，它会过滤一组对象，并匹配对象中的属性。
  但是，与`filter`相反，这个管道只能过滤`Phone`对象，而且我们会通过类型注解把它明确标示出来：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_filter.pipe.ts', null, 'app/js/phone_list/phone_filter.pipe.ts')

:marked
  Since we're adding new code, it's a good idea to add some unit tests for
  it too. Here are a few tests for `PhoneFilterPipe`:

  由于我们在写新代码，所以最好同时为它写一些单元测试。
  下面是一些针对`PhoneFilterPipe`的单元测试：

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_filter.pipe.spec.ts', null, 'test/unit/phone_filter.pipe.spec.ts')

:marked
  For sorting, we'll use a more generic pipe, just called `OrderBy`. It
  takes an array of objects, and a property to order the array by. It returns
  an array of the same type of thing it was given. In the implementation we
  copy the input array, sort the copy, and return it.

  要想排序，我们就需要一个更通用的管道了，称之为`OrderBy`。它接收一个对象数组，和一个用来作为排序依据的属性。
  它返回与所获得的参数同一类型的数组。在这个实现中，我们将拷贝一份此输入数组，排序它，然后返回它。

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/order_by.pipe.ts', null, 'app/js/phone_list/order_by.pipe.ts')

:marked
  Here's a unit test for `OrderByPipe` as well:

  下面同样是`OrderByPipe`的单元测试：

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/order_by.pipe.spec.ts', null, 'test/unit/order_by.pipe.spec.ts')

:marked
  We can now integrate these new pipes with our component. Before the pipes
  are available there, we need to declare them in the `@Component` decorator.

  我们可以把这些新的管道集成进组件中。要想让这些管道可用，我们得把它们声明在`@Component`装饰器中。

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.component.ts', 'top', 'app/js/phone_list/phone_list.component.ts')

:marked
  In the template we need to use the `phoneFilter` pipe instead of `filter`.
  No changes are needed for the `orderBy`

  在这个模板中，我们要用`phoneFilter`管道代替`filter`。
  而对`orderBy`则什么也不用改。

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_async.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  Now that the phone list is an Angular 2 component, there's one more neat trick
  we can apply to make its code a little bit simpler. Earlier, as we upgraded
  the `Phones` service, we needed to add a `subscribe` callback to the list
  response, which populated the `phones` array on the component.
  With Angular 2, we can instead just put the Observable itself on the
  component, and can skip the subscription callback:

  现在，电话列表变成了一个Angular 2组件，还有一个小把戏能让它更整洁：我们可以让它的代码更简单一点。
  以前，当我们升级`Phones`服务时，我们需要往列表的回应里添加一个`subscribe`(订阅)回调，它会把数据放在组件的`phones`数组中。
  在Angular 2中，我们可以改为直接把这个可观察对象(Observable)本身放进组件中，而不再使用订阅回调：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.component.ts', 'full', 'app/js/phone_list/phone_list.component.ts')

:marked
  This is made possible by the `async` pipe, which we can apply in the template.
  It knows how to turn an Observable to the (latest) value it has emitted:

  `async`管道让这变为可能，我们可以把`async`管道用在模板中。
  它知道该如何把一个可观察对象(Observable)变成它所发出的(最终)值：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  That takes care of the phone list. Here's the updated unit test file for
  that component to complete the migration:

  它会负责照管电话列表。下面是升级后的单元测试文件，用来测试迁移后的组件：

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_list.component.spec.ts', null, 'test/unit/phone_list.component.spec.ts')

:marked
  Before this test will run, we'll need to augment our Karma configuration
  so that component HTML templates are loaded properly. We didn't need them
  before when we were testing the controller in isolation, but our new test
  exercises the component as a whole, which includes the template.

  在测试运行之前，我们还得增加Karma配置，以便组件的HTML模板可以正确加载。在我们以前单独测试控制器的时候，并不需要它们，
  但是这个新的测试会把该组件作为整体进行测试，其中也包括了模板。

+makeExample('upgrade-phonecat/ts/ng2_components/test/karma.conf.1.js', 'html', 'test/karma.conf.js')

:marked
  Now we can start looking at our other controller, which is the one for
  the phone details. Rename `phone_detail.controller.ts` to `phone_detail.component.ts`,
  and set the contents as follows:

  现在，我们看看另一个控制器，也就是显示电话详情的那个。把`phone_detail.controller.ts`改名为`phone_detail.component.ts`，并写入如下代码：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail_without_pipes.component.ts', null, 'app/js/phone_detail/phone_detail.component.ts')

:marked
  This is pretty similar to what we did with the phone list. The one new change
  here is the use of `@Inject` for the `$routeParams` dependency. It tells the
  Angular 2 injector what this dependency should map to. We have a dependency called
  `$routeParams` in the Angular 1 injector, where it is provided by the Angular 1 router.
  That is what we were already using when `PhoneDetails` was still an Angular 1 controller.
  The things is though, Angular 1 dependencies are not made automatically available to
  Angular 2 components, so if we were to run this now, it would not work.

  这跟我们对电话列表所做的很像。新的修改是使用`@Inject`来注入`$routeParams`依赖。它告诉Angular 2的注入器，这个依赖应该被映射到哪里。
  我们在Angular 1注入器中有一个叫做`$routeParams`的依赖，那是由Angular 1路由器提供的。
  这就是当`PhoneDetails`还是Angular 1控制器时我们已经做过的。
  问题在于，Angular 1的依赖不会自动对Angular 2的组件可用，所以如果我们现在就想运行它，它是不会工作的。

  We explicitly need to tell the `UpgradeAdapter` to upgrade `$routeParams` so that
  it is available for injection in Angular 2. We can do it in `app.module.ts`:

  我们需要明确的告诉`UpgradeAdapter`要升级`$routeParams`，以便它能用于Angular 2的依赖注入系统。我们在`app.module.ts`中做到这一点：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'upgrade-route-params', 'app/js/app.module.ts')



:marked
  We now also need to convert the template of this component into Angular 2 syntax.
  Here is the new template in its entirety:

  我们现在也要把该组件的模板转变成Angular 2的语法。
  这里是它完整的新模板：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.html', null, 'app/js/phone_detail/phone_detail.html')

:marked
  There are several notable changes here:

  这里有几个值得注意的改动：

  * We've removed the `vm.` prefix from all expressions.

  * 我们从所有表达式中移除了`vm.`前缀。

  * Just like we did in the phone list, we've replaced `ng-src` with property
    bindings for the standard `src`.

  * 正如我们在电话列表中做过的那样，我们把`ng-src`替换成了标准的`src`属性绑定。

  * We're using the property binding syntax around `ng-class`. Though Angular 2
    does have [a very similar `ngClass`](../guide/template-syntax.html#directives)
    as Angular 1 does, its value is not magically evaluated as an expression.
    In Angular 2 we always specify  in the template when an attribute's value is
    a property expression, as opposed to a literal string.

  * 我们在`ng-class`周围使用了属性绑定语法。虽然Angular 2中有一个
    和Angular 1中[非常相似的`ngClass`](../guide/template-syntax.html#directives)指令，
    但是它的值不会神奇的作为表达式进行计算。在Angular 2中，模板中的属性(Attribute)值总是被作为
    属性(Property)表达式计算，而不是作为字符串字面量。

  * We've replaced `ng-repeat`s with `*ngFor`s.

  * 我们把`ng-repeat`替换成了`*ngFor`。

  * We've replaced `ng-click` with an event binding for the standard `click`.

  * 我们把`ng-click`替换成了一个到标准`click`事件的绑定。

  * In all references to `phone`, we're using the safe navigation operator `?.` for
    safe property navigation. We need it because when the component first loads,
    we don't have `phone` yet and the expressions will refer to a non-existing
    value. Unlike in Angular 1, Angular 2 expressions do not fail silently when
    we try to refer to properties on undefined objects. We need to be explicit
    about cases where this is expected.

  * 在所有涉及`phone`的引用中，我们使用了安全导航操作符`?.`来实现安全的属性导航。我们必须这么做，
    是因为组件首次加载时我们还没有`phone`变量，这些表达式就会引用到一个不存在的值。
    和Angular 1不同，当我们尝试引用未定义对象上的属性时，Angular 2中的表达式不会默默失败。
    我们必须明确指出这种情况是我们所期望的。

:marked
  In the module file we'll now register a `pcPhoneDetail` directive instead of a
  controller. The directive is a downgraded version of the `PhoneDetail` component.

  在模块文件中，我们现在将注册一个`pcPhoneDetail`指令，而不再是控制器。该指令是`PhoneDetail`组件的一个降级版。

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.module.ts', null, 'app/js/phone_detail/phone_detail.module.ts')

:marked
  In the router configuration in `app.module.ts`, we'll switch the details route to
  instantiate a component as well:

  在`app.module.ts`中的路由器配置中，我们同样把详情路由改成实例化一个组件：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'detail-route')

:marked
  There's one additional step we need to take, which is to upgrade the
  `checkmark` filter that the template is using. We need an Angular 2
  pipe instead of an Angular 1 filter.

  我们还有一个额外的步骤要做，那就是升级模板中用到的那个`checkmark`过滤器。我们需要用一个Angular 2管道替换Angular 1过滤器。

  While there is no upgrade method in the upgrade adapter for filters, we
  can just turn the filter function into a class that fulfills
  the contract for Angular 2 Pipes. The implementation is the same as before.
  It just comes in a different kind of package. While changing it, also
  rename the file to `checkmark.pipe.ts`:

  在升级适配器中并没有哪个方法可用于升级过滤器，但我们只要把过滤器函数转变成一个能满足Angular 2管道契约的类就可以了。
  它的实现方式和前面一样。它只是到了一个不同类型的包而已。修改它的同时，也把它的文件名改为`checkmark.pipe.ts`：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/core/checkmark.pipe.ts', null, 'app/js/core/checkmark.pipe.ts')

:marked
  As we apply this change, we should also remove the registration of the filter
  from the core module file. The module's content becomes:

  当我们做这个修改时，也要同时从`core`模块文件中移除对该过滤器的注册。该模块的内容变成了：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  The unit test file for the filter also now becomes the unit test filter
  for the pipe. While we're still testing the same thing, we need to change
  how we set things up:

  此过滤器的单元测试文件也将变为对管道的单元测试。不过我们本质上仍然在测同一个东西，要改的是对测试环境进行设置的代码：

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/checkmark.pipe.spec.ts', null, 'test/unit/checkmark.pipe.spec.ts')

:marked
  In the component we should now import and declare our newly created pipe:

  在这个组件中，我们应该立即引入和声明新建的这个管道：

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.component.ts', 'top', 'app/js/phone_detail/phone_detail.component.ts')

:marked
  With the phone detail component now migrated as well, we can go and migrate
  its unit tests too.

  电话详情组件已经迁移完毕了，我们也可以继续迁移它的单元测试文件。

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_detail.component.spec.ts', null, 'test/unit/phone_detail.component.spec.ts')

:marked
  As we discussed earlier, Protractor tests should largely remain functional
  as we are making changes, since we're not really changing the user-visible
  behavior of the application. Now that we've migrated some components and
  their templates, however, there are a few changes we need to make. Apply
  the following replacements to `scenarios.js`:

  就像我们以前讨论过的，在我们修改的时候，Protractor测试会大量保持原有功能，因为我们没有真的修改此程序中用户可见的行为。
  现在，我们已经迁移了一些组件和它们的模板，然而，我们还是要做一些修改。
  在`scenarios.js`中做下列替换：

table
  tr
    th
      p Previous code
      p 原有代码
    th
      p New code
      p 新代码
    th
      p Notes
      p 说明
  tr
    td
      :marked
        `by.repeater('phone in vm.phones').column('phone.name')`
    td
      :marked
        `by.css('.phones .name')`
    td
      :marked
        The repeater matcher relies on Angular 1 `ng-repeat`

        repeater匹配器依赖于Angular 1中的`ng-repeat`
  tr
    td
      :marked
        `by.repeater('phone in vm.phones')`
    td
      :marked
        `by.css('.phones li')`
    td
      :marked
        The repeater matcher relies on Angular 1 `ng-repeat`

        repeater匹配器依赖于Angular 1中的`ng-repeat`
  tr
    td
      :marked
        `by.model('vm.query')`
    td
      :marked
        `by.css('input')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`

        model匹配器依赖于Angular 1中的`ng-model`
  tr
    td
      :marked
        `by.model('vm.orderProp')`
    td
      :marked
        `by.css('select')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`

        model匹配器依赖于Angular 1中的`ng-model`
  tr
    td
      :marked
        `by.binding('vm.phone.name')`
    td
      :marked
        `by.css('h1')`
    td
      :marked
        The binding matcher relies on Angular 1 data binding

        binding匹配器依赖于Angular 1的数据绑定
  tr
    td
      :marked
        `li:nth-child(1)` and `li:nth-child(3)`
    td
      :marked
        `li:nth-of-type(1)` and `li:nth-of-type(3)`
    td
      :marked
        Angular 2 may inject empty `&lt;script>` tags to the page for its internal purposes so we should not rely on the number of siblings being predictable.

        Angular 2可能在页面中注入一个空白的`&lt;script>`标签供内部使用，所以我们不能假设兄弟节点的数量是可预计的。

:marked
  ## Switching To The Angular 2 Router And Bootstrap
  ## 切换到Angular 2路由器和引导程序

  At this point we've replaced all our Angular 1 application components with
  their Angular 2 counterparts. The application is still bootstrapped as a hybrid,
  but there isn't really any need for that anymore, and we can begin to
  pull out the last remnants of Angular 1.

  此时，我们已经把所有的Angular 1程序代码替换成了它们在Angular 2中的对应物。该应用仍然是作为混合应用进行引导的，
  但实际上我们已经不需要它了，我们这就彻底移除Angular 1的残余势力。

  There are just two more things to do: We need to switch the router to
  the Angular 2 one, and then bootstrap the app as a pure Angular 2 app.

  接下来只有两件事要做：我们要把路由器切换成Angular 2的，然后把该程序作为纯粹的Angular 2应用进行引导。

  Let's do the routing part first. Angular 2 comes with a [shiny new router](router.html)
  that we can use for this.

  我们先来处理路由部分。Angular 2自带了一个[全新的路由](router.html)可以用来做这件事。

  Angular 2 applications all have a *root component*, which, among other
  things, is where we should plug in the router. We don't yet have such a root
  component, because our app is still managed as an Angular 1 app.
  Let's change this now and add an `AppComponent` class into a new file
  `app.component.ts`:

  Angular 2应用全都有一个*根组件*，除具有其它功能外，它还是我们插入路由器的地方。
  我们现在还不需要根组件，因为我们的程序还是被当做Angular 1的应用进行管理的。
  我们这就改变这一点，并且把`AppComponent`类填加到一个叫`app.component.ts`的新文件中：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/app.component.ts', null, 'app/js/app.component.ts')

:marked
  This is a component that plugs in to an `<pc-app>` element on the page,
  and has a simple template that only includes the router outlet component
  of the Angular router. This means that the component just renders the contents
  of the current route and nothing else. The `@RouteConfig` decorator defines
  the Angular 2 counterparts of our two routes. They refer directly to the
  two components.

  这个组件将被插入到页面中一个`<pc-app>`元素中，并且其模板是只包含一个“路由器出口(router outlet)”组件。
  这意味着该组件将只会渲染当前路由的内容，没别的。`@RouteConfig`装饰器定义了两个原有路由在Angular 2中的对应物。
  它们直接引用了这两个组件。

  We should put this `<pc-app>` element in the HTML so that the root component
  has something to attach to. It replaces the old Angular 1 `ng-view` directive:

  我们还要把这个`<pc-app>`元素放进HTML中，以便这个根组件可以附加上去。它代替了Angular 1中原来的`ng-view`指令：

+makeExample('upgrade-phonecat/ts/ng2_final/app/index.html', 'body', 'app/index.html')

:marked
  In the `PhoneDetail` component we now need to change how the phone id parameter
  is received. There will be no more `$routeParams` injection available, because
  that comes from the Angular 1 router. Instead, what we have is a `RouteParams`
  object provided by the Angular 2 router. We use it to obtain the `phoneId` from
  the params:

  在`PhoneDetail`组件中，我们现在需要修改电话id参数的接收方式。再也没有`$routeParams`可被注入了，
  因为它来自Angular 1路由器。Angular 2路由器提供了一个`RouteParams`对象。我们使用它来从参数中获得`phoneId`。

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_detail/phone_detail.component.ts', null, 'app/js/phone_detail/phone_detail.component.ts')

:marked
  We should also make the corresponding change in the unit test. We provide
  an instance of the `RouteParams` class instead of the `$routeParams` object:

  我们还要在单元测试中做相应的修改。我们提供了一个`RouteParams`类的实例，以代替原来的`$routeParams`对的：

+makeExample('upgrade-phonecat/ts/ng2_final/test/unit/phone_detail.component.spec.ts', 'routeparams', 'test/unit/phone_detail.component.spec.ts')

:marked
  With that, we're ready to switch the bootstrap method of the application from that
  of the `UpgradeAdapter` to the main Angular 2 `bootstrap`. Let's import it together
  with the router and the new app component in `app.module.ts`

  使用它，我们就可以把来自`UpgradeAdapter`中的`bootstrap`方法切换到Angular 2自己的`bootstrap`了。
  通过路由器和`app.module.ts`中新的应用组件，我们把它们导入到一起：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', 'importbootstrap')

:marked
  We'll now use the regular Angular 2 `bootstrap` function to bootstrap the app
  instead of using `UpgradeAdapter`. The first argument to `bootstrap` is the
  application's root component `AppComponent`, and the second
  is an array of the Angular 2 providers that we want to make available for
  injection. In that array we include all the things we have been registering
  with  `upgradeAdapter.addProvider` until now, as well as the providers and
  directives of the router:

  我们现在就改用Angular 2中标准的`bootstrap`函数来引导本应用，而不再用`UpgradeAdapter`。
  `bootstrap`的第一个参数是应用程序的根组件`AppComponent`，第二个参数是一个由Angular 2中希望被注入的
  供应商构成的数组。这个数组中，我们包含了至今用`upgradeAdapter.addProvider`注册过的所有东西，
  比如各种供应商以及路由器中的指令：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', 'bootstrap')

:marked
  We are now running a pure Angular 2 application!

  我们已经在运行一个纯正的Angular 2应用了！

  But there's actually one more cool thing we can do with the new router.
  We no longer have to hardcode the links to phone details from the phone
  list, because the Angular 2 router is able to generate them for us with
  its `routerLink` directive. We just need to refer to the route names we
  used in the `@RouteConfig`:

  但是，基于新的路由，我们还能做一些更酷的事情。
  在电话列表页中，我们不需要再把到电话详情页的链接硬编码进去，因为Angular 2可以通过`routerLink`指令帮我们生成它。
  我们只需要引用`@RouteConfig`中用过的路由名称：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_list/phone_list.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  For this to work the directive just needs to be declared in the component:

  要让该指令能够工作，我们只需要把它在组件中声明一下：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_list/phone_list.component.ts', 'top')

:marked
  Also, the unit tests for `PhoneList` now need to set up some router providers
  so that the `RouterLink` directive can be injected in the tests:

  同样的，`PhoneList`的单元测试现在也需要设置一些路由供应商，以便`RouterLink`指令可以被注入到这些测试中：

+makeExample('upgrade-phonecat/ts/ng2_final/test/unit/phone_list.component.spec.ts', null)

:marked
  To bring our Protractor test suite up to speed with the latest changes,
  there are a few remaining things we need to do. Firstly, now that we're
  no longer running Angular 1 at all, we should let Protractor know it
  should not be looking for one but instead find *Angular 2 apps* from
  the page. Add the following configuration option to `protractor-conf.js`:

  要让Protractor测试套件能跟上最新的更改，我们还有一些事情要做。首先，我们完全不用运行Angular 1了，
  我们得让Protractor知道它现在不用再找Angular 1了，而是从页面中找*Angular 2应用*。
  把下列配置项添加到`protractor-conf.js`中：

+makeExample('upgrade-phonecat/ts/ng2_final/test/protractor-conf.js', 'ng2')

:marked
  Also, there are a couple of Protractor API calls in our test code that
  are using the Angular 1 `$location` service under the hood. As that
  service is no longer there, we need to replace those calls with ones
  that use WebDriver's generic URL APIs instead. The first of these is
  the redirection spec:

  同样，我们的测试代码中有两个Protractor API调用内部使用了`$location`。该服务没有了，
  我们就得把这些调用用一个WebDriver的通用URL API代替。第一个API是“重定向(redirect)”规约：

+makeExample('upgrade-phonecat/ts/ng2_final/test/e2e/scenarios.js', 'redirect')

:marked
  And the second is the phone links spec:

  第二个是“电话链接(phone links)”规约：

+makeExample('upgrade-phonecat/ts/ng2_final/test/e2e/scenarios.js', 'links')

:marked
  Now our E2E test suite is passing too, and we're ready to remove
  Angular 1 from the project!

  现在，我们的E2E测试套件也全都通过了，准备从项目中彻底移除Angular 1吧！

:marked
  ## Saying Goodbye to Angular 1
  ## 再见，Angular

  It is time to take off the training wheels and let our application begin
  its new life as a pure, shiny Angular 2 app. The remaining tasks all have to
  do with removing code - which of course is every programmer's favorite task!

  是时候把辅助训练的轮子摘下来了！让我们的应用作为一个纯粹、势均力敌的Angular 2程序开始它的新生命吧。
  剩下的所有任务就是移除代码 —— 这当然是每个程序员最喜欢的任务！

  First, rename `app.module.ts` to `main.ts`. It will no longer be setting up
  an Angular 1 module, so it doesn't really make sense to call it a module.
  Then remove all references to the `UpgradeAdapter` from `main.ts`. Also remove
  the Angular 1 bootstrap code and the imports of the `core`, `phoneList`, and
  `phoneDetail` modules. Instead import the `PhoneList` and `PhoneDetail`
  components directly - they are needed in the route configuration.

  首先，把`app.module.ts`改名为`main.ts`。它不会再设置一个Angular 1模块，把它叫做模块(module)也没有实际意义了。
  然后从`main.ts`中移除所有到`UpgradeAdapter`的引用。同样移除Angular 1的引导代码，以及到`core`、`phoneList`
  和`phoneDetail`模块的引用。改为直接导入`PhoneList`和`PhoneDetail`组件 —— 它们在路由配置中需要。

  When you're done, this is what `main.ts` should look like:

  都完成了之后，`main.ts`看起来应该像这样：

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', null, 'app/js/main.ts')

:marked
  You may also completely remove the following files. They are Angular 1
  module configuration files and type definition files, and not required
  in Angular 2:

  我们还完全移除了下列文件。他们是Angular 1的模块配置文件和类型定义文件，在Angular 2中不需要了：

  * `app/js/core/core.module.ts`
  * `app/js/core/upgrade_adapter.ts`
  * `app/js/phone_detail/phone_detail.module.ts`
  * `app/js/phone_list/phone_list.module.ts`

  The external typings for Angular 1 may be uninstalled as well. The only ones
  we still need are for Jasmine.

  Angular 1的外部类型定义文件还需要被反安装。我们现在只需要Jasmine的那些。

code-example(format="").
  npm run typings uninstall jquery -- --save --global
  npm run typings uninstall angular -- --save --global
  npm run typings uninstall angular-route -- --save --global
  npm run typings uninstall angular-resource -- --save --global
  npm run typings uninstall angular-mocks -- --save --global

:marked
  Finally, from `index.html` and `karma.conf.js`, remove all references to
  Angular 1 scripts as well as jQuery. Instead of importing `js/app.module`
  with SystemJS, import `js/main`. When you're done, this is what `index.html`
  should look like:

  最后，从`index.html`和`karma.conf.js`中，移除所有到Angular 1脚本的引用，比如jQuery。
  改为通过SystemJS导入`js/app.module`和`js.main`。当这些全部做完时，`index.html`看起来应该是这样的：

+makeExample('upgrade-phonecat/ts/ng2_final/app/index.html', null, 'app/index.html')

:marked
  And this is what `karma.conf.js` should look like:

  `karma.conf.js`看起来应该是这样的：

+makeExample('upgrade-phonecat/ts/ng2_final/test/karma.conf.1.js', null, 'test/karma.conf.js')

:marked
  That is the last we'll see of Angular 1! It has served us well but now
  it's time to say goodbye.

  这是我们最后一次看到Angular 1了！它帮过我们很多忙，不过，是时候说再见了！