通过本文逐步熟悉bpmn-js。
快速介绍：
bpmn.js是一个BPMN2.0渲染工具包和web建模器。使用JavaScript编写，在不需要后端服务器支持的前提下向现代浏览器内嵌入BPMN2.0流程图。这使得它很容易的嵌入到任何web应用中。
这个库既可以是web查看器也可以是web建模器。使用查看器将BPMN2.0流程图嵌入到你的应用中并可以使用数据丰富你的流程图。使用建模器在你的应用内部创建BPMN2.0流程图。
下文将向您介绍如何使用该库，并深入了解其内部结构。也就是说，这两个组件促成了该库的高度模块化和可扩展的结构。
本文包含以下内容：
● 如何使用库
• 嵌入查看器（预打包）
• 自己制作模型（通过npm）
● 理解bpmn-js内部
• 流程图交互/建模(流程图-js)
• BPMN元模型(bpmn-moddle)
• 将事物整合在一起(bpmn-js)
● 进一步探索
如何使用库
有两种方法在你的应用中使用bpmn.js。库的预打包版本可以让你在任何网站中快速添加BPMN。npm版本的设置更加复杂，但允许您访问单个库组件，并更容易扩展。
本节将概述这两种方法。首先我们来介绍如何向网站中嵌入一个预打包的BPMN查看器。之后，展示如何通过npm创建一个BPMN建模器。
嵌入预打包查看器
通过一个简单的script标签引入就可以将预打包的BPMN查看器嵌入你的网站
<!-- BPMN 流程图容器 -->
<div id="canvas"></div>
<!-- 使用 CDN 路径 或者本地 bpmn-js 路径 -->
<script src="https://unpkg.com/bpmn-js@0.27.0-1/dist/bpmn-viewer.development.js"></script>
通过引入的BPMNjs变量，可以使BPMN查看器可用。我们可以通过下面这段js来引入一个BPMN流程图。
<script>
// 你即将要展示的流程图
var bpmnXML;
// BpmnJS是BPMN查看器实例
var viewer = new BpmnJS({ container: '#canvas' });
// 导入BPMN 2.0流程图
viewer.importXML(bpmnXML, function(err) {
if (err) {
//导入失败 ！
} else {
// 导入成功！
var canvas = viewer.get('canvas');
canvas.zoom('fit-viewport');
}
});
</script>
该代码片段使用Viewer#importXML API显示预加载的BPMN 2.0图。导入图是异步的，一旦完成，查看器将通过回调通知我们结果。
导入后，我们可以通过Viewer#get访问各种图表服务。在上面的代码片段中，我们与画布交互以使图适合当前可用的视图大小。
通常，通过AJAX动态加载BPMN 2.0图更实用。这可以使用纯JavaScript(如下所示)或通过实用程序库(如jQuery)实现，后者提供了更方便的api。
<script>
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
if (xhr.readyState === 4) {
viewer.importXML(xhr.response, function(err) {
// ...
});
}
};
xhr.open('GET', 'path-to-diagram.bpmn', true);
xhr.send(null);
</script>
查看预打包的示例以及我们的初学者示例，了解更多信息。
创建属于自己的建模器
如果你想要围绕库做一些定制化，需要使用npm来使用库。这种方法有很多优点，比如可以访问单个库组件。它还使我们能够更好地控制部分打包查看器/建模器。需要使用Webpack (>=2) or Rollup来打包bpmn-js和我们的应用。
以下大致遵循modeler示例，使用该库创建BPMN建模器。
引入库
首先，通过npm安装bpmn.js
npm install bpmn-js
然后，通过ES import获得BPMN建模器
import Modeler from 'bpmn-js/lib/Modeler';
// 创建一个建模器
var modeler = new Modeler({ container: '#canvas' });
// 导入流程图
modeler.importXML(bpmnXML, function(err) {
// ...
});
同样的，需要在你的html中提供一个id声明的画布元素，以便建模器能够向画布内渲染。
添加样式
当将建模器嵌入网页时，要引入diagram-js样式以及BPMN图标字体。它们都随bpms -js发行版一起在dist/assets文件夹下提供。
<link rel="stylesheet" href="bpmn-js/dist/assets/diagram-js.css" />
<link rel="stylesheet" href="bpmn-js/dist/assets/bpmn-font/css/bpmn-.css" />
添加样式表可以确保图元素获得适当的样式化，背景板以及画板显示BPMN图标
浏览器打包
bpmn.js及其依赖由ES模块分发。使用ES模块打包器Webpack (>=2) 或者 Rollup来打包bpmn.js和你的应用。可以通过打包例子来学习更多相关。
与生命周期事件挂钩
事件允许您钩入建模器的生命周期以及图交互。下面的代码片段展示了一般情况下如何捕获元素的更改和建模操作。
modeler.on('commandStack.changed', function() {
// 建模或执行撤销/重做操作
});
modeler.on('element.changed', function(event) {
var element = event.element;
// 元素改变触发
})
使用Viewer#on注册事件或者扩展模块中的事件总线。使用 Viewer#off 来停止监听事件。请查看交互示例，以查看监听动作中的事件。
建模器的扩展
在实际使用的过程中，你可以用additionalModules选项来扩展查看器和建模器。允许您使用自定义模块来修改或替换现有的功能。
import OriginModule from 'diagram-js-origin';
// 创建一个建模器
var modeler = new Modeler({
container: '#canvas',
additionalModules: [
OriginModule,
require('./custom-rules'),
require('./custom-context-pad')
]
});
一个模块（比较：模块系统部分）是一个单元，定义了一个或多个服务。这些服务配置了bpmn.js或者提供了额外的功能。也就是通过接入流程图的生命周期来实现的。
一些模块，例如： diagram-js-origin 或 diagram-js-minimap提供了通用的用户界面添加。内置的bpmn-js模块，例如：such as bpmn rules 或 modeling提供了高定制的BPMN功能。
常用扩展BPMN建模器的方法是添加“自定义建模规则”。这样，您可以限制或扩展用户的建模操作。
扩展的其他例子有:
● 添加自定义元素
● 自定义面板/内容面板
● 自定义形状的渲染
查看bpms -js-example项目，了解更多工具包扩展展示案例。
构建自定义发行版
如果你想要针对你自定义的建模器和查看器创建预打包版本，请参 custom-bundle example这个例子。如果你定制了大量的功能但是希望以简单的方式交付给用户的话，这可能会给到你帮助。
理解bpmn-js内部
本节探讨一些bpmn-js的内部结构。
如下面的架构图所示，bpmn-js构建在两个重要的库之上:diagram-js和bpmn-moddle。
我们使用diagram-js 来绘制形状和连接。它为我们提供了与这些图形元素交互的方法，同时也提供了额外的工具例如overlays来帮助用户构建更为强大的查看器。对于更高级的建模情况，提供了提供了背景板、调色板和重做/撤消等功能。
bpmn-moddle清楚BPMN2.0元模型，元模型定义在BPMN2.0规范之上。它允许我们读写BPMN 2.0模式兼容的XML文档，获得关于图形和连接的相关信息并绘制出来。
在这两个库之上，bpmn.js定义了BPMN的细节，比如外观、建模规则和工具（如调色板）。我们将在下面的段落中详细介绍各个组件。
图交互/建模(diagram-js)
diagram-js是一个工具箱，用于在web上显示和修改图表。它允许我们渲染视觉元素并在它们之上构建交互体验。它为我们提供了一个非常简单的模块系统，用于构建特殊的服务和服务的依赖注入。这个系统还提供了一些核心服务，这些服务实现了图的基本内容。
此外，diagram-js为图形元素及其关系定义了一个数据模型。
模块系统
再下一层，diagram-js使用依赖注入(DI)来连接和发现图组件。这个机制是建立在node-di之上的。
在diagram-js上下文中讨论模块时，我们指的是提供命名服务及其实现的单元。从这个意义上说，服务是一个函数或实例，它可以使用其他服务在图的上下文中执行某些操作。
下面显示了一个与生命周期事件挂钩的服务。它通过eventBus注册一个事件来实现，eventBus是另一个著名的服务:
function MyLoggingPlugin(eventBus) {
eventBus.on('element.changed', function(event) {
console.log('element ', event.element, ' changed');
});
}
// 确保依赖项名称在缩小后仍然可用
MyLoggingPlugin.$inject = [ 'eventBus' ];
我们必须使用模块定义唯一名称发布服务:
import CoreModule from 'diagram-js/lib/core';
// 作为一个模块导入
export default {
__depends__: [ CoreModule ], // {2}
__init__: [ 'myLoggingPlugin' ], // {3}
myLoggingPlugin: [ 'type', MyLoggingPlugin ] // {1}
};
该定义告诉DI基础设施，该服务名为myLoggingPlugin {1}，它依赖于diagram-js核心模块{2} 并且服务应该在创建关系图{3}时初始化。要了解更多细节，请查看node-di的文档。
我们现在可以通过我们的自定义模块引导diagram-js
要将模块插入bpmn-js，可以使用additionalModules选项，如扩展Modeler部分所示。
核心服务
bpmn-js核心是围绕一些基本服务构建的:
● Canvas -提供了添加和删除图形元素的api;处理元素生命周期，并提供用于缩放和滚动的api。
● EventBus -该库的全局通信通道具有防火和遗忘策略。可以订阅各种事件，并在事件发出后立即采取行动。事件总线帮助我们解耦关注点并模块化功能，以便新特性能够轻松地与现有行为挂钩。
● ElementFactory -根据bpmn-js的内部数据模型创建形状和连接的工厂。
● ElementRegistry—知道添加到图中的所有元素，并提供api来根据id检索元素及其图形表示。
● GraphicsFactory -负责创建图形和连接的图形表示。实际的外观是由渲染器定义的，即绘制模块中的DefaultRenderer。
数据模型
实际上，diagram-js实现了一个由形状和连接组成的简单数据模型。
数据模型要点:形状和连接
一个形状有父节点、子节点列表以及传入和传出连接列表。
一个连接有父节点、源节点和目标节点，指向一个形状。
ElementRegistry负责根据该模型创建形状和连接。
在建模过程中，建模服务将根据用户操作更新元素关系。
辅助服务(即工具箱)
除了数据模型及其核心服务之外，diagram-js还提供了丰富的辅助工具工具箱。
CommandStack-负责建模过程中的重做和撤销。
● ContextPad-提供一个元素的上下文操作。
● Overlays——提供api来附加额外的信息到图元素。
● Modeling——提供用于更新画布上的元素(移动、删除)的api
● Palette
…
让我们继续讨论幕后发生的BPMN魔法。
BPMN元模型(bpmn-moddle)
bpmn-moddle封装了BPMN 2.0元模型，为我们提供了读写BPMN 2.0 XML文档的工具。在导入时，它将XML文档解析为JavaScript对象树。在建模过程中对该树进行编辑和验证，然后在用户希望保存图时将其导出回BPMN 2.0 XML。因为bpmn-moddle封装了有关BPMN的知识，我们能够在导入和建模期间进行验证。根据结果，我们可以约束某些建模操作，并向用户输出有用的错误消息和警告。
就像bpmn-js一样，bpmn-moddle的基础也是建立在两个库之上的:
● moddle提供了一种用JavaScript定义元模型的简洁方法
● 基于moddle读写XML文档的model-xml
从本质上讲，bpmn-moddle将BPMN规范作为元模型添加进来，并为BPMN模式验证提供了一个简单的接口。从库的角度来看，它提供了以下API:
● fromXML -从给定的XML字符串创建BPMN树
● toXML - 向BPMN 2.0 XML编写BPMN对象树
BPMN元模型对于bpmn -js是必不可少的，因为它允许我们验证我们使用的BPMN 2.0文档，提供正确的建模规则，并导出所有遵循BPMN模型的人都能理解的有效BPMN文档。
把东西连接起来(bpmn-js)
我们学过bpms -js是建立在diagram-js和bpms -moddle之上的。它将两者联系在一起，并添加BPMN外观。这包括BPMN调色板、BPMN背景板以及BPMN 2.0特定规则。在本节中，我们将解释它在建模的不同阶段是如何工作的。
当我们导入BPMN 2.0文档时，bpmn-moddle会将其从XML解析为对象树。bpmn-js呈现该树的所有可见元素，即在画布上创建各自的形状和连接。因此，它将BPMN元素和图形元素联系在一起。这将产生一个结构，如下所示，用于初始事件形状。
{
id: 'StartEvent_1',
x: 100,
y: 100,
width: 50,
height: 50,
businessObject: {
$attrs: Object
$parent: {
$attrs: Object
$parent: ModdleElement
$type: 'bpmn:Process'
flowElements: Array[1]
id: 'Process_1'
isExecutable: false
}
$type: 'bpmn:StartEvent'
id: 'StartEvent_1'
}
}
您可以通过businessObject属性从每个图形元素访问底层BPMN类型。
由于BpmnRenderer,bpmn -js也知道每个BPMN元素的样子。通过插入渲染周期，您还可以定义单个BPMN元素的自定义表示。
一旦导入完成，我们就可以开始建模了。我们使用规则来允许或不允许某些建模操作。这些规则由BpmnRules定义。我们将这些规则基于OMG定义的BPMN 2.0标准。然而，正如前面提到的，其他人也可能与规则评估挂钩，以贡献不同的行为。
建模模块捆绑了BPMN 2.0相关的建模功能。它添加了BPMN 2.0特定的建模行为，并负责在用户执行的每个建模操作中更新BPMN 2.0文档树(cf. BpmnUpdater)。请查看它，以更深入地了解规则、行为和BPMN更新周期。
当纯粹从库的角度来看bpmn-js时，值得一提的是它可以有三种形式:
● Viewer展示图
● NavigatedViewer显示和导航BPMN图
● Modeler 建模BPMN图
版本之间的唯一区别是它们捆绑了不同的功能集。NavigatedViewer添加了用于导航画布的模块，Modeler添加了大量用于创建、编辑和与画布上的元素交互的功能。
