performance-bpmn-js

English | 简体中文

performance-bpmn-js 是一个兼容 bpmn-js 的 Viewer / NavigatedViewer / Modeler 包，提供可选的性能指标采集和保守的 SVG 渲染优化。

该包保持 bpmn-js 的公共 API 与扩展模型不变。性能能力通过 didi 模块追加，并且可以通过配置关闭，也可以被用户的 additionalModules 覆盖。

目标

• 保持 bpmn-js 的构造、导入、导出、清理、销毁和服务访问语义。
• 保持自定义模块、自定义 renderer、rules 和 modeling 扩展可覆盖。
• 通过局部模块覆盖增加指标与优化服务，不复制上游源码树。
• 当遇到 connection docking、自定义图形或未知 dirty 变更时，优先回退到安全路径。

安装

npm install performance-bpmn-js

当前包依赖 npm registry 中的以下版本范围：

• bpmn-js: ^18.16.1
• diagram-js: ^15.14.0

入口

import Viewer from 'performance-bpmn-js';
import Viewer from 'performance-bpmn-js/lib/Viewer';
import NavigatedViewer from 'performance-bpmn-js/lib/NavigatedViewer';
import Modeler from 'performance-bpmn-js/lib/Modeler';

同时提供兼容性转导出：

import BaseViewer from 'performance-bpmn-js/lib/BaseViewer';
import BaseModeler from 'performance-bpmn-js/lib/BaseModeler';

基础用法

import Viewer from 'performance-bpmn-js';

const viewer = new Viewer({
  container: '#canvas',
  performance: {
    metrics: {
      enabled: true
    },
    renderer: {
      cachePaths: true,
      diffUpdates: true
    },
    viewport: {
      enabled: true,
      mode: 'hide',
      overscan: 0.5
    }
  }
});

const { warnings } = await viewer.importXML(xml);
const { svg } = await viewer.saveSVG();

performance-bpmn-js 支持与 bpmn-js 一致的常用公共方法：

• importXML(xml, bpmnDiagram?)
• importDefinitions(definitions, bpmnDiagram?)
• open(bpmnDiagramOrId?)
• saveXML(options?)
• saveSVG()
• clear()
• destroy()
• attachTo(parentNode)
• detach()
• get(serviceName)
• on(events, priority?, callback, that?)
• off(events, callback?)
• Modeler#createDiagram()

性能配置

所有自定义行为都集中在 options.performance 下。

const viewer = new Viewer({
  performance: {
    enabled: true,
    metrics: {
      enabled: true,
      sink(snapshot) {
        console.log(snapshot);
      }
    },
    renderer: {
      cachePaths: true,
      cacheMarkers: false,
      diffUpdates: true
    },
    viewport: {
      enabled: true,
      mode: 'hide',
      overscan: 0.5,
      minZoom: 0
    },
    events: {
      coalescePointerEvents: false,
      pointerFrameBudget: 8
    },
    import: {
      batchSize: 500,
      chunked: false,
      firstViewportOnly: false
    }
  }
});

当前默认值偏保守：

• metrics.enabled: true
• viewport.enabled: false
• renderer.cachePaths: false
• renderer.diffUpdates: false
• events.coalescePointerEvents: false
• import.chunked: false

核心优化说明

指标探针

PerformanceMetrics 会记录导入生命周期 mark、EventBus 触发次数、viewbox 变化次数和变更元素数量。

它会包装 eventBus.fire，但不改变返回值、监听优先级、事件传播或错误处理行为。用户可以通过 performance.metrics.sink 获取指标快照。

Renderer Path 缓存

PerformanceBpmnRenderer 继承 bpmn-js/lib/draw/BpmnRenderer，通过 PathCache 提供可选 path 缓存。

shape 缓存 key 包含绝对 x/y 坐标，因为 bpmn-js 的 shape path 会被 connection docking 使用。这样可以避免拖拽或建模后旧 shape path 影响连接锚点。

受保护的图形增量更新

