网上开源的流程引擎和表单引擎基本都只提供基础功能,博主有个项目涉及到这块内容,本来想简单引用一下网上开源的,毕竟这块功能在博主的项目里不是核心,但是找了多个开源项目后,发现表单和流程引擎虽然已经烂大街了,但真正做的好的又开源的其实不多,而且往深的做其实也有很高的门槛,前端、后端尤其是抽象能力都有一定要求。
一时心血来潮准备深入研究下这块东西,顺带把学习的过程记录下来,所以才有了这个系列文章。
所有文章(doc目录下)和官网的样例代码都放在了这个仓库:
https://gitee.com/fish982000/bpmn-js-examples-main.git后续会持续更新。
React 19 + TypeScript + BPMN 入门完整教程
这是一份从零到实战的教程,基于最新 React 19 + TypeScript,带你快速掌握 BPMN 流程设计器的基础使用、渲染、编辑、保存、导出等核心功能,全程可直接复制运行。
一、前置知识 & 环境
- 基础 React + TypeScript 语法
- 已创建好 React 19 + TS 项目(
create-react-app/vite均可) - 核心依赖:
-
bpmn-js:BPMN 渲染、建模核心库 -
bpmn-js-properties-panel:右侧属性配置面板 -
@bpmn-io/properties-panel:新版属性面板依赖 -
diagram-js:BPMN 底层绘图库(自动依赖)
-
二、安装依赖
在项目根目录执行:
# 核心 BPMN 库
npm install bpmn-js
# 属性面板(用于编辑节点名称、ID、类型等)
npm install bpmn-js-properties-panel @bpmn-io/properties-panel
# 样式文件
npm install inherits-browser
完整的组件清单:

image.png
三、核心概念(新手必看)
- Viewer:仅查看 BPMN 流程图(不可编辑)
- Modeler:可编辑、拖拽、配置的流程设计器(本教程重点)
- XML:BPMN 的数据格式(所有流程最终都是 XML 字符串)
- Canvas:画布区域
- Properties Panel:右侧属性配置面板
四、基础版:BPMN 流程图查看器(Viewer)
先实现只读展示,理解 BPMN 渲染原理。
1. 创建组件 BpmnViewer.tsx
import { useEffect, useRef } from 'react';
import BpmnViewer from 'bpmn-js';
import 'bpmn-js/dist/assets/diagram-js.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn.css';
// 示例 BPMN XML(默认空流程)
const defaultBpmnXml = `<?xml version="1.0" encoding="UTF-8"?>
<bpmn2:definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmn2="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" id="sample-diagram" targetNamespace="http://bpmn.io/schema/bpmn" xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/BPMN20.xsd">
<bpmn2:process id="Process_1" isExecutable="false">
<bpmn2:startEvent id="StartEvent_1" />
</bpmn2:process>
<bpmndi:BPMNDiagram id="BPMNDiagram_1">
<bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
<bpmndi:BPMNShape id="_BPMNShape_StartEvent_2" bpmnElement="StartEvent_1">
<dc:Bounds x="179" y="159" width="36" height="36" />
</bpmndi:BPMNShape>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</bpmn2:definitions>`;
const BpmnViewer = () => {
const containerRef = useRef<HTMLDivElement>(null);
const viewerRef = useRef<BpmnViewer | null>(null);
// 初始化 Viewer
useEffect(() => {
if (!containerRef.current) return;
// 创建实例
const viewer = new BpmnViewer({
container: containerRef.current,
width: '100%',
height: '600px',
});
viewerRef.current = viewer;
// 渲染 XML
viewer.importXML(defaultBpmnXml).catch((err) => {
if (err) console.error('BPMN 渲染失败', err);
});
// 销毁
return () => {
viewer.destroy();
};
}, []);
return (
<div style={{ border: '1px solid #eee' }}>
<h3>BPMN 查看器(只读)</h3>
<div ref={containerRef} style={{ width: '100%', height: '600px' }} />
</div>
);
};
export default BpmnViewer;
2. 在 App 中使用
import BpmnViewer from './BpmnViewer';
function App() {
return (
<div style={{ padding: 20 }}>
<BpmnViewer />
</div>
);
}
export default App;
运行项目,你会看到一个基础启动事件的流程图,不可编辑。
显示如下:

