智能运维与IT工作台前端BPMN流程插件

基于 bpmn.js 封装的 React 组件库，同时提供 Viewer（只读查看）和 Modeler（可编辑建模）两个组件，并深度集成了 Flowable 扩展属性支持。

特性

• 🎨 开箱即用 - 提供 BpmnViewer 和 BpmnModeler 两个 React 组件
• 📝 Flowable 扩展属性 - 完整支持 26 种 Flowable/activiti 扩展类型，属性面板可视化编辑
• 🌐 国际化 - 内置中文翻译支持，可扩展其他语言
• 🎯 TypeScript - 完整的类型定义
• 📐 自动布局 - 内置 bpmn-auto-layout，支持为缺少坐标信息的 XML 自动生成布局
• 🔍 规则校验 - 内置 bpmnlint，实时校验流程规范性
• ✏️ 手绘风格 - 支持 sketchy 手绘风格渲染

安装

npm install iop-bpmn-react

快速开始

import { BpmnViewer, BpmnModeler } from 'iop-bpmn-react'
import 'iop-bpmn-react/style.css'

// 只读查看
function ViewerDemo() {
  return <BpmnViewer xml={bpmnXml} />
}

// 可编辑建模
function ModelerDemo() {
  return <BpmnModeler xml={bpmnXml} />
}

导入

// 组件
import { BpmnViewer, BpmnModeler } from 'iop-bpmn-react'
import 'iop-bpmn-react/style.css'

// 工具函数
import { fitToView, layoutProcess } from 'iop-bpmn-react'

// 国际化
import { i18n, zhTranslations, addTranslations, getTranslations } from 'iop-bpmn-react'

// 令牌模拟模块
import { TokenSimulationModule } from 'iop-bpmn-react'

API

BpmnViewer

只读 BPMN 流程查看器组件。

<BpmnViewer
  xml={bpmnXml}
  autoLayout={false}
  locale="zh"
  className="viewer"
  style={{ width: '100%', height: '500px' }}
  onInit={(viewer) => { /* viewer 初始化完成 */ }}
/>

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | xml | string | 必填 | BPMN 2.0 XML 字符串 | | autoLayout | boolean | false | 是否自动布局（为缺少 DI 信息的 XML 生成坐标） | | locale | 'zh' \| 'en' \| 'ja' | 'zh' | 界面语言 | | className | string | — | 自定义类名 | | style | CSSProperties | — | 自定义样式 | | onInit | (viewer: Viewer) => void | — | 初始化完成回调 |

BpmnModeler

可编辑 BPMN 流程建模器组件，内置属性面板。

<BpmnModeler
  xml={bpmnXml}
  autoLayout={false}
  linting={true}
  sketchy={false}
  locale="zh"
  className="modeler"
  style={{ width: '100%', height: '500px' }}
  onSave={(xml) => console.log(xml)}
  onChange={(xml) => console.log(xml)}
  onInit={(modeler) => { /* modeler 初始化完成 */ }}
/>

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | xml | string | 必填 | BPMN 2.0 XML 字符串 | | autoLayout | boolean | false | 是否自动布局 | | linting | boolean | false | 是否启用规则校验 | | sketchy | boolean | false | 是否启用手绘风格 | | locale | 'zh' \| 'en' \| 'ja' | 'zh' | 界面语言 | | className | string | — | 画布容器类名 | | style | CSSProperties | — | 画布容器样式 | | panelClassName | string | — | 属性面板容器类名 | | panelStyle | CSSProperties | — | 属性面板容器样式 | | onSave | (xml: string) => void | — | 保存回调 | | onChange | (xml: string) => void | — | 内容变更回调 | | onInit | (modeler: Modeler) => void | — | 初始化完成回调 |

fitToView

将流程图适配到视口并居中显示。

import { fitToView } from 'iop-bpmn-react'

// 在 onInit 回调中使用
<BpmnViewer onInit={(viewer) => fitToView(viewer)} />

layoutProcess

对 BPMN XML 进行自动布局，为缺少坐标信息的元素生成位置。

import { layoutProcess } from 'iop-bpmn-react'

const layoutedXml = await layoutProcess(xmlString)

开发命令

| 任务 | 命令 | |------|------| | 启动开发服务器 | npm run dev | | 构建库 | npm run build | | 代码检查 | npm run lint | | 预览构建产物 | npm run preview |

项目结构

