全网最详bpmn.js教材-properties-panel篇(上)

前言



Q: bpmn.js是什么? 🤔️

”

bpmn.js是一个BPMN2.0渲染工具包和web建模器, 使得画流程图的功能在前端来完成.



Q: 我为何要写该系列的教材? 🤔️

”

由于公司业务的须要于是要在项目中使用到bpmn.js,可是因为bpmn.js的开发者是国外友人, 所以国内对这方面的教材不多, 也没有详细的文档. 因此不少使用方式不少坑都得本身去找.在将其琢磨完以后, 决定写一系列关于它的教材来帮助更多bpmn.js的使用者或者是期于找到一种好的绘制流程图的开发者. 同时也是本身对其的一种巩固.

因为是系列的文章, 因此更新的可能会比较频繁, 您要是无心间刷到了且不是您所须要的还请谅解😊.

不求赞👍不求心❤️. 只但愿能对你有一点小小的帮助.

Properties-panel篇

你们在了解了前一篇properties的内容后, 应该对属性有了一个大概的认识吧.

这一章节让咱们来讲说properties-panel 😄...

其实在前面的《全网最详bpmn.js教材-基础篇》中已经提到了怎样使用properties-panel, 不过那里只是简单的教了你们如何引用而没有细说, 如今就让我来详细为你们讲解一下它具体的使用方法。

经过这一章节的阅读你能够学习到:

• Properties-panel的基本使用
• 扩展使用 Properties-panel

Properties-panel的基本使用

properties-panel本质上是bpmn.js的一个扩展, 它实现了BPMN 2.0建模器，使你能够经过属性面板编辑与执行相关的属性。

官方的一个截图:

1. 安装properties-panel

在以前的文章中有不少内容没有介绍清楚, 在这一章中我会仔细的介绍.

首先是安装上.

若是你想要使用它的话, 得本身安装一下:

$ npm install --save bpmn-js-properties-panel
复制代码

一样的记得在项目中引入样式:

import 'bpmn-js-properties-panel/dist/assets/bpmn-js-properties-panel.css' // 右边工具栏样式
复制代码

使用上, 得在html代码中提供一个标签做为盛放它的容器:

<div id="js-properties-panel" class="panel"></div>
复制代码

以后, 在构建BpmnModeler的时候添加上它:

// 这里引入的是右侧属性栏这个框
import propertiesPanelModule from 'bpmn-js-properties-panel'
// 而这个引入的是右侧属性栏里的内容
import propertiesProviderModule from 'bpmn-js-properties-panel/lib/provider/camunda'

const bpmnModeler = new BpmnModeler({
	//添加控制板
  propertiesPanel: {
        parent: '#js-properties-panel'
  },
  additionalModules: [
  	propertiesPanelModule,
  	propertiesProviderModule
  ]
})
复制代码

在以前的文章中我没有弄清楚propertiesPanelModule和propertiesProviderModule的做用, 致使将左侧工具栏和右侧属性的引用方式写错了, 如今已经在<全网最详bpmn.js教材-基础篇>中更正了...抱歉...

2. 安装camunda-bpmn-moddle

还有一点, 若是你想使用Camunda BPM来执行相关属性的话, 也得安装一个叫camunda-bpmn-moddle的扩展:

$ npm install --save camunda-bpmn-moddle
复制代码

将其添加到项目中:

// 右侧属性栏
import propertiesPanelModule from 'bpmn-js-properties-panel'
import propertiesProviderModule from 'bpmn-js-properties-panel/lib/provider/camunda'
 // 一个描述的json
import camundaModdleDescriptor from 'camunda-bpmn-moddle/resources/camunda'

const bpmnModeler = new BpmnModeler({
	//添加控制板
  propertiesPanel: {
  	parent: '#js-properties-panel'
  },
  additionalModules: [
  	propertiesPanelModule,
  	propertiesProviderModule
  ],
  moddleExtensions: {
    //若是要在属性面板中维护camunda：XXX属性，则须要此 
    camunda: camundaModdleDescriptor
  }
})
复制代码

(Camunda BPM是一个用于工做流执行引擎和工做流自动化的解决方案, 在这里就不展开说了)

而camunda-bpmn-moddle的做用就是告诉使用者camunda:XXX扩展属性。

说了这个咱也听不懂啊, 来讲点具体的吧, 好比你已经安装并已经在项目上使用了properties-panel以后, 打开页面, 随便选择一个节点(就拿开始节点来讲吧), 会出现四个选项卡(tab)能让你修改属性, 若是你没有安装camunda并引用camundaModdleDescriptor的话, 使用后面三个功能, 控制台就会报错了:

