Vue CLI UI 插件 API 完全指南:用 cli-ui 扩展项目配置、任务与仪表盘
Vue CLI UI 插件 API 完全指南:用 cli-ui 扩展项目配置、任务与仪表盘
@vue/cli-ui 是 Vue CLI 内置的可视化管理界面(vue ui),它向外暴露了一套完整的 Node.js 插件 API,允许任何 vue-cli 插件通过一个可选的 ui.js 文件来增强、扩展 UI 本身:为项目补充可视化配置面板、为 npm scripts 任务附加参数与钩子、注册自定义页面与仪表盘小组件,并通过共享数据、插件动作、IPC 与本地存储实现浏览器端与 Node.js 服务端的双向通信。本文以官方 UI API 文档为主体,结合本仓库 packages/@vue/cli-ui 与 @vue/cli-shared-utils 的源码实现,系统讲解从加载机制、配置面板、任务增强,到客户端插件、共享数据、插件动作、IPC、建议、小组件的全部 API 用法与底层原理。读完本文,你将能够从零编写一个带完整 UI 能力的 vue-cli 插件。
UI 文件与插件加载机制
约定式入口 ui.js
在每一个已安装的 vue-cli 插件中,cli-ui 都会尝试从插件根目录加载一个可选的 ui.js 文件(也可以使用目录形式,例如 ui/index.js)。这个文件需要导出一个接收 api 对象作为参数的函数:
module.exports = api => {
// 在这里使用 API...
}
从源码看,cli-ui 通过 packages/@vue/cli-ui/apollo-server/connectors/plugins.js 中读取项目 package.json 的依赖与 vuePlugins 字段来定位插件,并为每个插件实例化一个 PluginApi(见 PluginApi.js),随后调用该插件导出的函数完成注册。
⚠️ 重要:这些文件在“项目插件”页面拉取插件列表时会重新加载。 修改 ui.js 后,需要在 UI 左侧导航栏点击「Project plugins」按钮才能让改动生效。
一个使用 UI API 的 vue-cli 插件,其典型目录结构如下:
- vue-cli-plugin-test
- package.json
- index.js
- generator.js
- prompts.js
- ui.js
- logo.png
其中 logo.png 会在未显式指定图标时作为配置/任务的默认图标显示。
项目本地插件(Project local plugins)
如果你只是想在当前项目里使用 UI API,而不想为此创建一个完整插件,可以在项目 package.json 中通过 vuePlugins.ui 选项声明本地 UI 文件:
{
"vuePlugins": {
"ui": ["my-ui.js"]
}
}
每个文件同样需要导出一个接收插件 API 作为第一个参数的函数。plugins.js 中正是通过读取 pkg.vuePlugins.ui 数组逐个加载这些文件的(见 plugins.js)。
开发模式(Dev mode)
开发插件期间,建议以开发模式启动 cli-ui,以便输出有用的调试日志:
vue ui --dev
或使用简写:
vue ui -D
扩展项目配置(describeConfig)
UI 的「Project configuration」面板允许以表单(inquirer prompts)形式编辑项目中的配置文件(如 .eslintrc.js、vue.config.js)。通过 api.describeConfig 即可注册一个配置项。
基础信息
首先传入一些描述性信息:
api.describeConfig({
// 配置的唯一 ID
id: 'org.vue.eslintrc',
// 显示名称
name: 'ESLint configuration',
// 显示在名称下方
description: 'Error checking & Code quality',
// "More info" 链接
link: 'https://eslint.org'
})
::: danger 注意
id 必须在所有插件之间保持全局唯一,建议使用反向域名表示法(reverse domain name notation)来命名空间化,例如 org.vue.eslintrc。
:::
从源码看,describeConfig 的入参还会经过 joi schema 校验(见 configuration.js):id、name 为必填字符串,onRead 与 onWrite 为必填函数,link 必须是合法的 URI;校验失败时错误会写入 UI 日志面板。
配置图标
图标可以是 Material icon 的图标码,也可以是自定义图片(见下文「公共静态文件」):
api.describeConfig({
/* ... */
// 配置图标
icon: 'application_settings'
})
如果未指定图标,则会显示插件自带的 logo(如果有)。
声明配置文件(files)
默认情况下,一个配置 UI 可以读写一个或多个配置文件,例如同时读写 .eslintrc.js 与 vue.config.js。通过 files 字段声明需要在用户项目中检测的候选文件:
api.describeConfig({
/* ... */
// 该配置所有可能的文件
files: {
// eslintrc.js
eslint: {
js: ['.eslintrc.js'],
json: ['.eslintrc', '.eslintrc.json'],
// 将从 `package.json` 中读取
package: 'eslintConfig'
},
// vue.config.js
vue: {
js: ['vue.config.js']
}
},
})
支持的文件类型为:json、yaml、js、package。顺序很重要:当文件不存在时,列表中的第一个文件名将被用来创建配置文件。例如 cli-plugin-eslint 的配置描述中,eslint 键同时给出了 js、json、yaml 三种写法以及 package 字段(见 configDescriptor.js),cli-ui 会在用户项目中按序探测。
展示配置提示(onRead 钩子)
使用 onRead 钩子返回要在配置面板中显示的提示(prompts)列表:
api.describeConfig({
/* ... */
onRead: ({ data, cwd }) => ({
prompts: [
// 提示对象
]
})
})
这些 prompts 会渲染在配置详情面板中。data 对象包含每个配置文件内容的 JSON 解析结果。
例如,用户项目中有如下 vue.config.js:
module.exports = {
lintOnSave: false
}
插件中声明:
api.describeConfig({
/* ... */
// 该配置所有可能的文件
files: {
// vue.config.js
vue: {
js: ['vue.config.js']
}
},
})
那么 data 对象将是:
{
// 文件
vue: {
// 文件数据
lintOnSave: false
}
}
多文件示例:如果用户项目中还有如下 eslintrc.js:
module.exports = {
root: true,
extends: [
'plugin:vue/essential',
'@vue/standard'
]
}
并将 files 改为同时声明 eslint 与 vue 两组:
api.describeConfig({
/* ... */
// 该配置所有可能的文件
files: {
// eslintrc.js
eslint: {
js: ['.eslintrc.js'],
json: ['.eslintrc', '.eslintrc.json'],
// 将从 `package.json` 中读取
package: 'eslintConfig'
},
// vue.config.js
vue: {
js: ['vue.config.js']
}
},
})
则 data 对象为:
{
eslint: {
root: true,
extends: [
'plugin:vue/essential',
'@vue/standard'
]
},
vue: {
lintOnSave: false
}
}
配置标签页(tabs)
可以将 prompts 组织到多个标签页中:
api.describeConfig({
/* ... */
onRead: ({ data, cwd }) => ({
tabs: [
{
id: 'tab1',
label: 'My tab',
// 可选
icon: 'application_settings',
prompts: [
// 提示对象
]
},
{
id: 'tab2',
label: 'My other tab',
prompts: [
// 提示对象
]
}
]
})
})
这正是 cli-plugin-eslint 的做法:它把配置拆分为 general(通用)与 rules(规则)两个标签页(见 configDescriptor.js)。
保存配置修改(onWrite 钩子)
使用 onWrite 钩子把数据写回配置文件(或执行任意 Node.js 代码):
api.describeConfig({
/* ... */
onWrite: ({ prompts, answers, data, files, cwd, api }) => {
// ...
}
})
各参数含义:
prompts:当前提示的运行时对象(见下方)answers:用户输入产生的回答数据data:从配置文件读取到的只读初始数据files:找到的文件的描述符(形如{ type: 'json', path: '...' })cwd:当前工作目录api:onWriteAPI(见下方)
prompts 运行时对象结构:
{
id: data.name,
type: data.type,
name: data.short || null,
message: data.message,
group: data.group || null,
description: data.description || null,
link: data.link || null,
choices: null,
visible: true,
enabled: true,
// 当前值(未经过滤)
value: null,
// 用户是否修改过
valueChanged: false,
error: null,
tabId: null,
// 原始 inquirer 提示对象
raw: data
}
onWrite API 提供三个方法:
assignData(fileId, newData):写入前使用Object.assign更新配置数据。setData(fileId, newData):写入前将newData的每个键深度设置到配置数据中(值为undefined时删除该键)。async getAnswer(id, mapper):获取指定 id 提示的回答,若提供了mapper函数则先经其处理(例如JSON.parse)。
示例(来自 ESLint 插件):
api.describeConfig({
// ...
onWrite: async ({ api, prompts }) => {
// 更新 ESLint 规则
const result = {}
for (const prompt of prompts) {
result[`rules.${prompt.id}`] = await api.getAnswer(prompt.id, JSON.parse)
}
api.setData('eslint', result)
}
})
完整的 onWrite 实现可以参考 configDescriptor.js:它针对 config 提示重写 eslint.extends,针对 vue/* 前缀的提示写入 rules.xxx 键,其余提示则写入 vue.config.js 数据,最后分别调用 api.setData('eslint', ...) 与 api.setData('vue', ...) 提交。
扩展项目任务(describeTask / addTask)
「Project tasks」面板中的任务由项目 package.json 的 scripts 字段自动生成。通过 api.describeTask 可以为既有任务附加额外信息与钩子:
api.describeTask({
// 对脚本命令执行的正则,用于选中要描述的任务
match: /vue-cli-service serve/,
description: 'Compiles and hot-reloads for development',
// "More info" 链接
link: 'https://github.com/vuejs/vue-cli/blob/dev/docs/cli-service.md#serve'
})
match 也可以是一个函数:
api.describeTask({
match: (command) => /vue-cli-service serve/.test(command),
})
从源码看,PluginApi.getDescribedTask(command) 正是对每个已注册描述执行“函数则调用、正则则 .test()”的匹配逻辑(见 PluginApi.js),而 describeTask 的 schema 要求 match 必须是 RegExp 实例或函数(见 task.js)。
任务图标
与配置图标相同,可以是 Material 图标码或自定义图片:
api.describeTask({
/* ... */
// 任务图标
icon: 'application_settings'
})
未指定时显示插件 logo。
任务参数(prompts)
可以添加 prompts 来修改命令参数,它们会显示在「Parameters」模态框中:
api.describeTask({
// ...
// 可选参数(inquirer prompts)
prompts: [
{
name: 'open',
type: 'confirm',
default: false,
description: 'Open browser on server start'
},
{
name: 'mode',
type: 'list',
default: 'development',
choices: [
{
name: 'development',
value: 'development'
},
{
name: 'production',
value: 'production'
},
{
name: 'test',
value: 'test'
}
],
description: 'Specify env mode'
}
]
})
任务钩子(Hooks)
任务有三个可用钩子:onBeforeRun、onRun、onExit。例如,利用用户对 prompts 的回答为命令追加参数:
api.describeTask({
// ...
// 钩子
// 在这里修改参数
onBeforeRun: async ({ answers, args }) => {
// 参数
if (answers.open) args.push('--open')
if (answers.mode) args.push('--mode', answers.mode)
args.push('--dashboard')
},
// 任务启动后立即执行
onRun: async ({ args, child, cwd }) => {
// child: node 子进程
// cwd: 进程工作目录
},
onExit: async ({ args, child, cwd, code, signal }) => {
// code: 退出码
// signal: 使用的 kill 信号(如果有)
}
})
注意上面 args.push('--dashboard') 的用法:@vue/cli-service 的 serve/build 命令在收到 --dashboard 参数后,会通过 IPC 把 webpack 构建统计推送给 cli-ui,从而在 Dashboard 视图中呈现实时构建信息——这正是下面「IPC」一节的典型应用。
任务视图(views)
通过 ClientAddon API 可以在任务详情面板中显示自定义视图:
api.describeTask({
// ...
// 附加视图(例如 webpack 仪表盘)
// 默认存在一个显示终端输出的 'output' 视图
views: [
{
// 唯一 ID
id: 'vue-webpack-dashboard-client-addon',
// 按钮文本
label: 'Dashboard',
// 按钮图标
icon: 'dashboard',
// 要加载的动态组件(见下文「客户端插件」)
component: 'vue-webpack-dashboard'
}
],
// 展示任务详情时的默认选中视图(默认是 output)
defaultView: 'vue-webpack-dashboard-client-addon'
})
views 数组中的每一项都要求 id、label、component 必填(见 task.js)。
添加全新任务(addTask)
api.describeTask 只能增强 package.json 中已存在的 scripts;如果想添加一个不在 scripts 中、仅存在于 UI 的全新任务,则使用 api.addTask:
必须提供 command 选项而不是 match。
api.addTask({
// 必填
name: 'inspect',
command: 'vue-cli-service inspect',
// 可选
// 其余选项与 `describeTask` 相同(去掉 `match`)
description: '...',
link: 'https://github.com/vuejs/vue-cli/...',
prompts: [ /* ... */ ],
onBeforeRun: () => {},
onRun: () => {},
onExit: () => {},
views: [ /* ... */ ],
defaultView: '...'
})
⚠️ command 会在 Node 上下文中运行,这意味着你可以像在 package.json scripts 中那样直接调用 node bin 命令。addTask 的 schema 要求 name 与 command 必填(见 task.js)。
交互式提示(Prompts)
提示对象必须是合法的 inquirer 对象。除此之外,你还可以添加以下仅供 UI 使用的可选附加字段:
{
/* ... */
// 用于将提示分组到不同区块
group: 'Strongly recommended',
// 附加描述
description: 'Enforce attribute naming style in template (`my-prop` or `myProp`)',
// "More info" 链接
link: 'https://github.com/vuejs/eslint-plugin-vue/blob/master/docs/rules/attribute-hyphenation.md',
}
支持的 inquirer 类型:checkbox、confirm、input、password、list、rawlist、editor。
此外 UI 还支持一个仅 UI 可用的特殊类型:
color:显示颜色选择器。
开关(Switch)示例
{
name: 'open',
type: 'confirm',
default: false,
description: 'Open the app in the browser'
}
下拉选择(Select)示例
{
name: 'mode',
type: 'list',
default: 'development',
choices: [
{
name: 'Development mode',
value: 'development'
},
{
name: 'Production mode',
value: 'production'
},
{
name: 'Test mode',
value: 'test'
}
],
description: 'Build mode',
link: 'https://link-to-docs'
}
输入框(Input)示例
{
name: 'host',
type: 'input',
default: '0.0.0.0',
description: 'Host for the development server'
}
复选框(Checkbox)示例
显示多个开关:
{
name: 'lintOn',
message: 'Pick additional lint features:',
when: answers => answers.features.includes('linter'),
type: 'checkbox',
choices: [
{
name: 'Lint on save',
value: 'save',
checked: true
},
{
name: 'Lint and fix on commit' + (hasGit() ? '' : chalk.red(' (requires Git)')),
value: 'commit'
}
]
}
注意 when 字段是标准 inquirer 的条件函数,可根据已有回答动态决定是否显示该提示;chalk.red(...) 则用于在 UI 中渲染红色提示文本。
颜色选择器(Color picker)示例
{
name: 'themeColor',
type: 'color',
message: 'Theme color',
description: 'This is used to change the system UI color around the app',
default: '#4DBA87'
}
安装时提示(prompts.js)的复用
vue-cli 插件通常已有 prompts.js 文件,在插件安装时(CLI 或 UI)向用户提问。你可以直接给这些提示对象添加上述仅 UI 使用的附加字段,这样用户在使用 UI 安装时就能获得更丰富的信息。
⚠️ 目前,上述不支持的 inquirer 类型在 UI 中无法正常工作。
客户端插件(Client Addon)
客户端插件(Client Addon)是一段动态加载进 cli-ui 的 JS bundle,用于加载自定义组件与 vue-router 路由。它运行在浏览器端,是打通“UI 可视化扩展”与“Node.js 插件逻辑”的关键桥梁。
创建客户端插件
推荐的方式是使用 Vue CLI 新建一个项目(可以放在插件包的子目录,也可以是一个独立的 npm 包),并将 @vue/cli-ui 安装为开发依赖。
然后添加 vue.config.js:
const { clientAddonConfig } = require('@vue/cli-ui')
module.exports = {
...clientAddonConfig({
id: 'org.vue.webpack.client-addon',
// 开发端口(默认 8042)
port: 8042
})
}
clientAddonConfig 会生成所需的 vue-cli 配置。从源码看,它会:在生产环境把 publicPath 设为 /_addon/<id>、开发环境指向 http://localhost:<port>/;强制输出文件名为 index.js;关闭 CSS 提取;删除 preload/prefetch/html 等插件并禁用代码分割(见 index.js)。即构建产物最终输出到客户端插件目录下的 ./dist/index.js。
::: danger 注意
id 必须全局唯一,建议使用反向域名表示法命名空间化。
:::
然后修改 .eslintrc.json,加入以下允许的全局对象:
{
// ...
"globals": {
"ClientAddonApi": false,
"mapSharedData": false,
"Vue": false
}
}
开发时运行 serve 脚本,准备发布插件时运行 build 脚本。本仓库的 webpack 客户端插件即采用这一模式,见 cli-ui-addon-webpack/vue.config.js。
ClientAddonApi
打开客户端插件源码中的 main.js 并清空原有代码。
⚠️ 不要在客户端插件源码中 import Vue,请使用浏览器 window 上的全局 Vue 对象。
main.js 示例:
import VueProgress from 'vue-progress-path'
import WebpackDashboard from './components/WebpackDashboard.vue'
import TestView from './components/TestView.vue'
// 可以使用全局 'Vue' 变量安装额外的 Vue 插件
Vue.use(VueProgress, {
defaultShape: 'circle'
})
// 注册自定义组件
// (用法类似 'Vue.component')
ClientAddonApi.component('org.vue.webpack.components.dashboard', WebpackDashboard)
// 向 vue-router 添加路由,父路由为 /addon/<id>。
// 例如 addRoutes('foo', [ { path: '' }, { path: 'bar' } ])
// 会向 vue-router 添加 /addon/foo/ 与 /addon/foo/bar 两个路由。
// 这里我们创建了一个名为 'test-webpack-route' 的新路由 '/addon/vue-webpack/'
ClientAddonApi.addRoutes('org.vue.webpack', [
{ path: '', name: 'org.vue.webpack.routes.test', component: TestView }
])
// 你可以翻译插件组件
// 加载本地化文件(使用 vue-i18n)
const locales = require.context('./locales', true, /[a-z0-9]+\.json$/i)
locales.keys().forEach(key => {
const locale = key.match(/([a-z0-9]+)\./i)[1]
ClientAddonApi.addLocalization(locale, locales(key))
})
::: danger 注意 所有 id 都必须全局唯一,建议使用反向域名表示法命名空间化。 :::
cli-ui 会在 window 全局作用域注册 Vue 与 ClientAddonApi 两个全局变量。在你的组件中,可以使用 @vue/ui 与 @vue/cli-ui 提供的全部组件与 CSS 类以保持视觉一致,并借助内置的 vue-i18n 翻译文本。
注册客户端插件
回到 ui.js,使用 api.addClientAddon 并传入指向构建产物的 require 查询:
api.addClientAddon({
id: 'org.vue.webpack.client-addon',
// 存放构建后 JS 文件的目录
path: '@vue/cli-ui-addon-webpack/dist'
})
这将通过 Node.js 的 require.resolve API 定位目录,并对外提供由客户端插件构建出的 index.js 文件。注意 addClientAddon 的 url 与 path 不能同时定义(见 PluginApi.js)。
开发插件时也可以直接指定 URL(理想情况下应放在测试 vue 项目中的 vue-cli-ui.js 文件里):
// 开发时很有用
// 如果插件中已定义 path,这里会覆盖它
api.addClientAddon({
id: 'org.vue.webpack.client-addon',
// 使用之前配置的相同端口
url: 'http://localhost:8042/index.js'
})
使用客户端插件
现在可以在视图中使用客户端插件了。例如,在任务描述中指定一个视图:
api.describeTask({
/* ... */
// 附加视图(例如 webpack 仪表盘)
// 默认存在一个显示终端输出的 'output' 视图
views: [
{
// 唯一 ID
id: 'org.vue.webpack.views.dashboard',
// 按钮文本
label: 'Dashboard',
// 按钮图标(material-icons)
icon: 'dashboard',
// 动态组件:通过 ClientAddonApi 注册
component: 'org.vue.webpack.components.dashboard'
}
],
// 展示任务详情时的默认视图(默认是 output)
defaultView: 'org.vue.webpack.views.dashboard'
})
以下是在客户端插件中注册 'org.vue.webpack.components.dashboard' 组件的代码(如前面所见):
/* 在 `main.js` 中 */
// 导入组件
import WebpackDashboard from './components/WebpackDashboard.vue'
// 注册自定义组件
// (用法类似 'Vue.component')
ClientAddonApi.component('org.vue.webpack.components.dashboard', WebpackDashboard)
自定义页面(addView)
除了内置的「Project plugins」「Project configuration」「Project tasks」之外,还可以用 api.addView 添加全新的项目页面:
api.addView({
// 唯一 id
id: 'org.vue.webpack.views.test',
// 路由名称(来自 vue-router)
// 使用与 'ClientAddonApi.addRoutes' 方法相同的名称(见上文「客户端插件」)
name: 'org.vue.webpack.routes.test',
// 按钮图标(material-icons)
icon: 'pets',
// 也可以指定自定义图片(见下文「公共静态文件」):
// icon: 'http://localhost:4000/_plugin/%40vue%2Fcli-service/webpack-icon.svg',
// 按钮提示
tooltip: 'Test view from webpack addon'
})
客户端插件中注册 'org.vue.webpack.routes.test' 路由的代码(如前面所见):
/* 在 `main.js` 中 */
// 导入组件
import TestView from './components/TestView.vue'
// 向 vue-router 添加路由,父路由为 /addon/<id>。
// 例如 addRoutes('foo', [ { path: '' }, { path: 'bar' } ])
// 会添加 /addon/foo/ 与 /addon/foo/bar 两个路由。
// 这里创建了新路由 '/addon/vue-webpack/',名称为 'test-webpack-route'
ClientAddonApi.addRoutes('org.vue.webpack', [
{ path: '', name: 'org.vue.webpack.routes.test', component: TestView }
])
共享数据(Shared Data)
共享数据(Shared Data)用于在 UI 客户端与自定义组件之间便捷地传递信息。
例如,webpack 仪表盘就是通过该 API 在 UI 客户端与 UI 服务端之间共享构建统计数据。
服务端(ui.js,Node.js)
// 设置或更新
api.setSharedData('com.my-name.my-variable', 'some-data')
// 获取
const sharedData = api.getSharedData('com.my-name.my-variable')
if (sharedData) {
console.log(sharedData.value)
}
// 删除
api.removeSharedData('com.my-name.my-variable')
// 监听变化
const watcher = (value, id) => {
console.log(value, id)
}
api.watchSharedData('com.my-name.my-variable', watcher)
// 取消监听
api.unwatchSharedData('com.my-name.my-variable', watcher)
// 命名空间版本
const {
setSharedData,
getSharedData,
removeSharedData,
watchSharedData,
unwatchSharedData
} = api.namespace('com.my-name.')
::: danger 注意 id 必须全局唯一,建议使用反向域名表示法命名空间化。 :::
从源码看,setSharedData 还可以传入第三个参数 { disk: true } 将数据持久化到磁盘而非仅存内存(见 PluginApi.js);数据最终按 { id, projectId } 维度存取于 shared-data connector 中。
客户端组件(浏览器)
// Vue 组件
export default {
// 同步共享数据
sharedData () {
return {
// 可以在模板中使用 `myVariable`
myVariable: 'com.my-name.my-variable'
// 也可以映射命名空间的共享数据
...mapSharedData('com.my-name.', {
myVariable2: 'my-variable2'
})
}
},
// 手动方法
async created () {
const value = await this.$getSharedData('com.my-name.my-variable')
this.$watchSharedData(`com.my-name.my-variable`, value => {
console.log(value)
})
await this.$setSharedData('com.my-name.my-variable', 'new-value')
}
}
如果使用 sharedData 选项,可以通过给对应属性赋新值来更新共享数据:
<template>
<VueInput v-model="message"/>
</template>
<script>
export default {
sharedData: {
// 将同步服务端 'my-message' 共享数据
message: 'com.my-name.my-message'
}
}
</script>
这对于创建设置类组件非常有用——表单的双向绑定直接映射到服务端共享数据,无需手动同步。
插件动作(Plugin Actions)
插件动作是 cli-ui(浏览器)与插件(Node.js)之间的调用通道。
例如,自定义组件(见「客户端插件」)中可能有一个按钮,通过该 API 调用服务端 Node.js 代码。
服务端(ui.js)
PluginApi 提供两个方法:
// 调用一个动作
api.callAction('com.my-name.other-action', { foo: 'bar' }).then(results => {
console.log(results)
}).catch(errors => {
console.error(errors)
})
// 监听一个动作
api.onAction('com.my-name.test-action', params => {
console.log('test-action called', params)
})
::: danger 注意 id 必须全局唯一,建议使用反向域名表示法命名空间化。 :::
可以用 api.namespace 获取命名空间版本(与共享数据类似):
const { onAction, callAction } = api.namespace('com.my-name.')
从源码看,onAction 把回调按 id 存入 this.actions 这个 Map(见 PluginApi.js),callAction 则委托给 plugins.callAction 执行并返回 Promise(见 PluginApi.js);namespace() 会为所有相关方法统一加上命名空间前缀(见 PluginApi.js)。
客户端组件(浏览器)
客户端插件组件中可以访问 $onPluginActionCalled、$onPluginActionResolved 与 $callPluginAction:
// Vue 组件
export default {
created () {
this.$onPluginActionCalled(action => {
// 动作被调用时
// (在动作执行之前)
console.log('called', action)
})
this.$onPluginActionResolved(action => {
// 动作执行并完成后
console.log('resolved', action)
})
},
methods: {
testPluginAction () {
// 调用插件动作
this.$callPluginAction('com.my-name.test-action', {
meow: 'meow'
})
}
}
}
进程间通信(IPC)
IPC(Inter-Process Communication)系统让你可以轻松地从子进程(例如任务!)向 cli-ui 服务端发送消息,且速度很快、开销很低。
为了在 webpack 仪表盘 UI 中展示数据,
@vue/cli-service的serve和build命令在收到--dashboard参数时,会向 cli-ui 的 Node.js 服务端发送 IPC 消息。
在子进程中使用 IpcMessenger
在进程代码中(可以是 Webpack 插件或 Node.js 任务脚本),使用 @vue/cli-shared-utils 导出的 IpcMessenger 类:
const { IpcMessenger } = require('@vue/cli-shared-utils')
// 创建新的 IpcMessenger 实例
const ipc = new IpcMessenger()
function sendMessage (data) {
// 向 cli-ui 服务端发送消息
ipc.send({
'com.my-name.some-data': {
type: 'build',
value: data
}
})
}
function messageHandler (data) {
console.log(data)
}
// 监听消息
ipc.on(messageHandler)
// 不再监听
ipc.off(messageHandler)
function cleanup () {
// 从 IPC 网络断开
ipc.disconnect()
}
从源码看,IpcMessenger 的默认选项为 { networkId: process.env.VUE_CLI_IPC || 'vue-cli', autoConnect: true, disconnectOnIdle: false, idleTimeout: 3000, namespaceOnProject: true }(见 ipc.js)。当 namespaceOnProject 为 true 且设置了 VUE_CLI_PROJECT_ID 环境变量时,send 会把消息包装为 { _projectId, _data } 结构,接收方只处理属于当前项目的消息——这正是多项目并存时消息不会串台的保证(见 ipc.js)。
手动连接(autoConnect: false 时消息会先入队):
const ipc = new IpcMessenger({
autoConnect: false
})
// 该消息将被加入队列
ipc.send({ ... })
ipc.connect()
空闲自动断开(一段时间不发送消息后自动断开):
const ipc = new IpcMessenger({
disconnectOnIdle: true,
idleTimeout: 3000 // 默认值
})
ipc.send({ ... })
setTimeout(() => {
console.log(ipc.connected) // false
}, 3000)
连接到另一个 IPC 网络(隔离消息域):
const ipc = new IpcMessenger({
networkId: 'com.my-name.my-ipc-network'
})
在 ui.js 中收发 IPC 消息
在 vue-cli 插件的 ui.js 中,可以使用 ipcOn、ipcOff 与 ipcSend 方法:
function onWebpackMessage ({ data: message }) {
if (message['com.my-name.some-data']) {
console.log(message['com.my-name.some-data'])
}
}
// 监听任意 IPC 消息
api.ipcOn(onWebpackMessage)
// 不再监听
api.ipcOff(onWebpackMessage)
// 向所有已连接的 IpcMessenger 实例发送消息
api.ipcSend({
webpackDashboardMessage: {
foo: 'bar'
}
})
从源码看,ipcOn 注册的回调会被包装:若消息带 _projectId 且与当前项目匹配,则解包出 _data 后再传给回调;ipcSend 则直接委托给 UI 服务端的 IPC 广播(见 PluginApi.js)。服务端侧的消息入口与 ack 应答逻辑见 util/ipc.js。
本地存储、通知与进度屏
本地存储(Local storage)
插件可以在 UI 服务端使用的本地 lowdb 数据库中存取数据:
// 将值存入本地数据库
api.storageSet('com.my-name.an-id', { some: 'value' })
// 从本地数据库读取值
console.log(api.storageGet('com.my-name.an-id'))
// 完整的 lowdb 实例
api.db.get('posts')
.find({ title: 'low!' })
.assign({ title: 'hi!'})
.write()
// 命名空间助手
const { storageGet, storageSet } = api.namespace('my-plugin.')
::: danger 注意 id 必须全局唯一,建议使用反向域名表示法命名空间化。 :::
storageGet/storageSet 的实现即 this.db.get(id).value() 与 this.db.set(id, value).write()(见 PluginApi.js),存储值必须是可 JSON 序列化的。
通知(Notification)
可以通过操作系统的通知系统显示通知:
api.notify({
title: 'Some title',
message: 'Some message',
icon: 'path-to-icon.png'
})
内置图标有:
'done''error'
进度屏(Progress screen)
可以显示带文本与进度条的进度屏:
api.setProgress({
status: 'Upgrading...',
error: null,
info: 'Step 2 of 4',
progress: 0.4 // 0 到 1,-1 表示隐藏进度条
})
移除进度屏:
api.removeProgress()
从源码看,进度屏使用固定的内部 id '__plugins__'(见 PluginApi.js),即所有插件共享同一块进度展示区域。
生命周期钩子(Hooks)
钩子允许你对 cli-ui 中的特定事件做出反应。它们全部注册在 PluginApi 构造函数的 this.hooks 中(见 PluginApi.js),并在相应 connector 中触发。
onProjectOpen
插件首次为当前项目加载时调用:
api.onProjectOpen((project, previousProject) => {
// 重置数据
})
onPluginReload
插件被重新加载时调用:
api.onPluginReload((project) => {
console.log('plugin reloaded')
})
onConfigRead
配置面板打开或刷新时调用:
api.onConfigRead(({ config, data, onReadData, tabs, cwd }) => {
console.log(config.id)
})
onConfigWrite
用户在配置面板中保存时调用:
api.onConfigWrite(({ config, data, changedFields, cwd }) => {
// ...
})
onTaskOpen
用户打开任务详情面板时调用:
api.onTaskOpen(({ task, cwd }) => {
console.log(task.id)
})
onTaskRun
用户运行任务时调用:
api.onTaskRun(({ task, args, child, cwd }) => {
// ...
})
onTaskExit
任务退出时调用(成功或失败都会触发):
api.onTaskExit(({ task, args, child, signal, code, cwd }) => {
// ...
})
onViewOpen
用户打开某个视图(如「Plugins」「Configurations」或「Tasks」)时调用:
api.onViewOpen(({ view, cwd }) => {
console.log(view.id)
})
建议(Suggestions)
建议(Suggestions)是显示在顶部栏、用于向用户提议操作的按钮。例如,当检测到项目未安装 vue-router 时,显示一个建议安装的按钮:
api.addSuggestion({
id: 'com.my-name.my-suggestion',
type: 'action', // 必填(未来会有更多类型)
label: 'Add vue-router',
// 将显示在详情模态框中
message: 'A longer message for the modal',
link: 'http://link-to-docs-in-the-modal',
// 可选图片
image: '/_plugin/my-package/screenshot.png',
// 用户激活建议时调用的函数
async handler () {
// ...
return {
// 默认会移除按钮
keep: false
}
}
})
::: danger 注意 id 必须全局唯一,建议使用反向域名表示法命名空间化。 :::
然后可以移除建议:
api.removeSuggestion('com.my-name.my-suggestion')
也可以用 actionLink 在用户激活建议时直接打开一个页面:
api.addSuggestion({
id: 'com.my-name.my-suggestion',
type: 'action', // 必填
label: 'Add vue-router',
// 打开新标签页
actionLink: 'https://vuejs.org/'
})
通常,你会结合钩子在正确的上下文显示建议:
const ROUTER = 'vue-router-add'
api.onViewOpen(({ view }) => {
if (view.id === 'vue-project-plugins') {
if (!api.hasPlugin('router')) {
api.addSuggestion({
id: ROUTER,
type: 'action',
label: 'org.vue.cli-service.suggestions.vue-router-add.label',
message: 'org.vue.cli-service.suggestions.vue-router-add.message',
link: 'https://router.vuejs.org/',
async handler () {
await install(api, 'router')
}
})
}
} else {
api.removeSuggestion(ROUTER)
}
})
在这个示例中,只有当视图为插件页且项目尚未安装 vue-router 时,才显示 vue-router 建议。注意:addSuggestion 和 removeSuggestion 可以通过 api.namespace() 进行命名空间化。类似的真实实现可参考 cli-plugin-eslint/ui/index.js:它利用 onViewOpen/onConfigRead 钩子,在打开 ESLint 配置面板时添加「打开 .eslintrc 文件」的建议,离开时移除。
仪表盘小组件(Widgets)
你可以在插件 ui 文件中为项目仪表盘注册小组件:
registerWidget({
// 唯一 ID
id: 'org.vue.widgets.news',
// 基本信息
title: 'org.vue.widgets.news.title',
description: 'org.vue.widgets.news.description',
icon: 'rss_feed',
// 渲染小组件的主组件
component: 'org.vue.widgets.components.news',
// (可选)小组件 'fullscreen' 视图的次级组件
detailsComponent: 'org.vue.widgets.components.news',
// 尺寸
minWidth: 2,
minHeight: 1,
maxWidth: 6,
maxHeight: 6,
defaultWidth: 2,
defaultHeight: 3,
// (可选)限制仪表盘上该小组件的最大数量
maxCount: 1,
// (可选)在小组件头部添加 'fullscreen' 按钮
openDetailsButton: true,
// (可选)小组件默认配置
defaultConfig: () => ({
url: 'https://vuenews.fireside.fm/rss'
}),
// (可选)要求用户在添加小组件时进行配置
// 注意不要与 `defaultConfig` 同时使用
needsUserConfig: true,
// (可选)展示用于配置小组件的 prompts
onConfigOpen: async ({ context }) => {
return {
prompts: [
{
name: 'url',
type: 'input',
message: 'org.vue.widgets.news.prompts.url',
validate: input => !!input // 必填
}
]
}
}
})
注意:registerWidget 可以通过 api.namespace() 命名空间化(此时 id 会被自动加上前缀,见 PluginApi.js)。
其他方法
hasPlugin
返回项目是否使用了指定插件(支持短名称匹配):
api.hasPlugin('eslint')
api.hasPlugin('apollo')
api.hasPlugin('vue-cli-plugin-apollo')
底层通过 @vue/cli-shared-utils 的 matchesPluginId 进行匹配(见 PluginApi.js)。
getCwd
获取当前工作目录:
api.getCwd()
resolve
解析当前项目内的文件(基于 cwd 的绝对路径):
api.resolve('src/main.js')
getProject
获取当前打开的项目对象:
api.getProject()
requestRoute
在 Web 客户端将用户切换到指定路由:
api.requestRoute({
name: 'foo',
params: {
id: 'bar'
}
})
api.requestRoute('/foobar')
公共静态文件(Public static files)
你可能需要通过 cli-ui 内置的 HTTP 服务器暴露一些静态文件(典型场景是为自定义视图指定图标)。
插件包根目录下可选的 ui-public 文件夹中的任何文件,都会暴露到 /_plugin/:id/* 这个 HTTP 路由下。
例如,把 my-logo.png 放入 vue-cli-plugin-hello/ui-public/ 文件夹,当 cli-ui 加载该插件后,就可以通过 URL /_plugin/vue-cli-plugin-hello/my-logo.png 访问它:
api.describeConfig({
/* ... */
// 自定义图片
icon: '/_plugin/vue-cli-plugin-hello/my-logo.png'
})
综合实战:组装一个完整的插件 ui.js
把本文介绍的 API 组合起来,一个完整的、具备配置面板、任务增强、自定义页面与建议能力的插件 ui.js 大致如下:
module.exports = api => {
// 1. 注册配置面板:读写 vue.config.js
api.describeConfig({
id: 'org.example.vue',
name: 'Vue configuration',
description: 'Vue CLI project configuration',
icon: 'application_settings',
files: {
vue: { js: ['vue.config.js'] }
},
onRead: ({ data }) => ({
tabs: [
{
id: 'general',
label: 'General',
prompts: [
{
name: 'lintOnSave',
type: 'confirm',
default: true,
description: 'Lint on save',
value: data.vue && data.vue.lintOnSave
}
]
}
]
}),
onWrite: async ({ api, prompts }) => {
const vueData = {}
for (const prompt of prompts) {
vueData[prompt.id] = await api.getAnswer(prompt.id)
}
api.setData('vue', vueData)
}
})
// 2. 增强 serve 任务:追加 --open / --mode 参数并开启 dashboard
api.describeTask({
match: /vue-cli-service serve/,
description: 'Compiles and hot-reloads for development',
prompts: [
{
name: 'open',
type: 'confirm',
default: false,
description: 'Open browser on server start'
}
],
onBeforeRun: async ({ answers, args }) => {
if (answers.open) args.push('--open')
args.push('--dashboard')
}
})
// 3. 注册一个全新的仅 UI 任务
api.addTask({
name: 'inspect',
command: 'vue-cli-service inspect'
})
// 4. 注册客户端插件(自定义组件与路由)
api.addClientAddon({
id: 'org.example.client-addon',
path: 'vue-cli-plugin-example/dist'
})
// 5. 添加自定义页面
api.addView({
id: 'org.example.views.home',
name: 'org.example.routes.home',
icon: 'home',
tooltip: 'Example view'
})
// 6. 共享数据 + 插件动作
api.setSharedData('org.example.count', 0)
api.onAction('org.example.increment', params => {
api.setSharedData('org.example.count', params.amount)
})
// 7. 在插件页面按需显示建议
api.onViewOpen(({ view }) => {
if (view.id === 'vue-project-plugins') {
api.addSuggestion({
id: 'org.example.suggestion',
type: 'action',
label: 'Open docs',
actionLink: 'https://example-docs.local/'
})
} else {
api.removeSuggestion('org.example.suggestion')
}
})
}
参考资料(仓库内)
- UI API 的核心实现:
packages/@vue/cli-ui/apollo-server/api/PluginApi.js、packages/@vue/cli-ui/apollo-server/api/configuration.js、packages/@vue/cli-ui/apollo-server/api/task.js、packages/@vue/cli-ui/apollo-server/api/client-addon.js clientAddonConfig生成器:packages/@vue/cli-ui/index.js- IPC 客户端类:
packages/@vue/cli-shared-utils/lib/ipc.js;IPC 服务端:packages/@vue/cli-ui/apollo-server/util/ipc.js - 生产级示例插件:
packages/@vue/cli-plugin-eslint/ui/index.js、packages/@vue/cli-plugin-eslint/ui/configDescriptor.js、packages/@vue/cli-plugin-eslint/ui/taskDescriptor.js - 客户端插件示例:
packages/@vue/cli-ui-addon-webpack/(含vue.config.js、src/main.js) - 相关说明文档:ui-info.md、ui-localization.md、plugin-dev.md



