Angular 17+ 高级教程 – Library

  • Angular 17+ 高级教程 – Library已关闭评论
  • 45 次浏览
  • A+
所属分类:Web前端
摘要

当你需要管理超过一个项目时,你就需要知道怎么使用 Angular Library。你可以把多个项目共享的组件放到这个 Library 了,就像 Angular Material 那样。


前言

当你需要管理超过一个项目时,你就需要知道怎么使用 Angular Library。

你可以把多个项目共享的组件放到这个 Library 了,就像 Angular Material 那样。

 

参考

Sandro Roth – Building an Angular Library with multiple entry points (主要参考)

Docs – Creating libraries

Docs – Copy assets

Docs – Embed assets in CSS

Stack Overflow – Include assets when building angular library

 

Angualr Library の Get Started 版

我们先来一个 Get Started 版本,之后再补一个实战版。

提醒:我这里给的例子 Library 和 Application 会在同一个项目里 (所谓的 Local Library)。如果要不同项目,那就需要把 Library 发布到 npm 才行。在本篇的结尾会讲解如何 publish to npm。

Create project

ng new play-library --create-application=false

在创建项目的同时,不要创建 Application 先,因为有 Library,folder 结构会不一样。

目前 folder 结构长这样

Angular 17+ 高级教程 – Library

angular.json 长这样

Angular 17+ 高级教程 – Library

空空如也。

Create Application

接着创建 Application

ng g app my-app --routing=false --ssr=false --style=scss --skip-tests

folder 多了一个 projects/my-app

Angular 17+ 高级教程 – Library

angular.json 也多了一个 projects.my-app 配置

Angular 17+ 高级教程 – Library

Create Library

接着创建 Library

ng g lib stooges --prefix=stg

我的 Library 名字叫 stooges

folder 又多了一个 projects/stooges

Angular 17+ 高级教程 – Library

stooges library 里,Angular 默认会替我们创建一个 demo component 和 service。

angular.json 也多了一个 projects.stooges 配置

Angular 17+ 高级教程 – Library

Build library

要使用 Library ,我们需要先 build 它。

ng build stooges --watch

build 也是可以 watch 的哦,每当我们修改,它就会 re-build (我不清楚是 re-build 修改的部分还是全部🤷‍♂️)

Angular 17+ 高级教程 – Library

build 好之后,它会多一个 folder -- dist/stooges 

Use library in application

app.component.ts

import { Component } from '@angular/core'; import { StoogesComponent } from 'stooges'; // 1. import component from library  @Component({   selector: 'app-root',   standalone: true,   imports: [StoogesComponent],              // 2. import StoogesComponent   templateUrl: './app.component.html',   styleUrl: './app.component.scss' }) export class AppComponent {}

app.component.html

<stg-stooges />

run

ng serve --open

效果

Angular 17+ 高级教程 – Library

哎哟,不错哦!It just work😎。

The connection between the library and the application

你可能会好奇,app.component.ts 为什么可以 import 到 'stooges'

import { StoogesComponent } from 'stooges';

stooges library 在 dist 里,并不在 node_modules 里丫🤔。

它的秘密在 tsconfig.json 里

Angular 17+ 高级教程 – Library

在 ng g lib 时,它偷偷往里头做了一个 connection 配置,所以 Application 就和 Library 连上了。

总结

Get Started 只是让大家感受以下 Angular Library 长啥样,上面提到的几个 folder 和 file 都是和 Library 比较有关系的,如果以后遇到什么疑难杂症可以多往这几个地方调查。

好,我们进入下一 part -- Angualr Library 实战版。

 

Angualr Library の 实战版

我们延续上面 Get Started 版本,把它改成实战版。

Multiple export path

Angular 17+ 高级教程 – Library

目前有一个问题 -- Library 只有一个出入口

import { StoogesComponent } from 'stooges';

假如我有 1000 个组件,由于它们都是通过 import .. from 'stooges' 导入,那它们就绝对不可以撞名字。

这对命名要求很高啊。

那...如果可以这样...

import { StgDialogComponent, StgSameNameComponent as StgDialogSameNameComponent } from 'stooges/dialog'; import { StgCardComponent, StgSameNameComponent as StgCardSameNameComponent } from 'stooges/card';

stooges/table 和 stooges/select 都是 stooges library,但 stooges library 里面又细分成了 2 个 namespace 'table' 和 'select'。

我们可以以 2 个不同的 path 做 import,这样就大大减少了撞名字的可能性,即使撞了名字也可以通过 as alias 换名。

restructure folder

首先,把 src/lib/ folder 给删了。

改成这样

Angular 17+ 高级教程 – Library

select 和 table 将成为 2 个 export path,它们里面装了很多组件,细节我们下面再看。

index.ts 取代了原本的 src/public_api.ts

Angular 17+ 高级教程 – Library

由于我没有需要 root export (因为有了 select 和 table 2 个 sub export),所以这里做一个假 export 骗过它就好。

接着,ng-package.json 的路径需要换一下

Angular 17+ 高级教程 – Library

然后是 table 和 select folder

Angular 17+ 高级教程 – Library

每一个要 sub export 的 folder 都需要加上 index.ts 和 ng-package.json。

index.ts 负责 export 组件

Angular 17+ 高级教程 – Library

ng-package.json 就抄 root 的 ng-package.json

Angular 17+ 高级教程 – Library

有两个小区别:

  1. $schema 路径多了一个 ../

  2. root 有一个 "dest" : "../../dist/stooges" 属性,sub 不需要 "dest" 属性。

select 和 table 一样,也需要 index.ts 和 ng-package.json。

Angular 17+ 高级教程 – Library

build library

接着 build library

