22ndtech-angular-lib 中文文档教程
Warning
该库正在积极开发中,尚未达到最终形式。
它可能与当前版本的 Angular 不完全兼容。
22ndtech Angular Library
这是一个简单的库,用于使用 Angular 的 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 appnpm run test
to test in watch mode, ornpm run test:once
to only run oncenpm run build
to build the librarynpm run lint
to lintnpm run clean
to cleannpm run integration
to run the integration e2e testsnpm install ./relative/path/to/lib
afternpm run build
to test locally in another app
如果您需要调试集成应用程序,请检查 ./integration/README.md
。
The 22ndtech Angular Library
此示例存储库具有所描述的包格式的实现,但绝不是 发布库的唯一方法。
构建必要的包格式的任何设置对消费者来说同样有效。 我们鼓励您根据需要自定义此过程。
在开发自己的设置时,请记住即使 AOT 首选,应该支持即时编译。
确保至少安装了 Node 6.9 和 NPM 3.0。 然后……
- Create a project folder (you can call it
22ndtech-angular-lib
and rename it later). - Clone or download the 22ndtech Angular Library into your project folder.
- Install npm packages.
- Run
npm start
to launch the sample application.
Clone
使用这些终端命令执行clone-to-launch 步骤。
git clone https://github.com/angular/22ndtech-angular-lib.git 22ndtech-angular-lib
cd angular-22ndtech-angular-lib
npm install
npm start
Download
下载 22ndtech Angular 库种子 并将其解压缩到您的项目文件夹中。 然后使用这些终端命令执行剩余的步骤。
cd 22ndtech-angular-lib
npm install
npm start
Initialize your repository
如果你从 github 克隆包,它有一个 .git
文件夹,官方存储库的历史存在于其中。
虽然你不想要那个 git 历史 - 你会想要自己的。
删除此文件夹并将此文件夹初始化为新存储库:
rm -rf .git # Linux or OS/X (bash)
rd .git /S/Q # Windows
git init
警告:仅在开始时执行此操作以避免意外删除您自己的 git 设置!
What's in the 22ndtech Angular Library?
22ndtech Angular 库 包含与快速入门种子 类似的结构。 它被修改为构建和测试库而不是应用程序。
因此,项目中有许多不同的文件。 关注 /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
andREADME.md
files
Testing libraries
虽然测试始终很重要,但它在图书馆中尤其重要,因为消费者 应用程序可能会由于库中的错误而中断。
但库被另一个应用程序使用的事实也使得它难以测试。
要正确测试库,您需要进行集成测试。 集成测试之于库就像端到端测试之于应用程序。 它测试应用程序如何安装和使用您的库。
22ndtech Angular 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 上的每个包都有一个唯一的名称,你的也应该如此。 如果您还没有,现在是时候更改您的图书馆的名称了。
使用您的编辑器在项目中搜索 angular-22ndtech-angular-lib
的所有实例并进行更改 到你想要的名字(也是 dash-case
格式)。 至少在这些文件中提到了库名称:
integration/src/app/app.component.ts
integration/src/app/app.module.ts
integration/src/systemjs.config.js
integrations/package.json
src/demo/app/app.component.ts
src/demo/app/app.module.ts
src/demo/systemjs.config.js
src/demo/tsconfig.json
src/lib/tsconfig.json
src/lib/tsconfig.es5.json
bs-config.json
package.json
README.md
您还需要重命名项目所在的文件夹。
更改包名称后,您可以将其发布到 NPM(阅读 此链接了解详情)。
而不是遵循之前文档中的更新包
,我们在这里使用 标准版本。 阅读他们的文档以了解如何使用它。
首先,您需要创建一个 NPM 帐户并登录到您的本地计算机。 然后你可以通过运行 npm publish dist/
来发布你的包。
由于您的包构建在 dist/
文件夹中,因此您应该发布该文件夹。
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 (insrc/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 todependencies
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
数组。
这确保您的库不会在其中打包额外的库,而是使用那些 在消费应用程序中可用。
Warning
This library is under active development and hasn't yet reached its final form.
It may not be fully compatible with current versions of Angular.
22ndtech Angular Library
This is a simple library for using 22ndtech services from Angular, implementing the Angular Package Format v4.0.
Currently only unscoped, primary entry-point libraries are supported.
Features:
- 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
Common tasks are present as npm scripts:
npm start
to run a live-reload server with the demo appnpm run test
to test in watch mode, ornpm run test:once
to only run oncenpm run build
to build the librarynpm run lint
to lintnpm run clean
to cleannpm run integration
to run the integration e2e testsnpm install ./relative/path/to/lib
afternpm run build
to test locally in another app
If you need to debug the integration app, please check ./integration/README.md
.
The 22ndtech Angular Library
This example repository has an implemention of the described package format but is by no means the only way you should publish a library.
Any setup that builds the necessary package format works just as well for a consumer. You are encouraged to customize this process as you see fit.
When developing your own setup, keep in mind that even though AOT is preferred, Just-in-time compilation should be supported.
Make sure you have at least Node 6.9 and NPM 3.0 installed. Then …
- Create a project folder (you can call it
22ndtech-angular-lib
and rename it later). - Clone or download the 22ndtech Angular Library into your project folder.
- Install npm packages.
- Run
npm start
to launch the sample application.
Clone
Perform the clone-to-launch steps with these terminal commands.
git clone https://github.com/angular/22ndtech-angular-lib.git 22ndtech-angular-lib
cd angular-22ndtech-angular-lib
npm install
npm start
Download
Download the 22ndtech Angular Library seed and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
cd 22ndtech-angular-lib
npm install
npm start
Initialize your repository
If you cloned the package from github, it has a .git
folder where the official repository's history lives.
You don't want that git history though - you'll want to make your own.
Delete this folder and initialize this one as a new repository:
rm -rf .git # Linux or OS/X (bash)
rd .git /S/Q # Windows
git init
Warning: Do this only in the beginning to avoid accidentally deleting your own git setup!
What's in the 22ndtech Angular Library?
The 22ndtech Angular Library contains a similar structure to the Quickstart seed. It's modified to build and test a library instead of an application.
Consequently, there are many different files in the project. Focus on the following TypeScript (.ts
) files in the /src
folder.
src/
├── demo/
| └── app/
| ├── app.component.ts
| └── app.module.ts
└── lib/
├── index.ts
└── src/
├── component/
| └── lib.component.ts
├── service/
| └── lib.service.ts
└── module.ts
Each file has a distinct purpose and evolves independently as the application grows.
Files outside src/
concern building, deploying, and testing your app. They include configuration files and external dependencies.
Files inside src/lib/
"belong" to your library, while src/demo/
contains a demo application that loads your library.
Libraries do not run by themselves, so it's very useful to have this "demo" app while developing to see how your library would look like to consumers.
When you run npm start
, the demo application is served.
The following are all in 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
You can build the library by running npm run build
. This will generate a dist/
directory with all the entry points described above.
All the logic for creating the build can be found in ./build.js
. It consists of roughly 5 steps:
- 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
andREADME.md
files
Testing libraries
While testing is always important, it's especially important in libraries because consumer applications might break due to bugs in libraries.
But the fact that a library is consumed by another application is also what makes it hard to test.
To properly test a library, you need to have an integration tests. An integration test is to libraries what an end-to-end test is to applications. It tests how an app would install and use your library.
The 22ndtech Angular Library includes a directory called integration
containing a standalone app that consumes your built library in both AOT and JIT modes, with end-to-end tests to verify it works.
To run the integration tests, do npm run integration
which does the following:
- 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.
Running integration tests gives you greater confidence that your library is properly built.
In addition to integration tests, you can also run unit tests in watch mode via npm run test
, or single-run via npm run test:once
.
You can also test your library by installing it in another local repository you have. To do so, first build your lib via npm run build
. Then install it from your other repo using a relative path to the dist folder: npm install relative/path/to/library/dist
.
Publishing your library
Every package on NPM has a unique name, and so should yours. If you haven't already, now is the time to change the name of your library.
Use your editor to search the project for all instances of angular-22ndtech-angular-lib
and change it to your intended name (also in dash-case
format). The library name is mentioned on at least these files:
integration/src/app/app.component.ts
integration/src/app/app.module.ts
integration/src/systemjs.config.js
integrations/package.json
src/demo/app/app.component.ts
src/demo/app/app.module.ts
src/demo/systemjs.config.js
src/demo/tsconfig.json
src/lib/tsconfig.json
src/lib/tsconfig.es5.json
bs-config.json
package.json
README.md
You'll also need to rename the folder your project is in.
After you have changed the package name, you can publish it to NPM (read this link for details).
Instead of following the Updating the package
on that previous doc, here we use standard-version. Read their docs to see how to use it.
First you'll need to create a NPM account and login on your local machine. Then you can publish your package by running npm publish dist/
.
Since your package is built on the dist/
folder this is the one you should publish.
Appendix: Supporting AOT
AOT plays an important role in optimizing Angular applications. It's therefore important that third party libraries be published in a format compatible with AOT compilation. Otherwise it will not be possible to include the library in an AOT compiled application.
Only code written in TypeScript can be AOT compiled.
Before publishing the library must first be compiled using the AOT compiler (ngc
). ngc
extends the tsc
compiler by adding extensions to support AOT compilation in addition to regular TypeScript compilation.
AOT compilation outputs three files that must be included in order to be compatible with AOT.
Transpiled JavaScript
As usual the original TypeScript is transpiled to regular JavaScript.
Typings files
JavaScript has no way of representing typings. In order to preserve the original typings, ngc
will generate .d.ts
typings files.
Meta Data JSON files
ngc
outputs a metadata.json file for every Component
and NgModule
. These meta data files represent the information in the original NgModule
and Component
decorators.
The meta data may reference external templates or css files. These external files must be included with the library.
NgFactories
ngc
generates a series of files with an .ngfactory
suffix as well. These files represent the AOT compiled source, but should not be included with the published library.
Instead the ngc
compiler in the consuming application will generate .ngfactory
files based on the JavaScript, Typings and meta data shipped with the library.
Why not publish TypeScript?
Why not ship TypeScript source instead? After all the library will be part of another TypeScript compilation step when the library is imported by the consuming application.
Generally it's discouraged to ship TypeScript with third party libraries. It would require the consumer to replicate the complete build environment of the library. Not only typings, but potentially a specific version of ngc
as well.
Publishing plain JavaScript with typings and meta data allows the consuming application to remain agnostic of the library's build environment.
Appendix: Supporting JIT
AOT compiled code is the preferred format for production builds, but due to the long compilation time it may not be practical to use AOT during development.
To create a more flexible developer experience a JIT compatible build of the library should be published as well. The format of the JIT bundle is umd
, which stands for Universal Module Definition. Shipping the bundle as umd
ensures compatibility with most common module loading formats.
The umd
bundle will ship as a single file containing ES5 JavaScript and inlined versions of any external templates or css.
Appendix: Dependency Management
As a library maintainer, it's important to properly manage your dependencies in package.json
.
There are three kinds of dependencies: dependencies
, devDependencies
and 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 (insrc/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 todependencies
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.
A good example of a peer dependency is @angular/core
and all other main Angular libraries. If you listed these in dependencies
, a new one - with a different version! - could be installed for your library to use. This isn't what you wanted though. You want your library to use the exact same @angular/core
that the app is using.
You'll usually used @angular/*
libraries listed in both devDependencies
and peerDependencies
. This is normal and expected, because when you're developing your library also need a copy of them installed.
Another thing to remember is to keep your dependencies from changing too much unexpectedly. Different versions of libraries can have different features, and if you inadvertently are too lenient with allowed versions your library might stop working because a dependency changed.
You can choose what versions you allow by using ranges.
A good rule of thumb is to have all dependencies
specified with a tilde ~
(~1.2.3
), while your peerDependencies
have a range ("@angular/core": ">=4.0.0 <5.0.0 || >=4.0.0-beta <5.0.0"
).
Any extra dependency or peer dependency that you add to package.json
should also be added to the globals
and external
array in the rollupBaseConfig
variable in ./build.js
.
This ensures your library doesn't package extra libraries inside of it and instead uses the ones available in the consuming app.
你可能也喜欢
- 47pages-keystone 中文文档教程
- @1500cloud/taitimestamp 中文文档教程
- @2003scape/rsc-world-map 中文文档教程
- @7polo/editorjs-code 中文文档教程
- @aave/aave-ui-kit 中文文档教程
- @abhilashmalhotra/react-components 中文文档教程
- @abi-software/svg-sprite 中文文档教程
- @ableco/coding-standards-javascript 中文文档教程
- @abstractpoint/subatomic 中文文档教程
- @abtnode/blocklet-services 中文文档教程