src/
├── lib/                          # 库源码（构建入口）
│   ├── index.ts                  # 统一导出 + bpmn-js 样式引入
│   ├── components/
│   │   ├── BpmnViewer/           # 只读查看器组件
│   │   └── BpmnModeler/          # 可编辑建模器组件
│   │       ├── FlowablePropertiesProvider/  # Flowable 属性面板
│   │       └── flowable-bpmn-moddle/        # Flowable moddle 扩展
│   ├── hooks/
│   │   └── useBpmn.ts            # 公共 hook（封装 bpmn-js 生命周期）
│   ├── i18n/
│   │   └── zh.ts                 # 中文翻译
│   ├── resources/
│   │   └── flowable.json         # Flowable moddle 描述符
│   └── types/
│       └── index.ts              # 类型定义
├── App.tsx                       # Demo 应用（开发调试用）
├── main.tsx                      # Demo 入口
└── ...

Flowable 扩展属性支持

本项目完整支持 Flowable/activiti 的 BPMN 扩展属性，通过 FlowablePropertiesProvider 在属性面板中提供可视化编辑。

Moddle 描述符类型

共定义 26 种 Flowable 扩展类型：

| 类型名称 | 扩展目标 | 属性 | |----------|----------|------| | Process | bpmn:Process | candidateStarterGroups, candidateStarterUsers | | Assignable | bpmn:UserTask | assignee, candidateUsers, candidateGroups, dueDate, followUpDate, priority | | TaskFormSupported | bpmn:UserTask | formKey, formFieldValidation | | StartFormSupported | bpmn:StartEvent | formKey, formFieldValidation | | Initiator | bpmn:StartEvent | initiator | | AsyncCapable | bpmn:Activity, bpmn:Gateway, bpmn:Event | async, asyncBefore, asyncAfter, exclusive | | ServiceTaskLike | bpmn:ServiceTask, bpmn:BusinessRuleTask, bpmn:SendTask | class, delegateExpression, expression, resultVariable | | ScriptTaskLike | bpmn:ScriptTask | autoStoreVariables, resultVariable, failedJobRetryTimeCycle | | DmnCapable | bpmn:BusinessRuleTask | decisionTable, decisionRef, decisionRefBinding, mapDecisionResult, resultVariable | | ExternalCapable | bpmn:ServiceTask | topic, taskPriority | | VariableMappingCapable | bpmn:CallActivity | variableMappingClass, variableMappingDelegateExpression | | Collectable | bpmn:MultiInstanceLoopCharacteristics | collection, elementVariable | | FormData | — | formProperty[] | | FormProperty | — | id, name, type, expression, variable, default, datePattern, readable, writable, required, formValues[] | | FormValue | — | id, name | | Properties | — | values (Property[]) | | Property | — | id, name, value | | In | — | source, sourceExpression, target, variables | | Out | — | source, sourceExpression, target, variables | | Field | — | name, stringValue, expression | | ExecutionListener | — | expression, class, delegateExpression, event, field[] | | TaskListener | — | expression, class, delegateExpression, event, field[] | | FailedJobRetryTimeCycle | — | body | | SignalEventDefinitionExtension | bpmn:SignalEventDefinition | signalExpression | | ErrorEventDefinitionExtension | bpmn:ErrorEventDefinition | errorCodeVariable, errorMessageVariable | | ConditionalEventDefinitionExtension | bpmn:ConditionalEventDefinition | variableName, variableEvents |

属性面板分组

属性面板根据元素类型自动显示对应的属性分组：

流程 (Process)

• 流程属性 - 候选启动组、候选启动用户

开始事件 (StartEvent)

• 表单 - 表单键、表单字段验证
• 表单数据 - 表单属性列表（支持枚举值）
• 发起者 - 发起者变量名
• 执行监听器 - 支持字段注入

用户任务 (UserTask)

• 分配 - 负责人、候选用户、候选组、到期日期、跟进日期、优先级
• 表单 - 表单键、表单字段验证
• 表单数据 - 表单属性列表（支持枚举值）
• 异步配置 - 异步前、异步后、排他、失败重试周期
• 任务监听器 - 支持字段注入

服务任务 (ServiceTask)

• 实现 - Java类、委托表达式、表达式、结果变量
• 外部任务 - 主题、任务优先级
• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 字段注入 - 字段名、字符串值、表达式
• 扩展属性 - 自定义键值对

业务规则任务 (BusinessRuleTask)

• 实现 - Java类、委托表达式、表达式、结果变量
• 决策 - 决策引用、决策绑定、映射决策结果、结果变量
• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 字段注入 - 字段名、字符串值、表达式
• 扩展属性 - 自定义键值对

脚本任务 (ScriptTask)

• 脚本 - 脚本格式、结果变量、自动存储变量
• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 字段注入 - 字段名、字符串值、表达式
• 扩展属性 - 自定义键值对

调用活动 (CallActivity)

• 变量映射 - 变量映射类、变量映射委托表达式
• 输入/输出映射 - In/Out 映射列表
• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 扩展属性 - 自定义键值对

