San CLI UI ——不只是San CLI的GUI（实践篇）
前言
本篇我们实现一个显示在仪表盘的小部件。
首先我们回顾一下仪表盘部件的工作流程：
前文提到的插件包的目录结构：
.
├── README.md
├── src
│ └── index.js // 组件注册
├── package.json
└── ui.js // `San CLI UI` 集成（这里存放插件的配置信息）
实现一个显示在仪表盘的小部件，在 ui.js 内主要借助两个 api：
-
api.registerAddon
：注册插件的 id 并且定义加载的路径。 -
api.registerWidget
：注册一个 widget 部件，返回小部件的具体配置。
在 client 端通过 ClientAddonApi
加载组件定义并挂载到仪表盘视图内，因此在 index.js 内需要用到:
-
ClientAddonApi.defineComponent
：组件定义 -
ClientAddonApi.addLocales
：组件扩展语言
插件开发
San CLI UI
提供了将自定义组件挂载到项目仪表盘的方式，通过此功能，你可以定制属于自己的个性仪表盘，也可将小工具分享给更多的人使用。
插件的实践中，我们将演示一个自定义部件的实现，并显示在仪表盘显示的过程。将新增部件分为三步： 创建工程
-> 本地调试
-> 发布安装
创建工程
我们提供了插件创建的脚手架来简化插件的创建过程，脚手架推荐：
- 插件脚手架：https://github.com/jinzhan/san-cli-plugin-template.git
- UI 插件脚手架：https://github.com/zttonly/san-ui-addon-project.git
在脚手架中预置了插件相关的基础配置，当然用户也可以根据自身习惯，创建自己的脚手架工程。
这里我们使用 UI 插件脚手架，创建一个名为 san-cli-ui-widget-hello
的工程，使用 San CLI UI
的创建项目功能，在脚手架地址输入 San CLI UI
插件脚手架地址，按照步骤执行，完成创建。过程演示如下：
在新创建工程的目录中关键的文件： san.config.js
、 ui.js
、 src/index.js
中已包含了默认配置，开发者直接修改其中的名称即可。
新建的插件包目录结构如下：
san-cli-ui-widget-hello
├── README.md
├── src
├──components
│ └── index.js
├── package.json
├── san.config.js
└── ui.js // San UI 集成（这里存放插件的配置信息）
我们逐一来看
在插件工程的 san.config.js
中已预置了由 San CLI UI
提供的默认配置，通过 clientAddonConfig
可生成 san.config.js
的默认配置，打包出的代码输出到 ./dist/index.js
。：
const clientAddonConfig = require('san-cli-ui/client-addon-config');
module.exports = {
...clientAddonConfig({
id: 'san.webpack.client-addon.san-cli-ui-widget-hello', // 名称唯一
port: 8890 // 端口可变
})
};
注意：id 应设置正确的命名，且在所有插件中保持唯一；port 是本地服务的端口，可修改，但应与 ui.js 文件中本地服务 url 保持一致
ui.js
文件已预置了插件加载路径定义和 widget 部件定义：
module.exports = api => {
// 注册组件加载路径 区分生产环境和开发环境
if (process.env.SAN_CLI_UI_DEV) { // 开发环境
api.registerAddon({
id: 'san.widget.san-cli-ui-widget-hello.client-addon.dev',
url: 'http://localhost:8890/index.js' // 开发环境地址，也即本地服务地址
});
}
else { // 生产环境
api.registerAddon({
id: 'san.widget.san-cli-ui-widget-hello.client-addon', // 唯一id，推荐增加类型前缀'san.widgets'
path: 'san-cli-ui-widget-hello/dist' // 生产环境指向本插件包的编译产出地址
});
}
// 接下来注册widget
api.registerWidget({
id: 'san.san-cli-ui-widget-hello.widget-demo', // 命名不重复即可
title: 'san-cli-ui-widget-hello.title', // locales定义的文案
description: 'san-cli-ui-widget-hello.description',
icon: 'smile', // santd的icon类型
component: 'san.widget.components.widget-demo', // 指定显示的组件id, 值对应src/index.js注册的组件名
// 接下来具体组件的配置信息
minWidth: 2,
minHeight: 2,
maxWidth: 2,
maxHeight: 2,
maxCount: 1
});
};
注意开发环境下的 url http://localhost:8890/index.js
其中端口应与 san.config.js 端口一致
在 src/index.js
中也定义了一个显示在 client 端的组件：
import widgetdemo from './components/widget-demo';
import locales from './locales.json';
/* global ClientAddonApi */
if (window.ClientAddonApi) {
// 扩展语言
ClientAddonApi.addLocales(locales);
// 推荐以类型前缀定义组件的唯一id：'san.widget'
ClientAddonApi.defineComponent('san.widget.components.widget-demo', widgetdemo);
}
其中的 widgetdemo
是按照 san 组件规范定义的一个 san 组件，在 San CLI UI
中扩展了 santd 组件预置，因此可直接使用 santd 组件，无需重复定义，使用方式是：
，例如 santd 的 icon 组件
：
export default {template: `<div class="widget-demo"><div>{{hello}}</div><div>{{$t('san-cli-ui-widget-hello.welcome')}}</div><s-icon type="file" style="font-size: 32px"/></div>`,initData() {return {hello: 'hello san ui widget'};}};
在开发 addon 组件过程中，会涉及到以下 api：
-
api.registerAddon
：addon 组件注册 -
api.registerWidget
：widget 部件注册 -
api.callAction
：事件调用 -
api.onAction
：事件监听 -
ClientAddonApi.defineComponent
：组件定义 -
ClientAddonApi.addLocales
：组件扩展语言
组件实现可参考文档以及已有插件图片压缩插件 (https://github.com/amazing-js/san-cli-ui-widget-tiny-image)
本地调试
1. 启动本地服务
在 san-cli-ui-widget-hello
插件工程中执行 npm start
或在 San CLI UI
启动的界面中，打开 san-cli-ui-widget-hello
工程，点击任务管理 ->start 任务 -> 运行，来启动 start 任务。
2. 修改插件的 ui.js
这步主要是将加载环境置为开发环境，暂时注释掉生产环境的加载条件判断：
module.exports = api => {
// 注册组件加载路径 区分生产环境和开发环境
// if (process.env.SAN_CLI_UI_DEV) { // 开发环境
api.registerAddon({
id: 'san.widget.san-cli-ui-widget-hello.client-addon.dev',
url: 'http://localhost:8890/index.js' // 开发环境地址，也即本地服务地址
});
// }
// else { // 生产环境
// api.registerAddon({
// id: 'san.widget.san-cli-ui-widget-hello.client-addon', // 唯一id，推荐增加类型前缀'san.widgets'
// path: 'san-cli-ui-widget-hello/dist' // 生产环境指向本插件包的编译产出地址
// });
// }
...
};
3. 在调试工程中加入新插件的依赖
现在我们已经有了一个插件工程 san-cli-ui-widget-hello
。
找到一个本地 san 工程用于调试，例如名称为 san-local
，在 san-local
的 package.json 增加插件依赖:
// package.json
{
"name": "san-local",
...
"devDependencies": {
"san-cli-ui-widget-hello": "file:../san-cli-ui-widget-hello",
...
},
"dependencies": {
}
}
注意这里采用的是本地文件的方式。
4. 调试工程内安装插件
在 san-local
工程内执行 npm i
，安装新添加的依赖。
5. 查看效果
依赖安装完成，在 San CLI UI
界面中打开 san-local
工程的仪表盘即可看到效果。
发布安装
san-cli-ui-widget-hello
调试完毕后，恢复 ui.js
内注释的内容，执行 npm run build
+ npm publish
完成包的发布。
在 San CLI UI
的插件管理中搜索到刚发布的插件，安装后即可使用了。
最后
至此我们 San CLI UI
主题已全部完成了，感谢大家的关注，有任何使用问题及建议欢迎提 issue 及 pr
- San CLI github: https://github.com/ecomfe/san-cli
- San CLI 文档: https://ecomfe.github.io/san-cli/#/
参考资料
- Vue CLI UI
- Apollo GraphQL
San 是百度自研的高性能 MVVM 框架，目前已落地百度 APP 核心业务，服务于亿级用户，开源社区已有 36 位贡献者，Star 数量超过 4.3K。开源维护不易，如果你看到这行小字，求给我们一个 Star
- San: https://github.com/baidu/san
- San CLI: https://github.com/ecomfe/san-cli
- San DevTools: https://github.com/baidu/san-devtools
EOF
作者：张婷婷
2021 年 1 月 14 日
About The Author
