网上开源的流程引擎和表单引擎基本都只提供基础功能,博主有个项目涉及到这块内容,本来想简单引用一下网上开源的,毕竟这块功能在博主的项目里不是核心,但是找了多个开源项目后,发现表单和流程引擎虽然已经烂大街了,但真正做的好的又开源的其实不多,而且往深的做其实也有很高的门槛,前端、后端尤其是抽象能力都有一定要求。
一时心血来潮准备深入研究下这块东西,顺带把学习的过程记录下来,所以才有了这个系列文章。
所有文章(doc目录下)和官网的样例代码都放在了这个仓库:
https://gitee.com/fish982000/bpmn-js-examples-main.git后续会持续更新。
在 bpmn-js 里,overlays、canvas、elementRegistry、modeling 是最核心、最常用的 4 个模块,几乎所有二次开发(标注、移动、修改、获取元素)都离不开它们。
一、统一获取方式(所有模块都这么拿)
在 bpmn-js 实例化后,通过 inject 或 get() 获取:
const modeler = new BpmnModeler({ container: '#canvas' });
// 获取四大核心对象
const overlays = modeler.get('overlays');
const canvas = modeler.get('canvas');
const elementRegistry = modeler.get('elementRegistry');
const modeling = modeler.get('modeling');
二、四大对象详细说明
1. overlays —— 元素标注/悬浮层
作用:给流程节点(任务、网关、事件)添加额外HTML标注,比如错误提示、状态图标、统计数字、按钮。
作用:想在节点旁边/上面显示东西 → 用 overlays
常用 API
// 添加标注
overlays.add(element, 'position类', {
html: '<div>我是标注</div>', // 自定义HTML
show: { minZoom: 0.5 } // 缩放控制显示
});
// 清空某个元素的标注
overlays.remove(element);
// 清空所有标注
overlays.clear();
官方提供的pizza案例中给CalmCustomerTask节点增加一层绿色遮障
var shape = elementRegistry.get('CalmCustomerTask');
var $overlayHtml = $('<div class="highlight-overlay">')
.css({
width: shape.width,
height: shape.height
}
overlays.add('CalmCustomerTask', {
position: {
top: 0,
left: 0
},
html: $overlayHtml
});
显示如下:

image.png
官方案例中其他几种改变节点背景颜色的方法
// Option 2: Color via BPMN 2.0 Extension
var elementToColor = elementRegistry.get('SelectAPizzaTask');
modeling.setColor([ elementToColor ], {
stroke: 'green',
fill: 'rgb(152, 203, 152)'
});
// Option 3: Color via Marker + CSS Styling
canvas.addMarker('OrderReceivedEvent', 'highlight');
典型用途
- 节点错误/警告小红点
- 审批状态图标
- 节点执行次数/耗时
- 自定义按钮(如删除、编辑)
2. canvas —— 画布控制器
作用:控制整个画布视图,和流程数据无关,只控制显示、缩放、居中、背景、画布容器。
一句话:想操作画布视野 → 用 canvas
常用 API
// 缩放并居中所有元素
canvas.zoom('fit-viewport', 'auto');
// 手动设置缩放比例
canvas.zoom(0.8);
// 获取画布根元素
const rootElement = canvas.getRootElement();
// 平移画布
canvas.pan({ x: 100, y: 100 });
// 清空画布(删除所有元素)
canvas.clear();
典型用途
- 打开流程图后自动居中
- 实现“适应画布”“放大”“缩小”
- 获取画布视口信息
3. elementRegistry —— 元素注册表
作用:查询、获取所有流程节点(任务、连线、网关、事件等),只读为主。
一句话:想找某个节点 → 用 elementRegistry
常用 API
// 根据 ID 获取元素(最常用)
const element = elementRegistry.get('Activity_123');
// 获取所有元素
const allElements = elementRegistry.getAll();
// 过滤获取所有任务节点
const tasks = elementRegistry.filter(el => el.type === 'bpmn:Task');
典型用途
- 根据业务 ID 找到对应节点
- 遍历所有流程元素
- 获取元素的形状、位置、类型
4. modeling —— 流程模型编辑器
作用:修改流程数据,增删改节点、连线、属性、颜色、名称。
这是唯一能真正修改 BPMN 模型的对象。
常用 API
// 更新元素名称
modeling.updateLabel(element, '新名称');
// 设置元素颜色(填充色 + 边框色)
modeling.setColor(element, {
fill: '#ff0000',
stroke: '#000000'
});
// 移动元素
modeling.moveElements([element], { x: 50, y: 50 });
// 删除元素
modeling.removeElements([element]);
// 创建连线
modeling.connect(sourceEl, targetEl);
典型用途
- 动态修改节点名称
- 高亮节点(流程跟踪)
- 动态增删任务
- 自动布局
三、总结
- overlays:画标注、显示小红点/图标
- canvas:控制画布视野、缩放、居中
- elementRegistry:查找、获取元素
- modeling:修改元素、颜色、名称、连线
四、最经典组合使用示例(流程跟踪高亮+标注)
// 1. 获取元素
const task = elementRegistry.get('Activity_1');
// 2. 修改颜色(高亮)
modeling.setColor(task, { fill: '#4aa3f7', stroke: '#000' });
// 3. 添加标注
overlays.add(task, {
html: '<div style="color:white">执行中</div>'
});
// 4. 画布居中
canvas.zoom('fit-viewport');