BPMNJS官方案例1:starter- 快速入门

网上开源的流程引擎和表单引擎基本都只提供基础功能,博主有个项目涉及到这块内容,本来想简单引用一下网上开源的,毕竟这块功能在博主的项目里不是核心,但是找了多个开源项目后,发现表单和流程引擎虽然已经烂大街了,但真正做的好的又开源的其实不多,而且往深的做其实也有很高的门槛,前端、后端尤其是抽象能力都有一定要求。

一时心血来潮准备深入研究下这块东西,顺带把学习的过程记录下来,所以才有了这个系列文章。

所有文章(doc目录下)和官网的样例代码都放在了这个仓库:
https://gitee.com/fish982000/bpmn-js-examples-main.git

后续会持续更新。

React 19 + TypeScript + BPMN 入门完整教程

这是一份从零到实战的教程,基于最新 React 19 + TypeScript,带你快速掌握 BPMN 流程设计器的基础使用、渲染、编辑、保存、导出等核心功能,全程可直接复制运行。

一、前置知识 & 环境

  1. 基础 React + TypeScript 语法
  2. 已创建好 React 19 + TS 项目(create-react-app / vite 均可)
  3. 核心依赖:
    • 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

三、核心概念(新手必看)

  1. Viewer:仅查看 BPMN 流程图(不可编辑)
  2. Modeler:可编辑、拖拽、配置的流程设计器(本教程重点)
  3. XML:BPMN 的数据格式(所有流程最终都是 XML 字符串)
  4. Canvas:画布区域
  5. 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 设计器:

  1. 左侧工具栏:可拖拽开始/结束事件、用户任务、网关、连线等
  2. 中间画布:编辑流程图
  3. 右侧面板:选中节点可修改名称、ID、类型等属性
  4. 按钮:导出 .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();

九、常见问题

  1. 样式错乱:必须引入 bpmn-js 自带的 CSS 文件
  2. 属性面板不显示:检查容器宽度、模块是否正确注册
  3. TS 类型报错:使用上面的自定义类型声明
  4. React 19 兼容:bpmn-js 不依赖 React 特性,100% 兼容 React 19

总结

  1. 本教程基于 React 19 + TS 实现了可用的 BPMN 设计器,开箱即用
  2. 核心分为 Viewer(查看) 和 Modeler(编辑)
  3. 支持:拖拽节点、属性配置、导出 XML/SVG、实时预览
  4. 可直接用于后台管理系统的流程设计模块
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

相关阅读更多精彩内容

友情链接更多精彩内容