ng build stooges --watch

效果

Angular 17+ 高级教程 – Library

之前只有一个 lib folder,现在变成了 select 和 table 2 个 folders。

connect library

connect library 会比之前复杂一些。

首先是 tsconfig.ts

Angular 17+ 高级教程 – Library

本来是直接链接到 dist library,现在改成链接到原本的 source library,然后结尾要用 /* 表示匹配 multiple path。

接着是 angular.json

Angular 17+ 高级教程 – Library

把 /src 移除

再来是 /projects/my-app/tsconfig.app.json

Angular 17+ 高级教程 – Library

这里链接到 dist library,之前 root tsconfig 则是链接到 source library,一个 dist 一个 source 被搞错哦。

test run application

build and connect 之后就可以 test run 了。

app.component.ts

import { Component } from '@angular/core'; import { StgSelectModule } from 'stooges/select'; // 1. import component from library import { StgTableModule } from 'stooges/table';   // 2. import component from library  @Component({   selector: 'app-root',   standalone: true,   imports: [StgSelectModule, StgTableModule],    templateUrl: './app.component.html',   styleUrl: './app.component.scss' }) export class AppComponent {}

两个 module 分别 import from 各自的 path。

app.component.html

<stg-table>   <stg-tr>     <stg-td />     <stg-td />   </stg-tr> </stg-table>  <stg-select>   <stg-option />   <stg-option /> </stg-select>

run

ng serve --open

效果

Angular 17+ 高级教程 – Library

import sub path inside library

library 内如果需要互相 import,也是使用绝对路径。

Angular 17+ 高级教程 – Library

Export scss

除了 multiple export path,另一个常见的需求是要 export scss。

首先在 library 里创建一个 styles forlder 

Angular 17+ 高级教程 – Library

reset.scss 和 _theme.scss

Angular 17+ 高级教程 – Library

添加 assets 配置到 ng-package.json

Angular 17+ 高级教程 – Library

表示我们要 export styles 这个 folder 里的所有 scss。

build library

ng build stooges --watch

效果

Angular 17+ 高级教程 – Library

_theme.scss 和 reset.scss 被打包出来了。

connect library

添加 stylePreprocessorOptions 到 angular.json

Angular 17+ 高级教程 – Library

这样 application 就能链接到 dist library 的 styles 了。

test run application

Angular 17+ 高级教程 – Library

run

ng serve --open

效果

Angular 17+ 高级教程 – Library

margin 被 reset.scss 清除了,body background 也被 theme.scss 染成了粉红色。

Export assets

scss 可以 export,其它类型的 file 也可以 export,比如图片,虽然图片不常会被封装进 Library。

添加 assets folder 到 Library

Angular 17+ 高级教程 – Library

里面有一张图片。

在 ng-package.json 里再添加多一个 assets 配置

Angular 17+ 高级教程 – Library

意思是我们要 export 所有 assets 里的 files。

build library

ng build stooges --watch

效果

Angular 17+ 高级教程 – Library

图片被打包出来了。

connect library

到 angular.json 添加 assets 配置

Angular 17+ 高级教程 – Library

这样 application 就链接上了 dist library 的 assets files。

test run application

app.component.html

Angular 17+ 高级教程 – Library

path starts with /stg-assets/**/* (使用绝对路径)

run

ng serve --open

效果

Angular 17+ 高级教程 – Library

use assets inside library

假设,我们没有 export assets,但是我们有 assets,我们只是在 library 中使用它。

这种情况的话,假如图片用于 scss url('....') 那它会被自动 convert to base64,我们可以不需要做 export。

假如图片被用于 <img src="..." >,这样不行,它不会自动 convert to base64,我们一定要 export assets 才行。

Angular 17+ 高级教程 – Library

另外,有 export 的必须使用绝对路径,如果 url('...') 使用相对路径那它会 convert to base64,如果使用绝对路径则不会 convert to base64 (使用绝对路径,我们就要确保有 export 图片哦,不然就空白了)。

总结

它其实就是几个东西在玩。

首先是 library folder 结构

然后是 library 要 export 的配置

接着 build to dist

然后 application 要 connect to dist library 或者 souce library

ts, scss, assets 三个的 export 和 connect 配置都不太一样。

大概就是这些,建议大家自己动手玩一玩。

 

Publish Library

publish 很简单,因为我们已经 build to dist 了,把整个 dist folder 发布到 npm 就可以了。

cd dist/stooges npm publish

publish 好了后就可以下载了

yarn add stooges

接着需要把 connect to dist 换成 connect to node_modules。

首先,root tsconfig 不需要 connect to source library 了,因为 node_modules 里的 ts 是自动 connect 的。

Angular 17+ 高级教程 – Library

同样,application 的 tsconfig 也不需要 connect to dist library 了

Angular 17+ 高级教程 – Library

ts 不需要配置,但是 scss 和 assets 需要。

去 angular.json 把 connect to dist 换成 connect to node_modules

Angular 17+ 高级教程 – Library

搞定!

 

关于 peerDependencies

Library 或许会依赖其它的 Library,通常这些依赖不会写在 package.json 的 dependencies,而会写在 peerDependencies。

Angular 17+ 高级教程 – Library

它们的区别是,peerDependencies 要求使用 Library 的人在外部去 yarn add 这些 Library 依赖,好处是不会 duplicated,因为 Application 和 Library 或许有相同的依赖,总不能 2 边分开加载,是吧。

 

目录

上一篇 Angular 17+ 高级教程 – EventManagerPlugin & Hammer.js Gesture

下一篇 Angular 17+ 高级教程 – Prettier, ESLint, Stylelint

想查看目录,请移步 Angular 17+ 高级教程 – 目录