它会告诉你unknown type <camunda:FormData>...

由于其实你查看camunda-bpmn-moddle/resources/camunda的源码就会发现, 这其实就是一个json文件, 里面存放的就是对各个属性的描述. 咱们在后面自定义properties-panel的时候也会须要编写这样的一个json文件, 待会你就知道了.

3. 实际使用效果

OK...让咱们来实际使用看看它们有什么效果.

为了方便查看, 我给bpmnModeler绑定一个commandStack.changed事件, 在图形每次改变的时候将最新的xml打印出来.

(关于事件绑定的部分能够看<全网最详bpmn.js教材-事件篇>)

以后仍是点击开始节点, 并修改一些属性. 结果发现你修改的属性居然同步更新到了xml上面:

Good Body! 你是否是想到了什么?!

没错! 和上一篇文章的updateProperties方法是否是很像呢, 都是可以更新属性到xml上.

扩展使用Properties-panel

与palette, contextPad等自定义方式同样, Properties-panel也能够在默认的基础上进行修改, 它容许你加上一些自定义的属性.

不过官方把它叫作Properties Panel Extension, 好像更专业一些...不过无所谓了, 你知道是那个意思就好了.

官方这里也提供了一个例子: properties-panel-extension

我其实也是跟着官方的这个例子来探索它是怎么使用的.

首先让咱们来明确一点, 还记得咱们在使用原版properties-panel的时候, 引入了两个东西吗?

// 这里引入的是右侧属性栏这个框
import propertiesPanelModule from 'bpmn-js-properties-panel'
// 而这个引入的是右侧属性栏里的内容
import propertiesProviderModule from 'bpmn-js-properties-panel/lib/provider/camunda'

additionalModules: [
  propertiesPanelModule,
  propertiesProviderModule
]
复制代码

我研究了一下, 若是你不引入第一个只引入第二个的话, 属性栏就出不来了.

而若是你只引入第一个不引入第二个的话, 就会报错...

我理解一下大概是这样意思:

• 第一个 propertiesPanelModule表示的是属性栏这个框, 就是告诉别人这里要有个属性栏;
• 第二个 propertiesProviderModule表示的是属性栏里的内容, 也就是点击不一样的 element该显示什么内容.

看到这, 你是否是有了点思路呢? 嘻嘻😁...

既然这样的话, 咱们只须要重写propertiesProviderModule就能够了, 不要引入官方提供的(也就是从bpmn-js-properties-panel/lib/provider/camunda引入的), 而是自定义一个propertiesProviderModule来显示本身想要的内容.

1. 前期准备

properties-panel的内容可能有点多, 我就另外建立了一个项目来作案例分析.

项目仍是用vue来编写, 不过其实你只要有点基础都能看得懂.

先让咱们来看看要实现的效果:

• 点击开始节点的时候, 右侧的属性栏中有 General和权限两个选项卡(tab);
• 权限这个选项卡中有一个组, 名为 编辑权限;
• 编辑权限下会有一个属性, 名为 标题, 它是一个输入框;
• 修改该开始节点的信息, 能将属性关联到 xml中

让咱们在components文件夹下建立一个properties-panel-extension文件夹, 这里用来放咱们要自定义的属性内容.

而后在properties-panel-extension下再新建一个descriptors和provider文件夹.

• descriptors是用来放一些描述的 json文件
• provider放你要自定义的选项卡(tab)

因为General是它本来就有的一个选项卡, 因此咱们能够不用管它, 如今咱们想要自定义的是一个名叫“权限”的选项卡, 因此我在provider文件夹下又建立了一个authority文件夹, 里面用来放咱们选项卡的内容...

以后一顿操做, 让目录变成了这样:

AuthorityPropertiesProvider.js这个文件就是来编写权限这个选项卡的, 它是咱们须要编写的主要文件.

parts这个文件夹就是来放各个组下的子元素, 好比这里的“标题”, 我给它取名为TitleProps.

2. provider返回值介绍

若是你看到上面那么多的文件感受眼花缭乱的话, 请没必要慌张😂, 这是正常的反应...

因此为了后面更好的讲解, 我决定先来介绍一下provider的返回值与页面的结构是如何对应上的.

经过上面👆的图, 咱们能够看出来:

