smart-bpmn-designer

init smart-bpmn-designer

一、引擎打包指令：

• npm run designer

二、载入指令：

• npm install --save smart-bpmn-designer

• npm install --save bpmn-js@7.2.1

• npm install --save bpmn-js-properties-panel@0.46.0

或者/使用淘宝镜像拉取

• cnpm install --save smart-bpmn-designer

• cnpm install --save bpmn-js@7.2.1

• cnpm install --save bpmn-js-properties-panel@0.46.0

备注： 可能存在部分依赖报错，安提醒加载即可

三、项目中 main.js 中引入如下指令：

import { designer, previewer } from 'smart-bpmn-designer'
Vue.use(designer)
Vue.use(previewer)

也可以追加 option 配置用于修改接口请求代理前缀(例如 NG 代理前缀)

const option = {
  bpmnProxy: '/NginxProxy'
}
Vue.use(designer, option)
Vue.use(previewer, option)

也可以追加 option 配置用汉化包配置文件； 汉化包模板文件可在此处获取：'smart-bpmn-designer/lib/asp-bpmn-designer/costumZh.js'

import costumsZh from './costumZh.js'
const option = {
  customZh: costumsZh
}
Vue.use(designer, option)
Vue.use(previewer, option)

可按需引入，设计器组件-designer，和预览组件-previewer

点击下载 bpmnInjectMixins.js

点击下载 costumZh.js

四、代码使用：

引入项目后，可直接复制下述代码使用，开启流程图绘制（设计器组件）

<AspSmartBpmDesigner></AspSmartBpmDesigner>

或者复制下述代码，用于只展示流程图预览（预览组件）

<AspSmartBpmnPreviewer></AspSmartBpmnPreviewer>

属性说明

序号	属性	类型	说明	适用组件	是否必填	默认值
1	height	String	设置引擎编辑高度	desinger/previewer	否	100%
2	isViewer	Boolean	设置是否为预览模式，编排引擎开启预览模式	desinger	否	false
3	isback	Boolean	设置是否有返回按钮	desinger/previewer	否	true
4	bpmnModel	Object	设置设计器引擎必要参数，具体配置参数见下详述：bpmnModel 属性赋值	desinger/previewer	是	-
5	bpmModdleType	String	设置设计器引擎使用哪种解析引擎： activiti，flowable，camunda	desinger/previewer	否	flowable
6	flowNodeType	String	设置设计器引擎使用模型展示属性区域，可支持项目自定义（customPanel），目前默认支持nodePanel/apiPanel/defaultPanel/customPanel	desinger	否	defaultPanel
7	bpmnConfig	Array	设置设计器引擎可呈现流程元素，可配置变量参考 asp_getBpmnConfigs()方法返回的bpmnConfigs数据的 Key，设置['All']可展示所有	desinger	否	默认呈现基础流程元素节点
8	buttonConfig	Array	设置设计器引擎头部工具栏，支持配置展示，可配置变量参考 asp_getBpmnConfigs()方法返回默认数据的 bpmnButtonConfigs，可按项目需求进行增减	desinger/previewer	否	默认呈现内置操作按钮
9	paddingHeight	String	设置预览引擎可呈现流程图的内嵌高度，无需填写单位（默认为px）	previewer	否	默认内嵌高度为0
10	beforeHttp	Function	设计器引擎接口请求前置事件，三个参数：{ alias-标识，type-操作类型，bpmnModel-引擎必要参数见4 }；httpObject-请求体（包含请求方式post/get等，请求url，请求参数等）；callba-回调函数，参数：httpObject；	desinger	否	-
11	afterHttp	Function	设计器引擎接口请求后置事件，三个参数：{ alias-标识，type-操作类型，bpmnModel-引擎必要参数见4，httpObject-请求体（包含请求方式post/get等，请求url，请求参数等） }；response-接口响应体；callba-回调函数，参数：response；	desinger	否	-
12	onbind	Function	设计器引擎操作回调绑定事件，参数：{ alias-标识，type-操作类型，其他参数等 }；	desinger	否	-

bpmnModel 属性赋值：

• 1、设计器模型下：bpmnModel: {actModelId, flowKey, flowName }

属性说明：

1. actModelId：原生流程设计模型 ID，创建流程时系统自动生成，新增是必传；
2. flowKey：流程图 Key，创建流程图时传入
3. flowName：流程图名称，创建流程图时传入

• 2、详情预览模型下：bpmnModel: { instanceId, defId }

属性说明：（instanceId, defId 二者传其一可预览流程图）

1. instanceId：流程实例 Id，可查看流程图及历史审批记录
2. defId：流程定义 Id，只传该参数，仅可查看流程图

• 3、本地静态模拟模型下：bpmnModel: { demoDesin }

属性说明：

1. demoDesin：设计器引擎模拟器，仅在无工作流后端服务时，可通过设置 demoDesin 为 true 使用本地版进行模拟；（也可通过在 url 上配置参数 demoDesin=true 实现）

