240 lines
9.1 KiB
Markdown
240 lines
9.1 KiB
Markdown
# 某组织团队Web端业务控件库服务
|
||
|
||
基于[元子组件库][GCPDesignPro]、[公共控件库][GCPWebFramework]封装的控件库，可输出Vue组件、JS模块、工具函数等。
|
||
|
||
## 目录结构
|
||
```
|
||
某组织团队Web端业务控件库
|
||
├─ .storybook storybook配置目录
|
||
│ ├─ main.js storybook 主配置
|
||
│ ├─ preview-head.html 自定义预览页面<head></head>
|
||
│ └─ preview.js 预览页面配置文件
|
||
├─ gcp-config.js GCP-CLI配置文件 类似 vue.config.js
|
||
├─ package.json
|
||
├─ examples 示例目录
|
||
│ └─ gcp-meta-json.ts 控件库元数据配置示例
|
||
├─ public 公共资源目录，部署时会把目录下所有文件原样放到根目录
|
||
│ └─ gcp-meta.json 打包后，提供给界面设计器使用的配置文件
|
||
├─ src
|
||
│ ├─ assets 存放字体图标、图片 等
|
||
│ ├─ index.js 启动入口
|
||
│ ├─ utils 存放一些工具函数
|
||
│ └─ widgets 需要exposes的控件
|
||
│ ├─ action 操作按钮类控件，也包含按钮发起弹窗类
|
||
│ │ └─ RefreshAction.vue
|
||
│ ├─ form 表单类控件; 如：editor, formTable等
|
||
│ ├─ layout 布局类控件
|
||
│ ├─ view 视图类控件，一般为路由页面根组件
|
||
│ ├─ normal-vue 普通Vue类控件
|
||
│ │ └─ CompositionApiSample.vue
|
||
│ └─ others 除以上类型之外的统一归为others
|
||
├─ stories storybook 组件文档及用例
|
||
│ └─ action
|
||
│ └─ RefreshAction.stories.js
|
||
└─ types TS声明文件目录
|
||
└─ widgetLibTypes.d.ts 控件库元数据Schema定义
|
||
|
||
```
|
||
## 开发流程
|
||
|
||
### 一、修改默认配置
|
||
脚手架中有些配置的关键词需要手动修改，如：包名、库名、publicPath、元数据等。
|
||
|
||
#### 1. 脚手架配置修改
|
||
根目录下[gcp-config.js](./gcp-config.js)中的包名、库名、publicPath需要修改，cdnBaseUrl、框架版本号选择性修改。
|
||
```js
|
||
// ...
|
||
// 根据“工作空间+业务领域+Widgets+目标终端”对库名进行修改，全局唯一
|
||
const name = 'WorkspaceBusinessWidgetsWeb'
|
||
// 需要部署的静态服务域名，推荐使用CDN，以达到最佳性能与体验
|
||
const cdnBaseUrl = 'https://cdn.developer.glodon.com'
|
||
// ...
|
||
module.exports = defineConfig(({ mode, env }) => {
|
||
// ...
|
||
// 根据工作空间、业务领域配置静态资源路径
|
||
const publicPath = `${host}/workspace/business-widgets-web/${libVersion}/`
|
||
|
||
return {
|
||
// ...
|
||
remotes: {
|
||
// 开发框架引用；使用框架最新稳定版本
|
||
'@gcbp/web-framework': `promise GcpCliAsyncRemotesConfig.getByName('GCPWebFramework')`
|
||
},
|
||
shareLib: {
|
||
// Vue版本不可修改
|
||
vue: 'Vue@https://cdn.staticfile.org/vue/2.6.14/vue.min.js',
|
||
// Vuex版本不可修改
|
||
vuex: 'Vuex@https://cdn.staticfile.org/vuex/3.6.2/vuex.min.js',
|
||
// 基础组件库引用；默认使用latest最新版，可修改为固定版本更加稳定
|
||
'@geip/basic-components': [
|
||
`GCPDesignPro@${cdnBaseUrl}/gcp/gcp-design-pro/latest/index.js`,
|
||
`${cdnBaseUrl}/gcp/gcp-design-pro/latest/theme-default/index.css`
|
||
]
|
||
}
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
#### 2. 修改package.json包配置
|
||
根目录下`package.json`中包名需要修改，可根据“工作空间+业务领域+Widgets+目标终端”命名，保证全局唯一
|
||
```json
|
||
{
|
||
"name": "@workspace/business-widgets-web", // 控件库包名
|
||
"description": "某组织团队Web端业务控件库描述", // 描述控件库的用途、适用范围等。
|
||
// ...
|
||
"devDependencies": {
|
||
// ...
|
||
// 按需安装依赖
|
||
},
|
||
"dependencies": {
|
||
// ...
|
||
// 按需安装依赖
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 修改控件库元数据配置
|
||
元数据文件`./public/gcp-meta.json`默认配置需要修改。
|
||
```json
|
||
{
|
||
"name": "WorkspaceBusinessWidgetsWeb", // 库名；要求与gcp-config.js中库名保持一致
|
||
"packageName": "@workspace/business-widgets-web", // 包名；要求与package.js中包名保持一致
|
||
"description": "某组织团队Web端业务控件库描述", // 可与package.js中的描述一致
|
||
"widgets": {
|
||
"action": [],
|
||
"layout": [],
|
||
"form": [],
|
||
"normalVue": [],
|
||
"others": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 二、编写Vue控件
|
||
编写Vue控件需要对平台控件库、开发框架有一定了解，否则请先进入文档学习[元子组件库][GCPDesignPro]、[公共控件库][GCPWebFramework]
|
||
|
||
#### 1. 安装依赖
|
||
如果要编写的控件需要依赖第三方的库实现，可以预先安装好备用，如：
|
||
```bash
|
||
npm install lodash
|
||
```
|
||
|
||
#### 2. 控件源码编写
|
||
基于平台提供的[元子组件库][GCPDesignPro]、[公共控件库][GCPWebFramework] ，进行Vue组件的开发；
|
||
|
||
可参考控件示例[GcdpOpenModalAction](./src/widgets/action/GcdpOpenModalAction.vue)
|
||
|
||
更多详细使用可参考[前端开发框架文档][GCPWebFramework]
|
||
#### 3. 增加控件输出
|
||
在控件库配置[gcp-config.js](./gcp-config.js)中增加控件输出，如：
|
||
```js
|
||
// ...
|
||
module.exports = defineConfig(({ mode, env }) => {
|
||
// ...
|
||
return {
|
||
// ...
|
||
exposes: {
|
||
// 导出 SampleAction 控件
|
||
'./action/SampleAction': './src/widgets/action/SampleAction.vue'
|
||
},
|
||
// ...
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
#### 4. 删除示例控件及输出配置
|
||
开发完一个控件后删除脚手架中的示例控件，以免产生不必要的空间占用、下载流量，进而影响性能（虽然影响不大）；
|
||
- 删除控件`./src/widgets/action/RefreshAction.vue`,`./src/widgets/normal-vue/CompositionApiSample.vue`
|
||
- 在[gcp-config.js](./gcp-config.js)中删除输出配置：
|
||
```js
|
||
// ...
|
||
module.exports = defineConfig(({ mode, env }) => {
|
||
// ...
|
||
return {
|
||
// ...
|
||
exposes: {
|
||
// ...
|
||
// 删除以下控件输出
|
||
'./action/GcdpOpenModalAction': './src/widgets/action/GcdpOpenModalAction.vue',
|
||
'./normal-vue/CompositionApiSample': './src/widgets/normal-vue/CompositionApiSample.vue'
|
||
},
|
||
// ...
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
### 三、编写控件元数据
|
||
编写控件元数据是为了提供开发平台界面设计器在控件库面板中正常展示控件，以及属性面板中正常展示其属性。
|
||
|
||
具体如何编写请查阅[控件库元数据编写规范](https://cdn.developer.glodon.com/gcp/gcdp-docs/latest/?path=/story/%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97-%E6%8E%A7%E4%BB%B6%E5%BA%93%E5%85%83%E6%95%B0%E6%8D%AE%E8%A7%84%E8%8C%83--page)
|
||
|
||
另外可参考[元数据配置示例](./examples/gcp-meta-json.ts)
|
||
|
||
### 四、开发调试
|
||
#### 1. 安装依赖
|
||
安装控件库的npm依赖包
|
||
```bash
|
||
npm install
|
||
```
|
||
> 如果未进行Git初始的新项目，需要先执行`git init`，再进行依赖的安装，否则Git hooks会报错
|
||
|
||
#### 2. 启动storybook文档
|
||
启动storybook文档后，可在浏览器里实时进行控件预览、文档预览、开发调试等。
|
||
```bash
|
||
npm run storybook
|
||
```
|
||
> 启动后会在浏览器自动打开 http://localhost:6008
|
||
|
||
### 五、构建部署
|
||
可通过Jenkins或其它CICD工具按以下步骤进行配置，保证部署到一个可访问的静态服务地址。
|
||
|
||
#### 1. 版本升级
|
||
如果代码有变动，强烈建议升级版本号，避免对上个版本产生影响
|
||
|
||
```bash
|
||
npm version patch # patch/minor/major/prepatch/preminor/premajor/prerelease/from-git
|
||
```
|
||
> 根据修改内容，选择如下指令更新版本号：
|
||
> patch: 一般只修复了Bug，minor: 增加了功能，major: 核心变更，重构等
|
||
> 执行此命令后，同时生成CHANGELOG，并push到Git远程仓库
|
||
|
||
#### 2. 构建打包
|
||
执行以下命令将控件库打包，以备部署使用
|
||
`npm run build`
|
||
|
||
#### 3. 部署到服务器
|
||
将打包输出目录`./dist`下的静态文件，部署到一个静态文件服务器（如：OSS）；
|
||
推荐采用**静态文件服务 + CDN**的部署方案提供一个CDN控件库资源URL，以达到最佳的性能与体验
|
||
|
||
### 六、控件库注册
|
||
#### 1. 资源库继承体系
|
||
资源库包括：控件库、图标库
|
||
开发平台为资源库提供了三层注册途径，继承关系如下：
|
||
|
||
租户 ——> 组件 ——> 模板
|
||
|
||
对象管理下的页面设计器，是从模板开始依次向上查找资源库，将匹配到的所有控件库在控件库面板中展示；
|
||
|
||
#### 2. 控件库注册
|
||
|
||
开发者可根据实际情况选择在哪一层进行注册，详细操作步骤请查阅[资源库注册](#)说明文档
|
||
注册完成后，即可在开发平台的页面设计器中使用了。
|
||
|
||
|
||
[GCPDesignPro]:https://cdn.developer.glodon.com/gcp/gcp-design-pro-docs/latest/
|
||
[GCPWebFramework]:https://developer.glodon.com/docs/geip/kaifazhinan/v1/n4v39212
|
||
|
||
## 翻译平台多语言配置
|
||
|
||
// package.json
|
||
```
|
||
"scripts": {
|
||
"write:i18n": "i18n-tool write gcp-cli-seed-plugins-web 1*****************", // gcp-cli-seed-plugins-web 需要查找翻译文件的目录，此项目定义为根文件目录
|
||
"publish:i18n": "i18n-tool publish gcp-cli-seed-plugins-web 1*****************" // 1***************** 翻译网站分组的id
|
||
}
|
||
```
|
||
> write 将翻译网站的内容写入到locales文件中
|
||
> publish 将locales文件夹下的所有需要翻译的多语言占位符推送到[翻译网站](http://10.0.197.220:7081/#/projects) |