360medics-ng2 中文文档教程

Question

angular-library-starter

构建一个与 AoT 编译 & 兼容的 Angular 库 像官方包一样摇树。

此启动程序允许您为 Angular v7 应用程序创建一个库。 该项目基于官方 Angular 包。

获取 变更日志。

Contents

• 1 Project structure
• 2 Customizing
• 3 Testing
• 4 Building
• 5 Publishing
• 6 Documentation
• 7 Using the library
• 8 What it is important to know
• 9 Inlining of templates and stylesheets
• Built with this starter
• Previous versions

1 Project structure

• Library:
  • src folder for the classes
  • public_api.ts entry point for all public APIs of the package
  • package.json npm options
  • rollup.config.js Rollup configuration for building the umd bundles
  • rollup.es.config.js Rollup configuration for building the es2015 bundles
  • tsconfig-build.json ngc compiler options for AoT compilation
  • build.js building process using ShellJS
• Testing:
  • tests folder for unit & integration tests
  • karma.conf.js Karma configuration that uses webpack to build the tests
  • spec.bundle.js defines the files used by webpack
• Extra:
  • tslint.json Angular TSLint Preset (TypeScript linter rules with Codelyzer)
  • travis.yml Travis CI configuration

2 Customizing

1. 更新 Node & npm。

2. 将 angular-library-starter 和 angularLibraryStarter 重命名为 my-library 和 myLibrary。

3. 使用您的图书馆许可证自定义 license-banner.txt 文件。

4. 更新 package.json 文件：

   • version: Semantic Versioning
   • description
   • urls
   • packages (optional): make sure you use a version of TypeScript compatible with Angular Compiler

   并运行 npm install。

5. 在 src 文件夹中创建您的类，并在 my-library.ts 中导出公共类。

6. 您只能为整个库创建一个模块： 我建议你为不同的功能创建不同的模块， 这样宿主应用程序就可以只导入它使用的模块，并优化它的Tree shaking。

7. 将 rollup.config.js 文件 globals 外部依赖项更新为您实际用于构建 umd 包的依赖项。

8. 创建单元 & tests 文件夹中的集成测试，或在 src 文件夹中测试的内容旁边进行单元测试，始终使用 .spec.ts 扩展名。

3 Testing

以下命令运行 unit & tests 文件夹中的集成测试（您可以在 spec.bundle.js 文件中更改文件夹）：

npm test 

或处于监视模式：

npm run test:watch

它还使用 报告覆盖率伊斯坦布尔。

4 Building

以下命令：

npm run build

• starts TSLint with Codelyzer using Angular TSLint Preset
• starts AoT compilation using ngc compiler
• creates dist folder with all the files of distribution, following Angular Package Format (APF):

└── dist
    ├── bundles
    |   ├── my-library.umd.js
    |   ├── my-library.umd.js.map
    |   ├── my-library.umd.min.js
    |   └── my-library.umd.min.js.map
    ├── esm5
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── esm2015
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── fesm5
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── fesm2015
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── src
    |   └── **/*.d.ts
    ├── my-library.d.ts
    ├── my-library.metadata.json
    ├── LICENSE
    ├── package.json
    ├── public_api.d.ts
    └── README

在发布前在本地测试 npm 包：

npm run pack:lib

然后您可以将其安装在应用程序中进行测试：

npm install [path]my-library-{version}.tgz

5 Publishing

在第一次发布之前：

• you can register your library on Travis CI: you have already configured .travis.yml file
• you must have a user on the npm registry: Publishing npm packages

npm run publish:lib

6 Documentation

为了生成文档，这个启动器使用 compodoc：

npm run compodoc
npm run compodoc:serve 

7 Using the library

Installing

npm install my-library --save 

Loading

Angular-CLI

无需设置任何内容，只需将其导入您的代码即可。

Rollup or webpack

无需设置任何内容，只需将其导入您的代码即可。

Using SystemJS configuration

System.config({
    map: {
        'my-library': 'node_modules/my-library/bundles/my-library.umd.js'
    }
});

Plain JavaScript

在 index.html 中包含 umd 包：

<script src="node_modules/my-library/bundles/my-library.umd.js"></script>

并使用全局 ng.myLibrary 命名空间。

AoT compilation

该库与AoT 编译 兼容。

8 What it is important to know

1. package.json

   • "main": "./bundles/angular-library-starter.umd.js" legacy module format
   • "module": "./esm5/angular-library-starter.js" flat ES module, for using module bundlers such as Rollup or webpack
   • "es2015": "./esm2015/angular-library-starter.js" ES2015 flat ESM format
   • "typings" declaration files for TypeScript compiler
   • "peerDependencies" the packages and their versions required by the library when it will be installed

2. tsconfig.json TypeScript 编译器

   • Compiler options:
     • "strict": true enables TypeScript strict master option

3. 使用的文件 tsconfig-build.json 使用的文件ngc 编译

   • 器 编译器选项：

     • "declaration": true to emit TypeScript declaration files
     • "module": "es2015" & "target": "es2015" are used by Rollup to create the ES2015 bundle

   • Angular 编译器选项：

     • "enableResourceInlining": true inlining of templates & styles
     • "skipTemplateCodegen": true skips generating AoT files
     • "annotateForClosureCompiler": true for compatibility with Google Closure compiler
     • "strictMetadataEmit": true without emitting metadata files, the library will not be compatible with AoT compilation: it is intended to report syntax errors immediately rather than produce a .metadata.json file with errors
     • "flatModuleId": "@scope/package" full package name has to include scope as well, otherwise AOT compilation will fail in the consumed application

4. rollup.config.js 由 Rollup

   • format: 'umd' the Universal Module Definition pattern is used by Angular for its bundles
   • moduleName: 'ng.angularLibraryStarter' defines the global namespace used by JavaScript apps
   • external & globals declare the external packages

5. 服务器端渲染

   使用的文件如果您希望库与服务器端兼容渲染：

   • window, document, navigator and other browser types do not exist on the server
   • don't manipulate the nativeElement directly

9 Inlining of templates and stylesheets

现在 ngc 编译器支持内联模板 & 样式。 此外，此启动器允许您使用 .scss sass 文件。 如果需要，您可以使用不同的预处理器。

Built with this starter

• angular-l10n An Angular library to translate messages, dates and numbers
• angular-auth-oidc-client An OpenID Connect Implicit Flow client for Angular
• ngx-infinite-scroll An infinite scroll directive for Angular compatible with AoT compilation and Tree shaking
• ngx-typeahead A simple but yet powerful typeahead component for Angular
• ng2-youtube-player A Powerful Youtube Player Component for Angular
• ng2-completer Angular autocomplete component
• ngx-store Angular Storage library for managing localStorage, sessionStorage and cookies, allowing to watch storage changes. Includes easy-to-use decorators, services and API based on builder pattern.
• ngx-table-editor A library for Angular that transforms HTML tables into dynamic editable components.
• ngx-ui-scroll An Angular *ngFor-like directive for infinite/virtual scrolling

Previous versions

• Angular v6

  • Branch

• Angular v5

  • Branch

• Angular v4

  • Branch

• Angular v2

  • Branch

License

麻省理工学院