1. 每一个 provider下都会有一个 tabs数组(一个 tab就是一个选项卡)
2. 每一个 tab下都会有一个 groups数组(一个 group就是一个组)
3. 每一个 group下都会有一堆 props, 它们多是输入框, 也多是下拉框

OK...如今是否是好理解多了😄...

因此咱们只须要在AuthorityPropertiesProvider.js中返回一个这样的结构就能够了:

/*-选项卡 | -组 | -属性*/
return [
    { // 选项卡
        id: 'general',
        groups: [] // 组
    },
    { // 选项卡
        id: 'authority',
        groups: [
            { // 组
                id: 'edit-authority', // 组id
                entries: [
                    { // 单个props
                        id: 'title',
                        description : '权限的标题',
                        label : '标题',
                        modelProperty : 'title'
                    }
                ]
            }
        ]
    }
]
复制代码

3. 编写AuthorityPropertiesProvider.js代码

编写的顺序我打算从上往下一层一层的讲.

因此先来看看AuthorityPropertiesProvider.js整体是要返回什么.

// AuthorityPropertiesProvider.js

import inherits from 'inherits';
// 引入自带的PropertiesActivator, 由于咱们要用到它来处理eventBus
import PropertiesActivator from 'bpmn-js-properties-panel/lib/PropertiesActivator';

export default function AuthorityPropertiesProvider( eventBus, bpmnFactory, canvas, // 这里是要用到什么就引入什么 elementRegistry, translate ) {
    PropertiesActivator.call(this, eventBus);
    
    this.getTabs = function (element) {
        var generalTab = {};
        var authorityTab = {};
        return [
            generalTab,
            authorityTab
        ];
    }
}

inherits(AuthorityPropertiesProvider, PropertiesActivator);
复制代码

这样看, 结构是否是也很清晰呢? 😊

咱们其实就是要重写里面的getTabs方法, 返回咱们须要的tab.

每一个tab都有固定的属性:

var authorityTab = {
        id: 'authority',
        label: '权限',
        groups: createAuthorityTabGroups(element)
    };
复制代码

你必须得准守以上命名规则来写哈😣...

编写createAuthorityTabGroups函数代码

在肯定了tab以后, 咱们须要告诉它里面有哪些组, 这时候就能够建立一个createAuthorityTabGroups函数来返回想要的组.

// AuthorityPropertiesProvider.js

import TitleProps from './parts/TitleProps';

function createAuthorityTabGroups(element) {
    var editAuthorityGroup = {
        id: 'edit-authority',
        label: '编辑权限',
        entries: [] // 属性集合
    }
    // 每一个属性都有本身的props方法
    TitleProps(editAuthorityGroup, element);
    // OtherProps1(editAuthorityGroup, element);
    // OtherProps2(editAuthorityGroup, element);
    
    return [
        editAuthorityGroup
    ];
}
复制代码

好比上面👆我就返回了一个编辑权限的组.

而各个属性是放到组的entries字段下的...

咿呀, 这里怎么没看到给entries数组添加属性呢?

可是下面好像有一个TitleProps呀, 这个是干吗的🤔?

看着有点像用来添加属性的...

编写TitleProps.js代码

是的, 因为属性可能会被多处用到, 因此我将它单独提了出来, 放到了parts这个文件夹下, 后面就能够往里面不停的加属性了.

这个属性的方法有点特别, 它接收两个参数:

• 一个组
• 当前 element

由于同一个属性可能存在于不一样的组里, 因此能够传入一个组.

另外可能要经过元素的类型来作各类判断, 因此能够传入当前元素.

// /parts/TitleProps.js
import entryFactory from 'bpmn-js-properties-panel/lib/factory/EntryFactory';

import { is } from 'bpmn-js/lib/util/ModelUtil';

export default function(group, element) {
  if (is(element, 'bpmn:StartEvent')) { // 能够在这里作类型判断
    group.entries.push(entryFactory.textField({
      id : 'title',
      description : '权限的标题',
      label : '标题',
      modelProperty : 'title'
    }));
  }
}
复制代码

啊😺, 原来entries是在每个Props里添加属性的啊🙈...

在push方法里, 你得告诉它是要添加一个什么类型的Props.

主要就是经过entryFactory, 例如这里就是返回一个text类型的输入框.

有时候你想要的不只仅是输入框怎么办🙈?

不要紧, entryFactory自己为你提供了不少类型.

Ctrl + 左键查看entryFactory的源码, 你能够发现有不少类型:

OK...

至此, 咱们的自定义authorityTab权限选项卡就写完了 😊!

