22ndtech-lib 中文文档教程

Question

Warning

该库处于早期 alpha 阶段，尚未达到足够的成熟度以保证接口的向后兼容性。

22ndtech Library

[![Build Status][travis-badge]][travis-badge-url]

这是一个简单的库 22ndtech，实现了 角度包格式 v4.0。

目前仅支持无作用域的主要入口点库。

特点：

• a simple example library
• unit tests for the library
• a demo application that consumes the library in JIT mode and runs in watch mode
• an integration app that consumes the library in JIT and AOT mode and runs e2e tests

常见任务作为 npm 脚本存在：

• npm start to run a live-reload server with the demo app
• npm run test to test in watch mode, or npm run test:once to only run once
• npm run build to build the library
• npm run lint to lint
• npm run clean to clean
• npm run integration to run the integration e2e tests
• npm install ./relative/path/to/lib after npm run build to test locally in another app

如果您需要调试集成应用程序，请检查 ./integration/README.md。

What's in the 22ndtech Library?

22ndtech 库 包含与Quickstart seed 类似的结构。 它被修改为构建和测试库而不是应用程序。

因此，项目中有许多不同的文件。 关注 /src 文件夹中的以下 TypeScript (.ts) 文件。

src/
├── demo/
|  └── app/
|     ├── app.component.ts
|     └── app.module.ts
└── lib/
   ├── index.ts
   └── src/
      ├── component/
      |  └── lib.component.ts
      ├── service/
      |  └── lib.service.ts
      └── module.ts

每个文件都有不同的用途，并随着应用程序的增长而独立发展。

src/ 之外的文件涉及构建、部署和测试您的应用程序。 它们包括配置文件和外部依赖项。

src/lib/ 中的文件“属于”您的库，而 src/demo/ 包含一个演示应用程序 加载您的图书馆。

库不会自行运行，因此在开发时拥有此“演示”应用程序非常有用 了解您的图书馆对消费者的看法。

当您运行 npm start 时，将提供演示应用程序。

以下都在 src/

File	Purpose
demo/app/app.component.ts	A demo component that renders the library component and a value from the library service.
demo/app/app.module.ts	A demo NgModule that imports the Library LibModule.
lib/src/component/app.component.ts	A sample library component that renders an h2 tag.
lib/src/service/lib.service.ts	A sample library service that exports a value.
lib/src/module.ts	The library's main NgModule, LibModule.
lib/index.ts	The public API of your library, where you choose what to export to consumers.

The build step

中，你可以通过运行 npm run build 来构建库。 这将生成一个包含上述所有入口点的 dist/ 目录。

创建构建的所有逻辑都可以在 ./build.js 中找到。 它由大约 5 个步骤组成：

• Compile with the AOT Compiler (AOT compiler or ngc) for ES5 and ES2015.
• Inline html and css inside the generated JavaScript files.
• Copy typings, metatada, html and css.
• Create each bundle using Rollup.
• Copy LICENSE, package.json and README.md files

Testing libraries

虽然测试始终很重要，但它在图书馆中尤其重要，因为消费者 应用程序可能会由于库中的错误而中断。

但库被另一个应用程序使用的事实也使得它难以测试。

要正确测试库，您需要进行集成测试。 集成测试之于库就像端到端测试之于应用程序。 它测试应用程序如何安装和使用您的库。

22ndtech Library 包含一个名为 integration 的目录，其中包含一个独立的 在 AOT 和 JIT 模式下使用您构建的库的应用程序，通过端到端测试来验证 有用。

要运行集成测试，请执行 npm run integration，它会执行以下操作：

• Build your library.
• Enter the integration app's directory.
• Install dependencies.
• Build the app in AOT mode.
• Test the app in AOT mode.
• Test the app in JIT mode.

运行集成测试让您更加确信您的库已正确构建。

除了集成测试，您还可以通过 npm run test 以监视模式运行单元测试， 或通过 npm run test:once 单次运行。

您还可以通过将其安装在您拥有的另一个本地存储库中来测试您的库。 为此，首先通过 npm run build 构建您的库。 然后使用 dist 文件夹的相对路径从您的其他存储库安装它： npm install relative/path/to/library/dist。

Publishing your library

您还需要重命名项目所在的文件夹。

更改包名称后，您可以将其发布到 NPM（阅读 此链接了解详情）。

而不是遵循之前文档中的更新包，我们在这里使用 标准版本。 阅读他们的文档以了解如何使用它。

首先，您需要创建一个 NPM 帐户并登录到您的本地计算机。 然后你可以通过运行 npm publish dist/ 来发布你的包。
由于您的包构建在 dist/ 文件夹中，因此您应该发布该文件夹。

