bpmn.js入门：生态与最小示例

发表于 更新于 分类于 ， ， ， 阅读次数：

现在我们从理论进入实践。bpmn.js 是一个由 bpmn.io 社区维护的JavaScript库，用来加载、编辑、展示BPMN流程图。本文介绍bpmn.js的生态、核心概念与最小实现示例。

bpmn.js生态

核心库

bpmn.js 的生态由几个关键库组成：

  1. bpmn-js：核心库，提供Viewer与Modeler

    • Viewer：只读展示模式，用于查看流程图
    • Modeler：编辑模式，支持拖拽、编辑、保存

  2. diagram-js：低层次的图形库

    • 提供画布、元素、事件系统
    • bpmn-js 基于它构建

  3. bpmn-moddle：BPMN数据模型库

    • 解析/生成 BPMN XML
    • 管理流程对象的属性

  4. 相关扩展：

    • bpmn-js-properties-panel：属性面板
    • diagram-js-minimap：小地图
    • bpmn-js-token-simulation：流程模拟

工作原理

1
2
3
4
5
6
7
8
9
BPMN XML 文件
    ↓
bpmn-moddle（解析）
    ↓
diagram-js（渲染到画布）
    ↓
bpmn-js（交互与编辑）
    ↓
浏览器中的可视流程图

两种使用模式

Viewer（查看器）

场景：展示流程图，用户无法编辑。

常见用途：

  • 流程审批页面
  • 流程历史查看
  • 流程可视化报告

特点：

  • 轻量级，加载快
  • 无编辑功能
  • 支持缩放、拖拽视图

Modeler（建模器）

场景：用户可以创建、编辑、保存流程图。

常见用途：

  • 流程设计器
  • 工作流配置工具
  • 流程模板编辑

特点：

  • 完整功能（Palette、ContextPad）
  • 支持拖拽添加元素
  • 可保存为XML

最小HTML示例

基础框架

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>bpmn.js最小示例</title>
  
  <style>
    html, body, #canvas {
      width: 100%;
      height: 100%;
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>
  <!-- 流程图容器 -->
  <div id="canvas"></div>

  <!-- bpmn-js库 -->
  <script src="https://cdn.jsdelivr.net/npm/bpmn-js@latest/dist/bpmn-viewer.production.min.js"></script>
  
  <script>
    // 创建Viewer实例
    const viewer = new BpmnJS({
      container: '#canvas'
    });

    // 示例BPMN XML（简单的订单审批流程）
    const bpmnDiagram = `<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                   id="Definitions_1" targetNamespace="http://bpmn.io/schema/bpmn">
  <bpmn:process id="OrderApproval" isExecutable="false">
    <bpmn:startEvent id="StartEvent_1"/>
    <bpmn:userTask id="ApproveOrder" name="审批订单"/>
    <bpmn:endEvent id="EndEvent_1"/>
    <bpmn:sequenceFlow id="Flow_1" sourceRef="StartEvent_1" targetRef="ApproveOrder"/>
    <bpmn:sequenceFlow id="Flow_2" sourceRef="ApproveOrder" targetRef="EndEvent_1"/>
  </bpmn:process>
  
  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="OrderApproval">
      <bpmndi:BPMNShape id="BPMNShape_StartEvent_1" bpmnElement="StartEvent_1">
        <dc:Bounds x="100" y="100" width="36" height="36"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="BPMNShape_ApproveOrder" bpmnElement="ApproveOrder">
        <dc:Bounds x="200" y="80" width="100" height="80"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="BPMNShape_EndEvent_1" bpmnElement="EndEvent_1">
        <dc:Bounds x="380" y="100" width="36" height="36"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNEdge id="BPMNEdge_Flow_1" bpmnElement="Flow_1">
        <di:waypoint x="136" y="118"/>
        <di:waypoint x="200" y="120"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="BPMNEdge_Flow_2" bpmnElement="Flow_2">
        <di:waypoint x="300" y="120"/>
        <di:waypoint x="380" y="118"/>
      </bpmndi:BPMNEdge>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
</bpmn:definitions>`;

    // 加载流程图
    viewer.importXML(bpmnDiagram).then(() => {
      // 自动适配视窗
      viewer.get('canvas').zoom('fit-viewport');
      console.log('流程图加载成功！');
    }).catch(err => {
      console.error('加载失败：', err);
    });
  </script>
</body>
</html>

效果说明

  • 容器：<div id="canvas"> 是流程图的绘制区域
  • 加载XML：通过 importXML() 方法解析BPMN XML并在画布上渲染
  • 自动适配：zoom('fit-viewport') 使流程图自动居中与缩放适应窗口
  • 错误处理：异步操作使用 Promise 进行错误捕获

bpmn.js的核心API概览

API 用途 返回值
new BpmnJS(options) 创建Viewer/Modeler实例 BpmnJS对象
importXML(xml) 加载BPMN XML Promise
saveXML() 导出为XML Promise<{xml: string}>
get('canvas') 获取画布对象 Canvas
get('elementRegistry') 获取元素注册表 ElementRegistry
get('eventBus') 获取事件总线 EventBus

常见的配置选项

1
2
3
4
5
const viewer = new BpmnJS({
  container: '#canvas',           // 容器选择器或DOM元素
  keyboard: { bindTo: document }, // 键盘事件绑定
  canvas: { deferUpdate: false }  // 画布更新策略
});

小结

掌握bpmn.js入门：

  • ✓ 理解生态结构（bpmn-js、diagram-js、bpmn-moddle）
  • ✓ Viewer vs Modeler 的选择
  • ✓ 最小HTML示例的完整流程
  • ✓ importXML 与基础配置

接下来将深入讲解Viewer与Modeler的各自特性与API。

参考资料