PerformanceGraphicsFactory 继承 diagram-js/lib/core/GraphicsFactory，可针对孤立位置变化执行 transform-only 更新。

该快速路径刻意收窄。带 incoming、outgoing、boundary attachers 或 host 的元素都会回退到上游完整重绘路径，确保 connection docking 正确。

视口 Hide 模式

ViewportManager 维护一个简单的 SpatialIndex，支持低风险 hide 模式。

所有图形仍然保持物化，因此 elementRegistry.getGraphics() 稳定可用。视口外元素只通过 display: none 隐藏，并且在 saveSVG.start 前会物化全部元素。

Dirty 跟踪

DirtyUpdateTracker 监听 command stack 和 elements.changed 事件，记录 position、bounds、waypoints、changed 等粗粒度 dirty 类型。

它不会替代 CommandStack 行为，只为其他性能服务提供安全提示。

Pointer 事件合并入口

PointerEventCoalescer 会记录高频 pointer 事件，并提供可选的按帧合并辅助能力，用于后续交互优化。

当前默认不启用 pointer 事件合并。

清理

PerformanceCleanup 会在 import、clear 和 destroy 生命周期中清理视口索引、pointer 队列、dirty 状态和指标引用。

目录结构

performance-bpmn-js/
  assets/
    performance-bpmn-js.css
  examples/
    vue-vite/
      index.html
      package.json
      src/
      vite.config.js
  lib/
    index.js
    Viewer.js
    NavigatedViewer.js
    Modeler.js
    BaseViewer.js
    BaseModeler.js
    performance/
      index.js
      config.js
      cleanup/
      core/
      draw/
      interaction/
      metrics/
      modeling/
  test/
    performance/
      fixture-generator.js
      benchmark-runner.js
      fixtures/
      baseline/

模块映射

性能 didi 模块注册以下服务：

{
  __init__: [
    'performanceMetrics',
    'viewportManager',
    'pointerEventCoalescer',
    'dirtyUpdateTracker',
    'performanceCleanup'
  ],

  bpmnRenderer: [ 'type', PerformanceBpmnRenderer ],
  graphicsFactory: [ 'type', PerformanceGraphicsFactory ],

  performanceMetrics: [ 'type', PerformanceMetrics ],
  viewportManager: [ 'type', ViewportManager ],
  pointerEventCoalescer: [ 'type', PointerEventCoalescer ],
  dirtyUpdateTracker: [ 'type', DirtyUpdateTracker ],
  performanceCleanup: [ 'type', PerformanceCleanup ]
}

用户的 additionalModules 仍会在内置模块之后应用，因此用户可以通过同名服务覆盖这些性能服务。

Vue + Vite 示例

npm install
npm run example:vue

构建示例：

npm run example:vue:build

示例位于 examples/vue-vite。它从 performance-bpmn-js/lib/Modeler 导入 Modeler，加载一个小型 BPMN 图，展示指标，并提供 Reload、Fit 和 SVG 操作。

基准测试

生成样例文件：

npm run benchmark:fixtures -- --size S

准备基准测试元数据：

npm run benchmark -- --package performance-bpmn-js

当前 runner 会记录样例文件哈希、规模、环境信息和占位测量字段。后续可在此基础上接入浏览器自动化，采集导入、拖拽、交互和内存指标。

验证清单

发布行为变更前建议验证：

• Viewer / NavigatedViewer / Modeler 构造
• importXML warnings 与生命周期事件
• saveXML 和 saveSVG
• additionalModules 服务覆盖行为
• 自定义 renderer 优先级行为
• 拖拽带连接元素时的连接锚点
• clear() 和 destroy() 清理
• Vue + Vite 示例构建
• npm pack --dry-run

已知限制

• 当前仅实现 hide 视口模式。
• detach、lazy、分块导入和首屏优先导入仍作为后续能力保留。
• cacheMarkers 已在配置中声明，但尚未实现。
• PointerEventCoalescer 当前作为辅助服务存在，默认未接入 bpmn-js 交互服务。