第一个最小插件

本文用一个最小案例带你完成第一个 BPMAX 插件。目标不是做复杂业务，而是尽快跑通“创建插件 -> 注册前端入口 -> 在系统中看到页面”。

学习目标

学会从已有插件复制出一个新插件
学会修改基础配置
学会注册一个可访问的前端页面

最终效果

完成后，你将得到一个最小插件，它至少具备：

独立的插件目录
基础配置文件
一个前端入口文件
一个通过路由访问的测试页面

第一步：创建插件

使用脚手架复制已有插件

推荐直接使用插件工程中提供的创建脚手架。

命令格式：

node create_plugin.js --name={pluginName} --from={copyFrom}

例如：

node create_plugin.js --name=plugin_hello_demo --from=template_plugin

这个脚手架会自动完成几件事：

创建新目录
复制源插件文件
修改 config.json 中的 en_name
替换文件内容中的旧插件名
重命名包含旧插件名的文件

选择合适的复制源

对于最小插件，建议选结构简单、依赖少的模板作为起点。选择标准是：

前端入口简单
路由注册直观
后端依赖少

修改插件英文名和展示信息

创建完成后，优先检查 config.json，确认以下内容已经正确：

en_name
name
description
version

其中 en_name 必须保持唯一，并尽量与插件目录保持一致。

第二步：认识最小目录结构

最小插件可以先收敛成下面这个结构：

plugin_hello_demo/
├── config.json
├── frontend/
│   ├── src/
│   │   ├── main.ts
│   │   └── HelloPage.vue
└── server/
    └── src/
        └── controller/

`config.json`

这是插件元信息入口。平台安装、展示和记录插件时都依赖这个文件。

一个最小可用示例如下：

{
  "name": "Hello Demo",
  "en_name": "plugin_hello_demo",
  "version": "1.0.0",
  "description": "最小插件示例"
}

前端入口文件

这是最核心的前端入口。最小插件通常只做一件事：注册一个路由。

一个最小入口示例如下：

import HelloPage from './HelloPage.vue';

BPMAX.router.addRoute({
  path: '/plugin/hello-demo',
  component: HelloPage,
});

`server/` 是否必须存在

如果只是做一个最小前端页面型插件，后端不是必须一开始就写复杂逻辑。

但从工程完整性考虑，仍建议保留 server/ 结构，方便后续扩展接口、服务和安装脚本。

第三步：注册一个前端页面

创建页面组件

先在插件前端目录中创建一个最简单的页面组件，例如：

<template>
  <section class="hello-plugin-page">
    <h2>Hello BPMAX Plugin</h2>
    <p>这是我的第一个插件页面。</p>
    <p>如果你能看到这段内容，说明插件前端入口已经生效。</p>
  </section>
</template>

<style scoped>
.hello-plugin-page {
  padding: 24px;
}
</style>

如果想顺手验证平台能力是否已注入，可以再补一个按钮：

<script setup lang="ts">
const openHome = () => {
  BPMAX.router.push('/');
};
</script>

<template>
  <section class="hello-plugin-page">
    <h2>Hello BPMAX Plugin</h2>
    <button @click="openHome">返回首页</button>
  </section>
</template>

完整入口文件示例

把页面、日志和路由放在一起后，main.ts 可以先写成：

import HelloPage from './HelloPage.vue';

console.log('plugin_hello_demo loaded');

BPMAX.router.addRoute({
  path: '/plugin/hello-demo',
  component: HelloPage,
});

这个版本足够验证三件事：

插件前端入口是否执行
页面组件是否参与构建
路由是否已成功注册

这个页面不依赖特定平台能力，目的是先确认插件入口和路由链路正确。

在入口文件中注册路由

在入口文件中引入页面并注册：

import HelloPage from './HelloPage.vue';

BPMAX.router.addRoute({
  path: '/plugin/hello-demo',
  component: HelloPage,
});

路径建议：

统一放在 /plugin/ 前缀下
路径名与插件英文名相关
不要与平台现有页面冲突

访问页面验证生效

本地运行环境启动后，直接访问你注册的路径，例如：

/plugin/hello-demo

如果页面成功显示，说明最小插件已经跑通。

第四步：验证加载结果

页面能访问

这是第一优先级验证点。

控制台能看到插件加载日志

建议在 main.ts 中先加一个简单日志：

console.log('plugin_hello_demo loaded');

这样可以快速判断插件前端入口是否实际执行了。

运行环境没有报错

如果页面打不开或白屏，不要只看插件代码，也要看前端控制台和服务日志。

本章涉及的平台能力

`BPMAX.router.addRoute`

用途：向平台添加新页面。

这是最简单、最稳定的入门扩展点。

全局 `BPMAX`

插件入口运行时，平台会提供全局 BPMAX 对象。后续更复杂的插件会继续用到：

BPMAX.router
BPMAX.ui
BPMAX.flow
BPMAX.app

常见问题

路由注册了但页面打不开

页面组件路径写错
访问 URL 与注册路径不一致
插件入口未加载

页面能打开但样式或依赖异常

使用了平台运行环境未提供的依赖
复制源插件时残留旧引用

插件目录复制后仍引用旧名字

这是正常风险。虽然脚手架会做批量替换，但仍建议手动再检查一次：

目录名
config.json
main.ts 中的日志或路径
安装脚本与 Hook 文件名
目录名
config.json
main.ts 中的日志或路径
安装脚本与 Hook 文件名

可以在插件目录中全文搜索旧插件名，确认是否替换完整。