### Be a good library maintainer Now that you've published a library, you need to maintain it as well. Below are some of the most important points: - Document your library. - Keep an eye on the issue tracker. - [Manage your dependencies properly](#appendix-dependency-management) - Follow [Semantic Versioning](http://semver.org/) - Setup a Continuous Integration solution to test your library (included is a `.travis.yml` file for [Travis CI](https://docs.travis-ci.com/user/getting-started/))! - Choose an [appropriate license](https://choosealicense.com/).

Appendix: Supporting AOT

AOT 在优化 Angular 应用程序方面发挥着重要作用。 因此，第三方库以与 AOT 兼容的格式发布非常重要 汇编。 否则，将无法将库包含在 AOT 编译的应用程序中。

只有使用 TypeScript 编写的代码才能进行 AOT 编译。

在发布库之前，必须先使用 AOT 编译器 (ngc) 进行编译。 ngc 通过添加扩展来扩展 tsc 编译器以支持 AOT 编译 常规的 TypeScript 编译。

AOT 编译输出三个文件，必须包含这些文件才能与 AOT 兼容。

Transpiled JavaScript

像往常一样，原始 TypeScript 被转译为常规 JavaScript。

类型文件

JavaScript 无法表示类型。 为了保留原始类型，ngc 将生成.d.ts 类型文件。

元数据 JSON 文件

ngc 为每个 Component 和 NgModule 输出一个 metadata.json 文件。 这些元数据文件代表了原始 NgModule 和 Component 中的信息 装饰器。

元数据可能引用外部模板或 css 文件。 这些外部文件必须包含在库中。

NgFactories

ngc 生成一系列带有 .ngfactory 后缀的文件。 这些文件代表 AOT 编译源，但不应包含在已发布的库中。

相反，消费应用程序中的 ngc 编译器将生成基于 .ngfactory 的文件 在库附带的 JavaScript、类型和元数据上。

Why not publish TypeScript?

为什么不发布 TypeScript 源代码呢？ 毕竟，当库是时，库将成为另一个 TypeScript 编译步骤的一部分 由消费应用程序导入。

通常不鼓励将 TypeScript 与第三方库一起发布。 这将要求消费者复制库的完整构建环境。 不仅是类型，还可能是 ngc 的特定版本。

发布带有类型和元数据的纯 JavaScript 允许消费应用程序 对库的构建环境保持不可知。

Appendix: Supporting JIT

AOT 编译代码是生产构建的首选格式，但由于编译时间长 有时在开发过程中使用 AOT 可能不切实际。

为了创建更灵活的开发人员体验，应该使用与 JIT 兼容的库构建 也发表了。 JIT bundle 的格式是umd，代表Universal Module Definition。 将包作为 umd 发送可确保与最常见的模块加载格式兼容。

umd 包将作为包含 ES5 JavaScript 和内联版本的单个文件发布 任何外部模板或 CSS。

Appendix: Dependency Management

作为库维护者，正确管理 package.json 中的依赖项非常重要。

有三种依赖： dependencies、devDependencies 和 peerDependencies。

• dependencies: here go all the other libraries yours depends on when being used. A good way to figure out these is to go through your library source code (in src/lib only) and list all the libraries there.
• devDependencies: libraries that you need while developing, testing and building your library go here. When a user installs your library, these won't be installed. Users don't need to develop, build or test your library, they just need to run it.
• peerDependencies: these are similar to dependencies since your library expects them to be there at runtime. The difference is that you don't want to install a new version of these, but instead use the one already available.

对等依赖的一个很好的例子是 @angular/core 和所有其他主要的 Angular 库。 如果您在 dependencies 中列出这些，一个新的 - 具有不同的版本！ - 可以安装 供您的图书馆使用。 这不是你想要的。 您希望您的库使用完全相同 @angular/core 该应用程序正在使用。

你通常会使用在 devDependencies 和 <代码>对等依赖。 这是正常的，也是意料之中的，因为当你开发你的库时，还需要一份 他们安装了。

另一件要记住的事情是防止你的依赖项意外地改变太多。 不同版本的库可以有不同的特性，如果你不小心 对允许的版本宽容，您的库可能会因为依赖项更改而停止工作。

您可以使用 ranges 选择您允许的版本。

一个好的经验法则是让所有 dependencies 都用波浪号 ~(~1.2.3) 指定， 而你的 peerDependencies 有一个范围 ("@angular/core": ">=4.0.0 <5.0.0 || >=4.0.0-beta <5.0. 0")。

您添加到 package.json 的任何额外依赖项或对等依赖项也应添加 到 ./build.js 中 rollupBaseConfig 变量中的 globals 和 external 数组。

这确保您的库不会在其中打包额外的库，而是使用那些 在消费应用程序中可用。