angular第三方包开发

发表于 更新于 分类于
将一个功能模块化提供给其他的应用使用是我们经常会遇到的需求，这个笔记记录了如何开发angular第三方插件，包括插件开发、npm发布、应用案例。

前几天大师兄说需要将已经开发完成的Saga在线工具模块化，提供给其他平台使用。所以打算先开发一个angular版本的插件试试。

以下为开发angular插件的教程：

1 开发基于angular的插件

1.1 初始化

在本地电脑中选择开发目录，开始初始化，cmd下：

1
2
3
mkdir ng-test-plugin
cd ng-test-plugin
npm init

在npm init之后需要填写第三方包的基本信息，项目名不可以大写，如果不填写可直接回车。执行完毕后项目中只有一个package.json。

注意：如果第三方包要发布到 npm 上，项目名在npm上已存在会导致发布失败。

1.2 添加 angular 所需依赖

1
npm install --dev typescript@latest @angular/core @angular/common rxjs zone.js

此时安装的包并不需要发布，发布时只发布代码，需要在package.json中配置peerDependencies作为前置依赖，但包本身不会实际安装这些依赖，实际的包应该由应用项目来安装，现在把peerDependencies添加进package.json

1
2
3
4
5
"peerDependencies": {
    "@angular/common": ">=5.0.0",
    "@angular/core": ">=5.0.0",
    "rxjs": ">=5.0.0"
  }

1.3 项目开发

1.3.1 开发插件功能

根目录创建lib文件夹，并在文件夹下创建fivering.component.ts和fivering.module.ts文件

fivering.component.ts文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import { Component, OnInit, Input, Output, EventEmitter } from '@angular/core'
@Component({
  selector: 'app-fivering',
  template: `
            <div class="five-rings">
            <div class="ring1"></div>
            <div class="ring2"></div>
            <div class="ring3"></div>
            <div class="ring4"></div>
            <div class="ring5"></div>
            </div>
            `,
  styles: ['.five-rings{position:fixed;top: 50%;left:50%;width: 290px;height: 130px;margin-top: -65px;margin-left:-145px;} .ring1,.ring2,.ring3,.ring4,.ring5{position: absolute; width: 80px;height: 80px;border-radius: 50%;border:5px solid;}  .ring1{\
    border-color: purple;\
  }\
  .ring2{\
    left: 100px;\
    border-color: black;\
  }\
  .ring3{\
    left: 200px;\
    border-color: red;\
  }\
  .ring4{\
    top: 45px;\
    left: 50px;\
    border-color: yellow;\
  }\
  .ring5{\
    top: 45px;\
    left: 150px;\
    border-color: green;\
  }']
})
export class FiveRingComponent implements OnInit {
  show_rings = false;
  constructor() { }
  ngOnInit() {
  }
}

fivering.module.ts文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { FiveRingComponent } from './fivering.component';
import { CommonModule } from '@angular/common';
import { NgModule } from '@angular/core';

@NgModule({
    declarations: [
        FiveRingComponent
    ],
    imports: [
        CommonModule
    ],
    providers: [],
    exports: [FiveRingComponent],
})
export class FiveRingModule { }

1.3.2 支持TypeScript

为了支持TypeScript,还需要一个tsconfig.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "compilerOptions": {
    "baseUrl": ".", // 基于哪个目录编译ts
    "declaration": true, // 是否生成声明文件即*.d.ts文件，有了它才有TS的代码提示
    "experimentalDecorators": true, // 用于支持TS装饰器如angular中的 @NgModule({}) 之类
    "emitDecoratorMetadata": true, // 用于支持TS装饰器如angular中的 @NgModule({}) 之类
    "module": "commonjs", // 模块化形式
    "moduleResolution": "node", // 模块化形式
    "rootDir": ".", // 以哪个目录为根
    "lib": ["es2015", "dom"], // 支持编译的内置库
    "skipDefaultLibCheck": true, // 是否跳过内置库检查
    "skipLibCheck": true, // 跳过库检查
    "target": "es5", // 编译目标版本
    "suppressImplicitAnyIndexErrors": true, // 几个检查代码的规则
    "strictNullChecks": true, // 几个检查代码的规则
    "noImplicitAny": true, // 几个检查代码的规则
    "sourceMap": true, // 是否生成 .js.map
    "removeComments": true, // 移除注释
    "noFallthroughCasesInSwitch": true // 几个检查代码的规则
  },
  "exclude": [  // 编译时排除以下内容
    "node_modules",
    "*.d.ts",
    "**/*.d.ts"
  ]
}

1.3.3 导出功能

功能完成后需要导出，让其他项目引用，所以在项目根目录下创建一个index.ts文件，文件内容：

1
export * from './lib/fivering.module';

1.3.4 编译打包

修改package.json中的script方便编译打包：

1
2
3
4
5
6
"scripts": {
  "prepublish": "npm run clean && tsc", //清理并编译
  "clean": "rimraf index.js index.js.map index.d.ts lib/**/*.js lib/**/*.js.map lib/**/*.d.ts *.tgz", //清理编译文件
  "link": "npm run pack && tar -zxf linktest.tgz && rimraf ../lib-test-app/node_modules/ng-test-plugin && mv package ../lib-test-app/node_modules/ng-test-plugin",//打包后解压并移动到测试项目的node_modules中，tar -zxf 为解压命令，rimraf为删除命令，mv为移动命令
  "pack": "npm run prepublish && npm pack"  //执行编译并打包成压缩包
}

执行时，使用npm run prepublish形式，clean命令需要先安装rimraf：

1
npm install rimraf -g

2 发布插件

2.1 npm 账号

  1. 注册npm账号： 地址：https://www.npmjs.com

  2. 进入项目根目录下打开终端

    运行：npm login

    输入账号、密码、邮箱

  3. 可使用 npm whoami 命令确认身份

2.2 完善包信息

完善package.json，包括开源许可、包名、作者、版本号等，最重要直接影响发布的是版本号。

2.3 选择性发布

基于angular的第三方包区别与普通的js包最大的地方就在于，不能直接把整个包都发布到npm，这样会导致奇怪错误，原因在于.ts文件，实际上需要发布的只是.js、.js.map、.d.ts这三种类型的文件就够了。

因为在其他项目中不一定会使用TypeScript，即使用了也不会刻意包含node_modules目录，也就是说其他项目只管使用，编译的活由我们得包自己来做，相反要是我们还发布多余的.ts文件，只会导致错误。

为了做到选择性发布，需要一个.npmignore文件，和.gitignore配合用来忽略上传的文件，一般这些编译输出我们会添加在.gitignore中，若项目不存在.npmignore，发布到npm时也会使用.gitignore，这不是我们想要的，所以需要再创建这个.npmignore来忽略.ts文件而包含编译输出：

1
2
3
4
5
6
7
8
node_modules
yarn-error.log
tsconfig.json
.gitignore
.npmignore
yarn.lock
*.ts
!*.d.ts

2.4 执行发布命令

将插件项目发布到npm:

1
2
npm run prepublish
npm publish

3 引用插件

3.1 安装插件

在需要引用插件的项目中执行以下命令安装插件：

1
npm install ng-test-plugin

3.2 引入到项目中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { FiveRingModule } from 'ng-test-sj';    //这里
@NgModule({
  declarations: [
    AppComponent,
    SagaPluginComponent,
  ],
  imports: [
    BrowserModule,
    FiveRingModule  // 这里
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

3.3 html中使用

1
<app-fivering></app-fivering>

4 参考

Yitimo - 简书：angular第三方包开发整理

essential_note - 简书：组件的工程化（开发第三方angular包）