备注： 本地静态模拟模型下，因无后端服务，无法进行保存，及部分涉及接口查询的功能

五、 customPanel项目自定义：

1、自定义组件配置：

<asp-smart-bpm-designer>
    <template slot="panelTitle">
      <customTitle>自定义属性title头部</customTitle>
    </template>
    <template slot="bpmnPanel">
      <customPane> v-bind:bpmn-model="bpmnModel">自定义属性组件模块</customPane>
    </template>
  </asp-smart-bpm-designer>

2、自定义属性title头部

<template>
  <div>{{ nodeName }}</div>
</template>
<script>
import bpmnInjectMixins from 'asp-bpmn-designer/lib/asp-bpmn-designer/bpmnInjectMixins.js'
export default {
  name: 'CustomTitle',
  mixins: [bpmnInjectMixins],
  mounted () {
    this.watchModelerEvent(this)
  }
}
</script>

3、自定义属性组件模块

<template>
  <div>
    配置区域
    {{ nodeName }} - {{ componentName }}
  </div>
</template>

<script>
import bpmnInjectMixins from 'asp-bpmn-designer/lib/asp-bpmn-designer/bpmnInjectMixins.js'
export default {
  name: 'CustomPanel',
  mixins: [bpmnInjectMixins],
  mounted () {
    this.watchModelerEvent(this)
  }
}
</script>

4、常用组件API，更新bpmn流程组件

使用说明，在和标签及其子组件中可通过this.$modelerApi调用；

/**
 * 重写流程元素属性/或追加子元素
 * @param {*} modeler 流程引擎实例
 * @param {*} element 流程元素
 * @param {*} properties 属性结构（包括子元素属性结构）
 * @returns 参数不完整时 return false, 否则执行元素属性更新
 */
this.$modelerApi.updateProperties(modeler, element, properties)

注意：

不同场景和不同节点，写入的属性和子节点（/子标签）是不一样的，具体结构和场景还需遵循BPMN2.0标准协议；

范例：

1、修改节点属性

this.$modelerApi.updateProperties({ attrName: '节点属性数据，attrName为属性名称key' })

• 另一种写法：

const businessObject = this.element.businessObject // 元素实例对象
businessObject.cancelActivity = properties // 添加属性
this.$modelerApi.updateProperties(this.modeler, this.element, {}) // 更新至流程节点

• 删除节点属性，对节点元素对象businessObject直接使用delete，后进行updateProperties进行更新即可；

if (!(this.element && this.element.businessObject)) return
      delete this.element.businessObject['attrrs-父标签属性名称']
      this.$modelerApi.updateProperties(this.modeler, this.element, {})

2、为节点添加注释说明

const documentationElement = this.modeler.get('moddle').create('bpmn:Documentation', { text: '节点注释说明' })
this.$modelerApi.updateProperties({ documentation: [documentationElement] }) // 会在当前节点下生成一个<bpmn:Documentation></bpmn:Documentation>标签

3、为节点添加会签节点

let loopCharacteristics = this.element.businessObject.get('loopCharacteristics')
if (!loopCharacteristics) { // 会签节点不存在时创建会签任务节点
  loopCharacteristics = this.modeler.get('moddle').create('bpmn:MultiInstanceLoopCharacteristics', { elementVariable: 'assignee' })
}
// 修改会签任务节点上属性
loopCharacteristics.$attrs['test_attr'] = '测试增加/修改属性'
// 为会签节点元素添加子元素节点
const FormalExpression = this.modeler.get('moddle').create('bpmn:FormalExpression', {
  body: '测试子标签元素'
})
loopCharacteristics['completionCondition'] = FormalExpression
// 更新会签节点信息至流程元素
this.$modelerApi.updateModdleProperties(this.modeler, this.element, { loopCharacteristics })

效果如下：

<bpmn2:userTask id="user_task_id" name="用户任务">
  <bpmn2:multiInstanceLoopCharacteristics flowable:elementVariable="assignee" test_attr="测试增加/修改属性">
    <bpmn2:completionCondition xsi:type="bpmn2:tFormalExpression">测试子标签元素</bpmn2:completionCondition>
  </bpmn2:multiInstanceLoopCharacteristics>
</bpmn2:userTask>

5、常用API

1、获取流程元素节点数据模型(用于配置)--asp_getBpmnConfigs

asp_getBpmnConfigs()
return {
  bpmnConfigs, // 常用流程元素节点（内置），暂不支持自定义拓展
  bpmnButtonConfigs // 常用按钮配置（内置），可自定义拓展
}

2、执行头部操作栏按钮点击事件--asp_topButtonClick

/**
 * 执行头部操作栏按钮点击事件
 * @param {*} alias 按钮标识，为ButtonConfig中配置的按钮标识
 * @returns 执行点击事件
 */
asp_topButtonClick(alias)

3、执行流程数据模型更新和获取事件--asp_getBpmFlowModel()--asp_updateBpmFlowModel({流程数据模型})