你若是想添加其它的选项卡用上面👆的方式就能够了...

编写generalTab代码

上面👆的权限选项卡是咱们自定义的一些内容, 若是你想要使用官方提供的一些tab和属性怎么办呢?

generalTab就为你演示了该如何作...

首先一样的, generalTab须要长成这样:

var generalTab = {
    id: 'general',
    label: 'General',
    groups: createGeneralTabGroups(element, bpmnFactory, canvas, elementRegistry, translate)
};
复制代码

咱们看到createGeneralTabGroups好像传递了不少参数进去, 那是由于咱们要在里面用到它们, 而这些参数在构造AuthorityPropertiesProvider函数的时候就引入进来的...

来看看createGeneralTabGroups是如何编写的:

// AuthorityPropertiesProvider.js

import idProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/IdProps';
import nameProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/NameProps';
import processProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/ProcessProps';
import linkProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/LinkProps';
import eventProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/EventProps';
import documentationProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/DocumentationProps';

function createGeneralTabGroups(element, bpmnFactory, canvas, elementRegistry, translate) {

    var generalGroup = {
        id: 'general',
        label: 'General',
        entries: []
    };
    idProps(generalGroup, element, translate);
    nameProps(generalGroup, element, bpmnFactory, canvas, translate);
    processProps(generalGroup, element, translate);

    var detailsGroup = {
        id: 'details',
        label: 'Details',
        entries: []
    };
    linkProps(detailsGroup, element, translate);
    eventProps(detailsGroup, element, bpmnFactory, elementRegistry, translate);

    var documentationGroup = {
        id: 'documentation',
        label: 'Documentation',
        entries: []
    };

    documentationProps(documentationGroup, element, bpmnFactory, translate);

    return [
        generalGroup,
        detailsGroup,
        documentationGroup
    ];
}
复制代码

在general中, 导出了三个组, 而每一个组中的Props都是bpmn-js-properties-panel/lib/provider/bpmn/parts这个文件夹中拿的...

一样的, 你查找它的源码, 也能发现不少其它的Props, 你须要什么, 直接取来用就能够了[狗头].

AuthorityPropertiesProvider.js完整代码

额, 要不仍是贴下完整的代码?

其实也很少, 91行:

import inherits from 'inherits';

import PropertiesActivator from 'bpmn-js-properties-panel/lib/PropertiesActivator';


import idProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/IdProps';
import nameProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/NameProps';
import processProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/ProcessProps';
import linkProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/LinkProps';
import eventProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/EventProps';
import documentationProps from 'bpmn-js-properties-panel/lib/provider/bpmn/parts/DocumentationProps';

import TitleProps from './parts/TitleProps';

function createGeneralTabGroups(element, bpmnFactory, canvas, elementRegistry, translate) {

    var generalGroup = {
        id: 'general',
        label: 'General',
        entries: []
    };
    idProps(generalGroup, element, translate);
    nameProps(generalGroup, element, bpmnFactory, canvas, translate);
    processProps(generalGroup, element, translate);

    var detailsGroup = {
        id: 'details',
        label: 'Details',
        entries: []
    };
    linkProps(detailsGroup, element, translate);
    eventProps(detailsGroup, element, bpmnFactory, elementRegistry, translate);

    var documentationGroup = {
        id: 'documentation',
        label: 'Documentation',
        entries: []
    };

    documentationProps(documentationGroup, element, bpmnFactory, translate);

    return [
        generalGroup,
        detailsGroup,
        documentationGroup
    ];
}

function createAuthorityTabGroups(element) {
    var editAuthorityGroup = {
        id: 'edit-authority',
        label: '编辑权限',
        entries: []
    }

    // 每一个属性都有本身的props方法
    TitleProps(editAuthorityGroup, element);
    // OtherProps1(editAuthorityGroup, element);
    // OtherProps2(editAuthorityGroup, element);

    return [
        editAuthorityGroup
    ];
}

export default function AuthorityPropertiesProvider( eventBus, bpmnFactory, canvas, // 这里是要用到什么就引入什么 elementRegistry, translate ) {
    PropertiesActivator.call(this, eventBus);

    this.getTabs = function(element) {
        var generalTab = {
            id: 'general',
            label: 'General',
            groups: createGeneralTabGroups(element, bpmnFactory, canvas, elementRegistry, translate)
        };

        var authorityTab = {
            id: 'authority',
            label: '权限',
            groups: createAuthorityTabGroups(element)
        };
        return [
            generalTab,
            authorityTab
        ];
    }
}

