React 19 TypeScript BPMN 入门完整教程这是一份从零到实战的教程基于最新React 19TypeScript带你快速掌握 BPMN 流程设计器的基础使用、渲染、编辑、保存、导出等核心功能全程可直接复制运行。一、前置知识 环境基础 React TypeScript 语法已创建好 React 19 TS 项目create-react-app/vite均可核心依赖bpmn-jsBPMN 渲染、建模核心库bpmn-js-properties-panel右侧属性配置面板bpmn-io/properties-panel新版属性面板依赖diagram-jsBPMN 底层绘图库自动依赖二、安装依赖在项目根目录执行# 核心 BPMN 库npminstallbpmn-js# 属性面板用于编辑节点名称、ID、类型等npminstallbpmn-js-properties-panel bpmn-io/properties-panel# 样式文件npminstallinherits-browser完整的组件清单三、核心概念新手必看Viewer仅查看 BPMN 流程图不可编辑Modeler可编辑、拖拽、配置的流程设计器本教程重点XMLBPMN 的数据格式所有流程最终都是 XML 字符串Canvas画布区域Properties Panel右侧属性配置面板四、基础版BPMN 流程图查看器Viewer先实现只读展示理解 BPMN 渲染原理。1. 创建组件BpmnViewer.tsximport { 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 version1.0 encodingUTF-8? bpmn2:definitions xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:bpmn2http://www.omg.org/spec/BPMN/20100524/MODEL xmlns:bpmndihttp://www.omg.org/spec/BPMN/20100524/DI xmlns:dchttp://www.omg.org/spec/DD/20100524/DC idsample-diagram targetNamespacehttp://bpmn.io/schema/bpmn xsi:schemaLocationhttp://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/BPMN20.xsd bpmn2:process idProcess_1 isExecutablefalse bpmn2:startEvent idStartEvent_1 / /bpmn2:process bpmndi:BPMNDiagram idBPMNDiagram_1 bpmndi:BPMNPlane idBPMNPlane_1 bpmnElementProcess_1 bpmndi:BPMNShape id_BPMNShape_StartEvent_2 bpmnElementStartEvent_1 dc:Bounds x179 y159 width36 height36 / /bpmndi:BPMNShape /bpmndi:BPMNPlane /bpmndi:BPMNDiagram /bpmn2:definitions; const BpmnViewer () { const containerRef useRefHTMLDivElement(null); const viewerRef useRefBpmnViewer | 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 }} h3BPMN 查看器只读/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;运行项目你会看到一个基础启动事件的流程图不可编辑。显示如下五、进阶版可编辑 BPMN 设计器Modeler 属性面板这是企业最常用的功能左侧工具栏拖拽节点右侧编辑节点属性保存/导出 XML导出 SVG 图片1. 创建组件BpmnModeler.tsximport { 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 version1.0 encodingUTF-8? bpmn:definitions xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:bpmnhttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:bpmndihttp://www.omg.org/spec/BPMN/20100524/DI xmlns:dchttp://www.omg.org/spec/DD/20100524/DC idsample-diagram targetNamespacehttp://bpmn.io/schema/bpmn xsi:schemaLocationhttp://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/bpmn0.xsd bpmn:process idProcess_1 isExecutablefalse bpmn:startEvent idStartEvent_1 / /bpmn:process bpmndi:BPMNDiagram idBPMNDiagram_1 bpmndi:BPMNPlane idBPMNPlane_1 bpmnElementProcess_1 bpmndi:BPMNShape id_BPMNShape_StartEvent_2 bpmnElementStartEvent_1 dc:Bounds x179 y159 width36 height36 / /bpmndi:BPMNShape /bpmndi:BPMNPlane /bpmndi:BPMNDiagram /bpmn:definitions; const BpmnModeler () { const containerRef useRefHTMLDivElement(null); const panelRef useRefHTMLDivElement(null); const modelerRef useRefModeler | null(null); // 存储当前 XML const [xml, setXml] useStatestring(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/svgxml }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download process.svg; a.click(); URL.revokeObjectURL(url); }; return ( div h2React 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图片显示如下七、TS 类型补充避免类型报错如果 TS 提示模块无类型定义可在项目根目录创建types/bpmn.d.tsdeclaremodulebpmn-js{exportclassModeler{constructor(options:any);importXML(xml:string):Promiseany;saveXML(options?:any):Promise{xml:string};saveSVG(options?:any):Promise{svg:string};on(event:string,callback:()void):void;destroy():void;}exportdefaultclassViewer{constructor(options:any);importXML(xml:string):Promiseany;destroy():void;}}declaremodulebpmn-js-properties-panel{exportconstBpmnPropertiesPanelModule:any;exportconstBpmnPropertiesProviderModule:any;}然后在tsconfig.json中加入include:[src,types]八、常用功能扩展企业级必备1. 加载本地 BPMN 文件// 文件上传加载 const loadLocalFile (e: React.ChangeEventHTMLInputElement) { 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、实时预览可直接用于后台管理系统的流程设计模块
BPMNJS官方案例1：React 19 + TypeScript + BPMN 入门完整教程
发布时间：2026/6/5 2:49:45
React 19 TypeScript BPMN 入门完整教程这是一份从零到实战的教程基于最新React 19TypeScript带你快速掌握 BPMN 流程设计器的基础使用、渲染、编辑、保存、导出等核心功能全程可直接复制运行。一、前置知识 环境基础 React TypeScript 语法已创建好 React 19 TS 项目create-react-app/vite均可核心依赖bpmn-jsBPMN 渲染、建模核心库bpmn-js-properties-panel右侧属性配置面板bpmn-io/properties-panel新版属性面板依赖diagram-jsBPMN 底层绘图库自动依赖二、安装依赖在项目根目录执行# 核心 BPMN 库npminstallbpmn-js# 属性面板用于编辑节点名称、ID、类型等npminstallbpmn-js-properties-panel bpmn-io/properties-panel# 样式文件npminstallinherits-browser完整的组件清单三、核心概念新手必看Viewer仅查看 BPMN 流程图不可编辑Modeler可编辑、拖拽、配置的流程设计器本教程重点XMLBPMN 的数据格式所有流程最终都是 XML 字符串Canvas画布区域Properties Panel右侧属性配置面板四、基础版BPMN 流程图查看器Viewer先实现只读展示理解 BPMN 渲染原理。1. 创建组件BpmnViewer.tsximport { 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 version1.0 encodingUTF-8? bpmn2:definitions xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:bpmn2http://www.omg.org/spec/BPMN/20100524/MODEL xmlns:bpmndihttp://www.omg.org/spec/BPMN/20100524/DI xmlns:dchttp://www.omg.org/spec/DD/20100524/DC idsample-diagram targetNamespacehttp://bpmn.io/schema/bpmn xsi:schemaLocationhttp://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/BPMN20.xsd bpmn2:process idProcess_1 isExecutablefalse bpmn2:startEvent idStartEvent_1 / /bpmn2:process bpmndi:BPMNDiagram idBPMNDiagram_1 bpmndi:BPMNPlane idBPMNPlane_1 bpmnElementProcess_1 bpmndi:BPMNShape id_BPMNShape_StartEvent_2 bpmnElementStartEvent_1 dc:Bounds x179 y159 width36 height36 / /bpmndi:BPMNShape /bpmndi:BPMNPlane /bpmndi:BPMNDiagram /bpmn2:definitions; const BpmnViewer () { const containerRef useRefHTMLDivElement(null); const viewerRef useRefBpmnViewer | 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 }} h3BPMN 查看器只读/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;运行项目你会看到一个基础启动事件的流程图不可编辑。显示如下五、进阶版可编辑 BPMN 设计器Modeler 属性面板这是企业最常用的功能左侧工具栏拖拽节点右侧编辑节点属性保存/导出 XML导出 SVG 图片1. 创建组件BpmnModeler.tsximport { 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 version1.0 encodingUTF-8? bpmn:definitions xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:bpmnhttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:bpmndihttp://www.omg.org/spec/BPMN/20100524/DI xmlns:dchttp://www.omg.org/spec/DD/20100524/DC idsample-diagram targetNamespacehttp://bpmn.io/schema/bpmn xsi:schemaLocationhttp://www.omg.org/spec/BPMN/20100524/MODEL http://www.omg.org/spec/BPMN/2.0/20100524/bpmn0.xsd bpmn:process idProcess_1 isExecutablefalse bpmn:startEvent idStartEvent_1 / /bpmn:process bpmndi:BPMNDiagram idBPMNDiagram_1 bpmndi:BPMNPlane idBPMNPlane_1 bpmnElementProcess_1 bpmndi:BPMNShape id_BPMNShape_StartEvent_2 bpmnElementStartEvent_1 dc:Bounds x179 y159 width36 height36 / /bpmndi:BPMNShape /bpmndi:BPMNPlane /bpmndi:BPMNDiagram /bpmn:definitions; const BpmnModeler () { const containerRef useRefHTMLDivElement(null); const panelRef useRefHTMLDivElement(null); const modelerRef useRefModeler | null(null); // 存储当前 XML const [xml, setXml] useStatestring(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/svgxml }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download process.svg; a.click(); URL.revokeObjectURL(url); }; return ( div h2React 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图片显示如下七、TS 类型补充避免类型报错如果 TS 提示模块无类型定义可在项目根目录创建types/bpmn.d.tsdeclaremodulebpmn-js{exportclassModeler{constructor(options:any);importXML(xml:string):Promiseany;saveXML(options?:any):Promise{xml:string};saveSVG(options?:any):Promise{svg:string};on(event:string,callback:()void):void;destroy():void;}exportdefaultclassViewer{constructor(options:any);importXML(xml:string):Promiseany;destroy():void;}}declaremodulebpmn-js-properties-panel{exportconstBpmnPropertiesPanelModule:any;exportconstBpmnPropertiesProviderModule:any;}然后在tsconfig.json中加入include:[src,types]八、常用功能扩展企业级必备1. 加载本地 BPMN 文件// 文件上传加载 const loadLocalFile (e: React.ChangeEventHTMLInputElement) { 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、实时预览可直接用于后台管理系统的流程设计模块
