翻译:Angular2 Dart快速上手指南


#1

转载我的博客文章:Angular2 Dart快速上手指南,水平有限,仅供参考,更新更全的内容请查看原文:https://angular.io/docs/dart/latest/quickstart.html


本篇快速上手指南的目标是,用Dart创建一个超级简单的Angular2应用,为后续教程提供一个基础的开发环境,也为开发者提供一个可用于实际应用开发的基础项目。

尝试一下!

点击在线示例(查看源码),将加载示例应用,并展示以下信息:

构建这个应用!

  • 先决条件:安装Dart SDK
  • 步骤1:创建项目目录,定义项目依赖及部分特殊的项目设置
  • 步骤2:创建应用的Angular根组件(root component)
  • 步骤3:添加 main.dart, 为Angular指定根组件
  • 步骤4:添加运行本应用的web页面 index.html
  • 步骤5:构建并运行应用
  • 修改应用
  • 总结

先决条件

请配置好Dart SDK以及任意你喜欢的开发工具,Dart SDK自带了包管理器 pub。如果你没有称手的编辑器,可以尝试一下自带Dart插件的WebStorm。当然,你也可以去Dart官网工具页面下载其他IDE、编辑器的Dart插件。

译注:Dart官方推荐的IDE是jetbrains家的WebStorm,笔者使用的是Atom与dart项目组编写的dartlang插件。

步骤1: 创建并配置项目

本步中,我们将:

  • (a) 创建项目目录
  • (b) 添加 pubspec.yaml
  • © 获取依赖

(a) 创建项目目录

> mkdir angular2-quickstart
> cd angular2-quickstart

(b) 添加 pubspec.yaml

在刚刚创建的文件夹中,创建一个名称为 pubspec.yaml 的文件,并填入下面的代码。这个文件指定 angular2 跟 browser 作为项目依赖,并配置了名称为 angular2 的 transformer。此外,还配置了另一个名为dart_to_js_script_rewriter的 transformer,当然,你可以加入其他任意开发所需的package跟transformer。因为Angular2的API还在变化,所以指定了它的版本:2.0.0-beta.17(译注:指定版本可以避免在更新依赖时发生版本冲突)。

name: angular2_getting_started
description: QuickStart
version: 0.0.1
environment:
  sdk: '>=1.13.0 <2.0.0'
dependencies:
  angular2: 2.0.0-beta.17
  browser: ^0.10.0
  dart_to_js_script_rewriter: ^1.0.1
transformers:
- angular2:
    entry_points: web/main.dart
- dart_to_js_script_rewriter

© 获取依赖

在项目目录下,执行 pub get 安装 angular2 与 browser(包括它们自身的依赖)。

> pub get
Resolving dependencies...

我们已经准备好了,开始写代码吧。

步骤2: 第一个Angular组件

我们来创建应用的目录并在其中添加一个超级简单的Angular组件。

在项目根目录下新建一个名为 lib 的文件夹。

> mkdir lib

创建组件 lib/app_component.dart,并写入以下代码:

import 'package:angular2/core.dart';

@Component(
    selector: 'my-app',
    template: '<h1>My First Angular 2 App</h1>')
class AppComponent {}

AppComponent是应用的根组件

每个Angular应用至少有一个根组件(root component),按照约定通常命名为 AppComponent。组件是Angular应用的最基本的组成单元。一个组件通过与它关联的模板来控制屏幕的某块区域(视图)。

虽然本篇指南只介绍了一个超级简单的组件,但它却包含了每个组件必备的关键要素:

  • 一个或多个import语句 - 导入我们需要的库。

  • 一个@Component注解 - 告诉Angular使用哪一个模板以及如何创建组件

  • 一个component类 - 通过模板来构建组件的外观与行为

Import

Angular应用都是模块化的,它们由多个职责明确的文件组成。Angular框架本身也是模块化的,它底层有非常多的模块,各个模块组合成不同的功能块,然后再被我们拿来编写应用。

在需要调用到某个模块或库的内容时,我们就要导入它。在这里,我们导入了Angular2的core模块,所以我们的组件才能够访问@Compenet注解。

    import 'package:angular2/core.dart';

@Compenet 注解