网关 (Gateway)

• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 扩展属性 - 自定义键值对

事件 (Event)

• 异步配置 - 异步前、异步后、排他、失败重试周期
• 执行监听器 - 支持字段注入
• 扩展属性 - 自定义键值对

信号事件定义 (SignalEventDefinition)

• 信号 - 信号表达式

错误事件定义 (ErrorEventDefinition)

• 错误 - 错误代码变量、错误消息变量

条件事件定义 (ConditionalEventDefinition)

• 条件 - 变量名、变量事件

多实例 (MultiInstance)

• 多实例 - 集合、元素变量

属性说明

分配属性

| 属性 | 说明 | 示例 | |------|------|------| | assignee | 任务负责人 | 张三 或 ${assignee} | | candidateUsers | 候选用户（逗号分隔） | user1,user2 | | candidateGroups | 候选组（逗号分隔） | group1,group2 | | dueDate | 到期日期 | 2024-12-31 或 ${dueDate} | | followUpDate | 跟进日期 | 2024-12-31 或 ${followUpDate} | | priority | 优先级 | 50 或 ${priority} |

表单属性

| 属性 | 说明 | 示例 | |------|------|------| | formKey | 表单键 | embedded:app:forms/start.html | | formFieldValidation | 表单字段验证 | true / false |

异步配置

| 属性 | 说明 | 默认值 | |------|------|--------| | asyncBefore | 异步前 | false | | asyncAfter | 异步后 | false | | exclusive | 排他 | true | | failedJobRetryTimeCycle | 失败重试周期 | R3/PT10M |

服务任务实现

| 属性 | 说明 | 示例 | |------|------|------| | class | Java类 | com.example.MyDelegate | | delegateExpression | 委托表达式 | ${myDelegate} | | expression | 表达式 | ${myService.execute(execution)} | | resultVariable | 结果变量 | result |

业务规则任务决策

| 属性 | 说明 | 示例 | |------|------|------| | decisionRef | 决策引用 | myDecision | | decisionRefBinding | 决策绑定 | latest / deployment / versionTag | | mapDecisionResult | 映射决策结果 | singleEntry / singleResult / collectEntries / resultList | | resultVariable | 结果变量 | result |

脚本任务

| 属性 | 说明 | 示例 | |------|------|------| | scriptFormat | 脚本格式 | groovy / javascript | | resultVariable | 结果变量 | result | | autoStoreVariables | 自动存储变量 | true / false |

外部任务

| 属性 | 说明 | 示例 | |------|------|------| | topic | 主题 | myTopic | | taskPriority | 任务优先级 | 50 |

调用活动变量映射

| 属性 | 说明 | 示例 | |------|------|------| | variableMappingClass | 变量映射类 | com.example.MyMapping | | variableMappingDelegateExpression | 变量映射委托表达式 | ${myMapping} |

发起者

| 属性 | 说明 | 示例 | |------|------|------| | initiator | 发起者变量名 | initiator |

监听器

| 属性 | 说明 | 示例 | |------|------|------| | event | 事件类型 | start / end / create / assignment / complete / delete / update / timeout | | class | Java类 | com.example.MyListener | | expression | 表达式 | ${myListener.notify(execution)} | | delegateExpression | 委托表达式 | ${myListener} | | field | 字段注入 | 支持 name, stringValue, expression |

字段注入

| 属性 | 说明 | 示例 | |------|------|------| | name | 字段名 | myField | | stringValue | 字段值 | hello | | expression | 表达式 | ${myVariable} |

扩展属性

自定义键值对，可用于存储任意扩展信息。

多实例

| 属性 | 说明 | 示例 | |------|------|------| | collection | 集合变量或表达式 | ${users} | | elementVariable | 元素变量名 | user |

表单数据

支持 flowable:formData 和 flowable:formProperty，包括：

• 表单属性：id, name, type, expression, variable, default, datePattern
• 属性选项：readable, writable, required
• 枚举值：formValues (id, name)

事件定义扩展

| 事件类型 | 属性 | 说明 | |----------|------|------| | 信号事件 | signalExpression | 信号表达式 | | 错误事件 | errorCodeVariable | 错误代码变量 | | 错误事件 | errorMessageVariable | 错误消息变量 | | 条件事件 | variableName | 变量名 | | 条件事件 | variableEvents | 变量事件（逗号分隔） |

技术栈

• Vite 8 - 构建工具
• React 19 + TypeScript
• bpmn-js - BPMN 2.0 流程图引擎
• bpmn-js-properties-panel - 属性面板组件
• bpmn-js-i18n - 国际化翻译

许可证

MIT