inherits(AuthorityPropertiesProvider, PropertiesActivator);

复制代码

通过咱们的拆分, 感受异常简单有木有 😊 !

(没错, 霖呆呆就是这么一个简单善良如白纸通常的男子😳...)

4. 编写authority.json代码

OK...其实到了这里就接近尾声了, 可是其实还有很是关键的一步要作...

刚刚咱们自定义了一个叫作权限的选项卡, 还有一个叫title的属性, 而且还指定了只有StartEvent中出现, 那么此时咱们还得在一个叫authority.json的文件中作一些说明.

(之因此取名为authority.json, 是由于我添加的选项卡叫权限, 这个命名随便你本身)

它长成这样:

{
    "name": "Authority",
    "prefix": "authority",
    "uri": "http://authority",
    "xml": {
      "tagAlias": "lowerCase"
    },
    "associations": [],
    "types": [
      {
        "name": "LinDaiDaiStartEvent",
        "extends": [
          "bpmn:StartEvent"
        ],
        "properties": [
          {
            "name": "title",
            "isAttr": true,
            "type": "String"
          }
        ]
      }
    ]
  }
复制代码

在这个描述文件中, 咱们定义了一个新类型LinDaiDaiStartEvent, 该类型扩展了该类型bpmn:StartEvent并向其添加“title”属性做为属性。

注️: 有必要在描述符中定义要扩展的元素。若是但愿该属性对全部bpmn元素均有效，则能够扩展bpmn:BaseElement️

例如🌰这样:

...
{
  "name": "LinDaiDaiStartEvent",
  "extends": [
    "bpmn:BaseElement"
  ],
  ...
}
复制代码

5. 导出并使用AuthorityPropertiesProvider

通过一轮翻云覆雨(C + V)的操做, 终于将大头给写完了...

下面让咱们来看看怎么用它...

在/provider/authority文件夹下建立一个index.js用于导出:

import AuthorityPropertiesProvider from './AuthorityPropertiesProvider';

export default {
  __init__: [ 'propertiesProvider' ],
  propertiesProvider: [ 'type', AuthorityPropertiesProvider ]
};
复制代码

看着很眼熟啊, 哈哈😄... 和contextPad什么的好像...

用于演示, 我在项目中建立了一个properties-panel-extension.vue, 并在其中引用上bpmn.js和咱们的刚刚编写好的authority.

<template>
  <div class="containers" ref="content">
    <div class="canvas" ref="canvas"></div>
    <div id="js-properties-panel" class="panel"></div>
  </div>
</template>
<script> // 原有的 properties-panel 这个框 import propertiesPanelModule from 'bpmn-js-properties-panel' // 自定义的 properties-panel内容 import propertiesProviderModule from './properties-panel-extension/provider/authority'; // 引入描述文件 import authorityModdleDescriptor from './properties-panel-extension/descriptors/authority' ... additionalModules: [ // 右边的工具栏(固定引入) propertiesPanelModule, // 自定义右边工做栏的内容 propertiesProviderModule ], moddleExtensions: { // camunda: camundaModdleDescriptor, authority: authorityModdleDescriptor } ... </script>
复制代码

看到这里, 相信你对properties-panel又有了一个新的认识...

恭喜你🎉🎉🎉

霖呆呆非常欣慰...

后语

上面👆教材案例的代码地址: LinDaiDai/bpmn-vue-properties-panel

关于properties-panel要讲的内容有点多, 因此我将其分为了两篇来写.

还有几天过年了🧨...霖呆呆有个小小的愿望, 就是在年前能破200的粉丝...

卑微博主在线恳求关注...哈哈哈😂

(看着好心酸)

最后, 若是你也对bpmn.js 感兴趣能够进咱们的bpmn.js交流群👇👇👇, 共同窗习, 共同进步.

关注霖呆呆的公众号, 选择“其它”菜单中的“bpmn.js群”便可😁

LinDaiDai公众号二维码.jpg

系列所有目录请查看此处: 《全网最详bpmn.js教材》

系列相关推荐:

《全网最详bpmn.js教材-基础篇》

《全网最详bpmn.js教材-事件篇》

《全网最详bpmn.js教材-renderer篇》

《全网最详bpmn.js教材-contextPad篇》

《全网最详bpmn.js教材-自定义palette篇》

《全网最详bpmn.js教材-编辑、删除节点篇》

《全网最详bpmn.js教材-封装组件篇》

《全网最详bpmn.js教材-properties篇》