@Compenet 是一个注解,它让我们能够给组件类添加元数据(metadata),而元数据会告诉Angular怎样去创建并使用我们的组件。

    @Component(
    selector: 'my-app',
    template: '<h1>My First Angular 2 App</h1>')

@Component 的构造函数有两个命名参数:selectortemplate

selector 参数是一个简单的CSS选择器,它指定了一个代表组件的自定义HTML元素。

这个组件的html标签是 my-app ,当Angular遇到这个元素时,就会创建并展示一个AppComponent类的实例。

template 参数指定组件的模板,模板内容使用一种增强版的HTML,Angular依照它去渲染组件的视图。

我们的例子中,模板只是一行简单的HTML,用来展示一句文字:“My First Angular 2 App”。

在更加复杂的模板中,可能会包含组件属性的数据绑定,也可能会放置其他带模板的组件,即引用其他组件,这种方式使Angular应用成为一个由组件构成的树。

组件类

在文件尾部,是一个名称为AppComponent,没有做任何事的类。

class AppComponent {}

这个AppComponent是空的,是因为在本篇指南中,我们不需要它做任何事。在构建真正的应用时,我们可以扩展这个类,给它加上属性与逻辑实现代码。

步骤3: 添加main.dart

现在我们需要让Angular加载我们的根组件,创建如下文件:

  • 一个名为 web 的文件夹
  • 一个名为 web/main.dart 的文件,它的内容如下:
import 'package:angular2/platform/browser.dart';
import 'package:angular2_getting_started/app_component.dart';

void main() {
  bootstrap(AppComponent);
}

在这里,我们引入了两个dart文件,其中包含了启动应用所需要的:

  1. Angular browser模块的 bootstrap 函数
  2. 应用的根组件:AppComponent

我们把根组件AppComponent传递给bootstrap函数并运行它,即启动应用。

应用启动随平台而变

需要注意的是:我们导入的bootstrap函数是来自 package:angular2/platform/browser.dart,而不是 package:angular2/core.dart,因为Angular有多种方式来启动应用,所以bootstrap函数没有放置在core库中。当然,大部分Angular应用都运行在浏览器中,所以它们都是调用来自browser.dart的bootstrap函数。

要注意的是,在除浏览器以外的环境下加载组件,是完全可行的。我们可能会通过 Apache CordovaNative Script,在移动设备上运行组件。为了提升应用加载速度或是提升SEO,也可能会把应用首页放到服务端去渲染。这些不同的平台就要求有不同的bootstrap函数,而它们必然是分布在不同的库中。

为什么把组件跟 main.dart 分离

本篇文章只为快速上手,main.dart跟AppComponent都非常简单,把它们合并到一个文件是完全可行的。

我们之所以把它们分离,是想向开发者展示一种合理的项目结构。应用启动跟视图渲染是完全不同的概念,把它们混在一起会对后续开发带来不便。我们可能会针对不同的平台,使用不同的加载方式来运行AppComponent,混合在一起的代码会对此造成麻烦,而且对组件的测试也会造成影响。虽然分离操作会让我们有额外的小付出,但确实能为以后的开发工作打好基础。

步骤4: 添加index.html

在web文件夹下,创建一个index.html文件,并填入如下内容:

<!DOCTYPE html>
<html>
  <head>
    <title>Getting Started</title>
    <link rel="stylesheet" href="styles.css">
    <script defer src="main.dart" type="application/dart"></script>
    <script defer src="packages/browser/dart.js"></script>
  </head>
  <body>
    <my-app>Loading...</my-app>
  </body>
</html>

这个index.html文件定义了应用所在的web页面。

Angular在调用main.dart的bootstrap函数时,会读取AppComponent的元数据,在知道组件的选择器是my-app后,就会定位模板中对应的标签,并把应用的视图渲染到标签内。

添加一些样式

index.html假定我们拥有一个名为styles.css的样式文件,样式虽然不是最重要的,但它们确实有锦上添花的作用。

在web文件夹下创建一个styles.css文件,并填入如下所示的最小化样式代码。如果你想查看完整的样式代码,请查看styles.css。(译注:在本篇快速指南中,使用以下基本样式就可以了,完整的样式代码是为配合其他文档中的示例)

h1 {
  color: #369;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 250%;
}
body {
  margin: 2em;
}

/*
* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
* for the full set of master styles used by the documentation samples
*/

步骤5:构建并运行应用