image.png
五、进阶版:可编辑 BPMN 设计器(Modeler)+ 属性面板
这是企业最常用的功能:
- 左侧工具栏拖拽节点
- 右侧编辑节点属性
- 保存/导出 XML
- 导出 SVG 图片
1. 创建组件 BpmnModeler.tsx
import { useEffect, useRef, useState } from 'react';
import Modeler from 'bpmn-js/lib/Modeler';
import 'bpmn-js/dist/assets/diagram-js.css'
import 'bpmn-js/dist/assets/bpmn-js.css'
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn.css'
import '@bpmn-io/properties-panel/assets/properties-panel.css'
// 引入属性面板模块
import {
BpmnPropertiesPanelModule,
BpmnPropertiesProviderModule,
} from 'bpmn-js-properties-panel';
// 默认空流程 XML
const defaultXml = `<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" id="sample-diagram" targetNamespace="http://bpmn.io/schema/bpmn" xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/bpmn0.xsd">
<bpmn:process id="Process_1" isExecutable="false">
<bpmn:startEvent id="StartEvent_1" />
</bpmn:process>
<bpmndi:BPMNDiagram id="BPMNDiagram_1">
<bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
<bpmndi:BPMNShape id="_BPMNShape_StartEvent_2" bpmnElement="StartEvent_1">
<dc:Bounds x="179" y="159" width="36" height="36" />
</bpmndi:BPMNShape>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</bpmn:definitions>`;
const BpmnModeler = () => {
const containerRef = useRef<HTMLDivElement>(null);
const panelRef = useRef<HTMLDivElement>(null);
const modelerRef = useRef<Modeler | null>(null);
// 存储当前 XML
const [xml, setXml] = useState<string>(defaultXml);
// 1. 初始化 BPMN 设计器
useEffect(() => {
if (!containerRef.current || !panelRef.current) return;
const modeler = new Modeler({
container: containerRef.current,
// 集成属性面板
additionalModules: [
BpmnPropertiesPanelModule,
BpmnPropertiesProviderModule,
],
propertiesPanel: {
parent: panelRef.current,
},
});
modelerRef.current = modeler;
// 加载默认 XML
modeler.importXML(defaultXml).catch((err) => {
console.error('加载失败', err);
});
// 监听修改事件
modeler.on('commandStack.changed', async () => {
try {
const { xml:string } = await modeler.saveXML({ format: true });
setXml(xml);
} catch (err) {
console.error('保存失败', err);
}
});
return () => {
modeler.destroy();
};
}, []);
// 2. 导出 XML 文件
const exportXml = async () => {
if (!modelerRef.current) return;
const { xml:string } = await modelerRef.current.saveXML({ format: true });
const blob = new Blob([xml], { type: 'application/xml' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'process.bpmn';
a.click();
URL.revokeObjectURL(url);
};
// 3. 导出 SVG 图片
const exportSvg = async () => {
if (!modelerRef.current) return;
const { svg } = await modelerRef.current.saveSVG();
const blob = new Blob([svg], { type: 'image/svg+xml' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'process.svg';
a.click();
URL.revokeObjectURL(url);
};
return (
<div>
<h2>React 19 + TS + BPMN 设计器</h2>
{/* 操作按钮 */}
<div style={{ marginBottom: 10, gap: 10, display: 'flex' }}>
<button onClick={exportXml}>导出 BPMN XML</button>
<button onClick={exportSvg}>导出 SVG 图片</button>
</div>
{/* 画布 + 属性面板 布局 */}
<div style={{ display: 'flex', border: '1px solid #eee' }} >
{/* BPMN 画布 */}
<div ref={containerRef} style={{width:'calc(100% - 300px)'}} />
{/* 右侧属性面板 */}
<div
ref={panelRef}
style={{
width: '300px',
height: '600px',
borderLeft: '1px solid #eee',
}}
/>
</div>
</div>
);
};
export default BpmnModeler;
2. 在 App.tsx 中使用
import BpmnViewer from './bpmn/components/demo/BpmnViewer';
import BpmnModeler from './bpmn/components/demo/BpmnModeler'
function App() {
return (
<div style={{ padding: 20 }}>
<BpmnModeler />
</div>
);
}
export default App;
六、运行效果
启动项目后,你会得到一个完整可用的 BPMN 设计器:
- 左侧工具栏:可拖拽开始/结束事件、用户任务、网关、连线等
- 中间画布:编辑流程图
- 右侧面板:选中节点可修改名称、ID、类型等属性
- 按钮:导出
.bpmn文件、导出.svg图片
显示如下:
image.png
七、TS 类型补充(避免类型报错)
如果 TS 提示模块无类型定义,可在项目根目录创建 types/bpmn.d.ts:
declare module 'bpmn-js' {
export class Modeler {
constructor(options: any);
importXML(xml: string): Promise<any>;
saveXML(options?: any): Promise<{ xml: string }>;
saveSVG(options?: any): Promise<{ svg: string }>;
on(event: string, callback: () => void): void;
destroy(): void;
}
export default class Viewer {
constructor(options: any);
importXML(xml: string): Promise<any>;
destroy(): void;
}
}
declare module 'bpmn-js-properties-panel' {
export const BpmnPropertiesPanelModule: any;
export const BpmnPropertiesProviderModule: any;
}
然后在 tsconfig.json 中加入:
"include": ["src", "types"]
八、常用功能扩展(企业级必备)
1. 加载本地 BPMN 文件
// 文件上传加载
const loadLocalFile = (e: React.ChangeEvent<HTMLInputElement>) => {
const file = e.target.files?.[0];
if (!file) return;
const reader = new FileReader();
reader.onload = async (ev) => {
const xml = ev.target?.result as string;
await modelerRef.current?.importXML(xml);
};
reader.readAsText(file);
};
2. 撤销 / 重做
const undo = () => modelerRef.current?.get('commandStack').undo();
const redo = () => modelerRef.current?.get('commandStack').redo();
3. 清空画布
const clearCanvas = () => modelerRef.current?.clear();
九、常见问题
-
样式错乱:必须引入
bpmn-js自带的 CSS 文件 - 属性面板不显示:检查容器宽度、模块是否正确注册
- TS 类型报错:使用上面的自定义类型声明
-
React 19 兼容:
bpmn-js不依赖 React 特性,100% 兼容 React 19
总结
- 本教程基于 React 19 + TS 实现了可用的 BPMN 设计器,开箱即用
- 核心分为 Viewer(查看) 和 Modeler(编辑)
- 支持:拖拽节点、属性配置、导出 XML/SVG、实时预览
- 可直接用于后台管理系统的流程设计模块