// 数据模型：更新数据模型的数据--updateBpmFlowModel
asp_updateBpmFlowModel (bpmFlowModel = {})
// 数据模型：获取数据模型的数据--getBpmFlowModel
asp_getBpmFlowModel ()
return this.bpmFlowModel

六、 历史版本说明：

2024-08-09 2.1.0 更新拓展配置化--自定义组件

1、拓展自定义属性title头部；

  <customTitle>自定义属性title头部</customTitle>

2、自定义属性组件模块；

  <customPane> v-bind:bpmn-model="bpmnModel">自定义属性组件模块</customPane>

3、更新组件绑定事件，封装常用组件API；

this.$modelerApi.updateProperties(modeler, element, properties)

2023-08-12 2.0.0 更新拓展配置化

1、支持汉化包可自定义元素节点名称；

2、拓展提供钩子函数：

    // 接口请求前置事件
    beforeHttp({ alias, type, data, bpmFlowModel }, httpObject, callback) {
      callback(httpObject)
    },
    // 接口请求后置事件
    afterHttp({ alias, type, data, bpmFlowModel, httpObject }, response, callback) {
      callback(response)
    },
    // 元素节点更新前置事件
    beforeUpdateNode({ alias, type, bizObj, bpmFlowModel }, callback) {
      callback(bpmFlowModel)
    },
    // 元素节点属性初始化前置事件
    beforeInitNode({ alias, type, bizObj, bpmFlowModel }, callback) {
      callback(bpmFlowModel)
    }

3、特别说明, 初始化流程详情请求和响应处理，可通过 alias === 'initLoading' && type === 'httpLoading' ，在 beforeHttp 和 afterHttp 钩子函数中进行处理。

3.1、其中，在beforeHttp分别设置url/method/data等参数，来实现接口请求的定制。 例如：

 /**
  * 接口请求前置事件
  * 调用位置: designer\design\panel\apiPanel\index-loading\index.js
  * alias: String e.g.-initLoading save
  * type: String e.g.-httpLoading
  * data: Object bpmnModel
  * bpmFlowModel: Object bpmFlowModel
  * httpObject: Object{httpBody:Object,httpUrl:String}
  * callback: 初始化图层详情 调用必须把httpObject回传回去
 */
beforeHttp ({ alias, data, type, bpmFlowModel }, httpObject, callback) {
   // 封装获取流程图的请求
   if (alias === 'initLoading' && type === 'httpLoading') {
     const { httpUrl, httpBody } = httpObject
     const actModelId = httpBody?.bpmnModel?.actModelId
     httpObject.httpUrl = `${httpUrl}/url`
     httpObject.type = 'get' // 请求类型-post+json/post+form/get/put+json/delete+json/patch+json
     // 封装请求
     httpObject.httpBody = {}
   }
   callback(httpObject)
 }

3.2、 在afterHttp中处理响应数据，其中初始化详情数据必须进行如下处理（响应中必须提供response.data = { flowModel, xml }）： 例如：

  /**
   * 接口请求后置事件
   * 调用位置: designer\design\panel\apiPanel\index-loading\index.js
   * alias: String e.g.-initLoading save
   * type: String e.g.-httpLoading
   * data: Object bpmnModel
   * bpmnModel: Object bpmnModel
   * httpObject: Object{httpBody:Object,httpUrl:String}
   * response: Any
   * callback: 请求完成逻辑处理 e.g.-弹窗提示 关闭loading 保存刷新
  */
  afterHttp ({ alias, type, bpmnModel, httpObject }, response, callback) {
    // 手动处理初始化响应数据
    if (alias === 'initLoading' && type === 'httpLoading') {
      response.data = { flowModel, xml }
    }
    callback(response)
  }

2023-06-07 1.1.2-bate5 拓展流程元素节点

1、拓展流程元素节点，可支持动态配置； 2、优化流程元素初始化渲染机制； 3、拓展元素边界事件，支持定时器和定时器（非中断）； 4、修复已知漏洞；

2023-06-01 1.1.2-bate.3 支撑流程预览

• 可通过配置 ：bpmnModel:{ readOnly, xml} 支持直接查看流程图

2022-12-05 1.1.2 开始兼容 IE11

• wangEditor 降低到 v4，兼容 IE11
• 引入 babel-polyfill，兼容 ES5

2022-10-24 1.1.0 以下版本（不包括 1.1.0），引用方式：

1. 项目中 main.js 中引入如下指令：

import aspBpmnDesigner from 'asp-bpmn-designer'
Vue.use(aspBpmnDesigner)

2. 也可以追加 option 配置用于修改接口请求代理前缀(例如 NG 代理前缀)

const option = {
  bpmnProxy: '/NginxProxy'
}
Vue.use(aspBpmnDesigner, option)

3. 引入项目后，可直接复制下述代码使用

<aspBpmnDesigner></aspBpmnDesigner>