Vue CLI UI 插件 API 完全指南:用 cli-ui 扩展项目配置、任务与仪表盘

原创2026-09-18 19:21:251,846 阅读
文章标签:前端开发工具构建工具

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 插件。

Vue CLI UI 插件架构图

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:onWrite API(见下方)

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 必须全局唯一,建议使用反向域名表示法命名空间化。 :::

UI 建议示例

然后可以移除建议:

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
登录后查看全文
vue-cli