有多种方式来运行应用,其中之一是在本地运行一个http服务器,然后在Dartium中访问应用。我们可以使用任意的web服务器,比如WebStorm内置的服务器或者Python的SimpleHttpServer。

另外一种方式是通过执行 pub serve 来构建并启动应用,然后在任意现代浏览器中访问 http://localhost:8080 来访问应用。Pub serve 指令会实时的将Dart编译为JavaScript,当然,这会对页面的初次访问造成一定的延迟。Pub serve 指令是会开启 监控模式 的,也就是说,你一修改文件,它就会自动重新编译,无需重启服务。

一旦应用运行起来,你就会浏览器窗口中看到:

干的漂亮!

如果你没有看到类似的运行结果,请确保完整的输入了所有代码,使用了正确的项目文件结构(请参考下面的 总结 部分),以及执行过 pub get

构建应用(生成JavaScript)

在部署应用之前,我们还需要生成JavaScript文件,pub build 指令使这项工作得以简单化。

> pub build
Loading source assets...

生成的JavaScript以及其他支持文件都会出现在 build 文件夹下。

使用Angular transformer

在为Angular应用生成JavaScript时,请确保使用Angular transformer。它会分析Dart代码,将其中使用了反射的代码转换为静态代码,使Dart的构建工具输出更快速、体积更小的JavaScript。如下所示,pubspec.yaml 中的高亮部分是对Angular transformer进行配置:(译注:这里高亮的是第10、11、16行,笔者暂时没有找到使codeblock内容高亮的方法)

name: angular2_getting_started
description: QuickStart
version: 0.0.1
environment:
  sdk: '>=1.13.0 <2.0.0'
dependencies:
  angular2: 2.0.0-beta.17
  browser: ^0.10.0
  dart_to_js_script_rewriter: ^1.0.1
transformers:
- angular2:
    platform_directives:
    - 'package:angular2/common.dart#COMMON_DIRECTIVES'
    platform_pipes:
    - 'package:angular2/common.dart#COMMON_PIPES'
    entry_points: web/main.dart
- dart_to_js_script_rewriter

entry_points 指定了调用 main() 函数的Dart文件,如果需要查看更多相关信息,请查看Angular transformer维基页面

性能,transformer,以及Angular 2库

当一个应用引入 bootstrap.dart时,就同时引入了 dart:mirrors,它是一个反射库,它会影响生成的JavaScript的性能。但是别担心,Angular transformer会对你的入口文件(pubspec.yaml 中的 entry_points)执行转换操作,在转换后,它们就不会引用 dart:mirrors 了。

使用 dart_to_js_script_rewriter

为了改善应用的性能,就要让HTML文件指向最终生成的JavaScript,而这可以由 dart_to_js_script_rewriter 来完成。要使用它,必须将它添加到你的 pubsepc.yaml 中,并且 dependencies 跟 transformers 都需要设置:(译注:这里高亮的是第6、9、10、17行)

name: angular2_getting_started
description: QuickStart
version: 0.0.1
environment:
  sdk: '>=1.13.0 <2.0.0'
dependencies:
  angular2: 2.0.0-beta.17
  browser: ^0.10.0
  dart_to_js_script_rewriter: ^1.0.1
transformers:
- angular2:
    platform_directives:
    - 'package:angular2/common.dart#COMMON_DIRECTIVES'
    platform_pipes:
    - 'package:angular2/common.dart#COMMON_PIPES'
    entry_points: web/main.dart
- dart_to_js_script_rewriter

注意:dart_to_js_script_rewriter必须配置在angular2之后,更多关于它的文档,请查看dart_to_js_script_rewriter

做点修改

你可以尝试修改component注解的template参数,比如把它改成"My SECOND Angular 2 app",然后重新刷新浏览器,就可以看到新的内容了。

注意:在结束应用开发时,请记得中止 pub serve

总结

我们的项目结构应该类似于下图:

注意:以上图片没有列出pub等产生的文件跟目录,比如 pubspec.lock,它列出并锁定了我们应用所有依赖的版本以及其他相关信息。在执行 pub build 时,一个build文件夹也会被创建,里面包含了编译生成的JavaScript。而Pub、IDE及其他工具,都可能会在项目目录下创建各种dot文件与文件夹。


#3

2016.06.17 - 跟随原文,大幅更新