@szjy/workflow

项目概述

@szjy/workflow 是基于 Vue 3、TypeScript 和 BPMN.js 开发的工作流设计器组件库，提供了完整的工作流程设计、表单权限配置和电子签章管理能力。该组件库适用于需要实现业务流程设计与管理的企业应用系统，特别是在建筑信息化领域。

目录结构

workflow/
├── examples/                # 示例代码
│   ├── App.vue             # 示例应用
│   └── ui/                 # 示例UI组件
├── packages/
│   ├── components/         # 核心组件
│   │   ├── Hello/          # Hello组件(示例)
│   │   └── Workflow/       # 工作流组件
│   │       ├── activiti/   # Activiti引擎配置
│   │       ├── biz-logic/  # 业务逻辑实现
│   │       ├── components/ # 子组件
│   │       ├── palette/    # 自定义画板
│   │       ├── store/      # 状态管理
│   │       └── utils/      # 工具函数
│   └── i18n/               # 国际化资源
│       ├── en_US/          # 英文
│       └── zh_CN/          # 中文
├── public/                 # 静态资源
└── index.ts                # 入口文件

环境要求

• Node.js >= 16
• Vue 3
• TypeScript >= 4.8
• Vite >= 5.0.0

安装

# npm
npm install @szjy/workflow

# yarn
yarn add @szjy/workflow

# pnpm
pnpm add @szjy/workflow

快速开始

全局注册

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import SWorkflow from '@szjy/workflow'
import '@szjy/workflow/dist/style.css'

const app = createApp(App)
app.use(SWorkflow).mount('#app')

组件使用

<template>
  <sz-workflow ref="workflowRef" @init="onInitWorkflow">
    <!-- 自定义工具栏插槽 -->
    <template #TOOLBAR_SUFFIX>
      <button>导入模板</button>
    </template>
    
    <!-- 自定义用户选择器插槽 -->
    <template #USER_CHOOSER_SUFFIX="userProps">
      <user-chooser :user-id="userProps.userId" :on-change="userProps.onChange"></user-chooser>
    </template>
  </sz-workflow>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const workflowRef = ref()

// 初始化回调
const onInitWorkflow = (modeler) => {
  console.log('工作流编辑器初始化完成', modeler)
}

// 获取工作流XML
const getXml = async () => {
  const xml = await workflowRef.value?.getWorkflowXml()
  console.log(xml)
}

// 导入工作流XML
const importXml = (xml) => {
  workflowRef.value?.initXmlToStore(xml)
}
</script>

核心功能

工作流设计器

提供基于BPMN.js的可视化流程设计器，支持拖拽式流程设计。

表单权限配置

支持为工作流各节点配置表单字段的权限（编辑、只读、隐藏）。

电子签章管理

支持配置电子签章的位置、样式和触发条件。

单元格关联配置

支持为工作流各节点配置单元格（字段）的关联操作，包括记录操作时间和操作人员。可以分别为当前用户和其他用户配置不同的关联规则。

国际化支持

内置中文和英文语言包，支持多语言配置。

API文档

属性

| 属性名 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | mode | string | 'normal' | 工作流模式，可选值：'normal'(编辑模式)、'preview'(预览模式) | | height | string | '' | 工作流设计器高度，为空时自动计算 |

事件

| 事件名 | 参数 | 说明 | |-------|------|------| | init | modeler | 工作流编辑器初始化完成时触发 |

方法

| 方法名 | 参数 | 返回值 | 说明 | |-------|------|-------|------| | getWorkflowXml | - | Promise<string> | 获取当前工作流的XML定义 | | initXmlToStore | xml: string | Promise<void> | 导入工作流XML定义 | | updateProcessId | processId: string | void | 更新流程ID | | getPermissionJSON | - | PermissionJSONLike | 获取表单权限配置 | | setPermissionByFields | permissonJSON: PermissionJSONLike, fields: FieldItemType[] | void | 设置表单权限配置 | | updatePermFields | fields: FieldItemType[] | void | 更新表单字段列表 | | getEsignJSON | - | EsignJSONLike | 获取电子签章配置 | | setEsignConfig | esignJSON: EsignJSONLike | void | 设置电子签章配置 | | getCellAssociatedJSON | - | CellAssociatedJSONLike | 获取单元格关联配置 | | setCellAssociatedConfig | cellAssociatedJSON: CellAssociatedJSONLike, fields: FieldItemType[] | void | 设置单元格关联配置 | | updateCellAssociatedFields | fields: FieldItemType[] | void | 更新单元格关联配置的字段列表 |

插槽

| 插槽名 | 参数 | 说明 | |-------|------|------| | TOOLBAR_PREFIX | - | 工具栏前置内容 | | TOOLBAR_SUFFIX | - | 工具栏后置内容 | | USER_CHOOSER_SUFFIX | { userId, onChange } | 用户选择器自定义渲染 | | FORMID_CHOOSER_SUFFIX | { formFieldId, onChange } | 表单字段选择器自定义渲染 |

工作流架构

flowchart TD
  A[工作流组件] --> B[BPMN编辑器]
  A --> C[属性面板]
  A --> D[工具栏]
  
  B --> E[Activiti引擎]
  B --> F[自定义画板]
  
  C --> G[节点属性]
  C --> H[表单权限]
  C --> I[电子签章]
  
  G --> J[基础属性]
  G --> K[监听器]
  
  H --> L[字段权限]
  H --> M[条件配置]
  
  D --> N[保存/导出]
  D --> O[放大/缩小]
  D --> P[对齐工具]

使用示例

基础工作流设计

<template>
  <sz-workflow ref="workflowRef"></sz-workflow>
  <button @click="saveWorkflow">保存流程</button>
</template>

<script setup>
import { ref } from 'vue'

const workflowRef = ref()

const saveWorkflow = async () => {
  const xml = await workflowRef.value?.getWorkflowXml()
  console.log('流程定义XML:', xml)
  // 保存到服务器的代码
}
</script>

表单权限配置

// 字段列表
const fields = [
  { id: 'field1', name: '姓名' },
  { id: 'field2', name: '部门' },
  { id: 'field3', name: '职位' }
]

// 权限配置
const permissions = {
  createFieldPermission: {
    assigneeFieldPermissionMap: [
      { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'EDITABLE' },
      { key: 'field2', fieldId: 'field2', fieldName: '部门', permission: 'EDITABLE' },
      { key: 'field3', fieldId: 'field3', fieldName: '职位', permission: 'EDITABLE' }
    ],
    othersFieldPermissionMap: [
      { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'ALL_READ_ONLY' },
      { key: 'field2', fieldId: 'field2', fieldName: '部门', permission: 'ALL_READ_ONLY' },
      { key: 'field3', fieldId: 'field3', fieldName: '职位', permission: 'HIDDEN' }
    ]
  },
  taskToFieldPermissionMap: {
    'Activity_1': {
      assigneeFieldPermissionMap: [
        { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'EDITABLE' }
      ],
      othersFieldPermissionMap: [
        { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'ALL_READ_ONLY' }
      ]
    }
  }
}

// 设置权限
workflowRef.value?.setPermissionByFields(permissions, fields)

单元格关联配置

// 字段列表
const fields = [
  { id: 'field1', name: '操作时间' },
  { id: 'field2', name: '操作人员' },
  { id: 'field3', name: '审批意见' }
]

// 单元格关联配置
const cellAssociatedConfig = {
  'Activity_1': {
    current: {
      'field1': { opTime: true },        // 当前用户操作时记录操作时间
      'field2': { opUser: true }         // 当前用户操作时记录操作人员
    },
    others: {
      'field3': { opTime: true, opUser: true }  // 其他用户操作时同时记录时间和人员
    }
  },
  'Activity_2': {
    current: {
      'field1': { opTime: true }
    }
  }
}

// 设置单元格关联配置
workflowRef.value?.setCellAssociatedConfig(cellAssociatedConfig, fields)

// 获取单元格关联配置
const config = workflowRef.value?.getCellAssociatedJSON()
console.log('单元格关联配置:', config)

配置说明：

• opTime: 是否记录操作时间
• opUser: 是否记录操作人员
• current: 当前用户的配置
• others: 其他用户的配置

项目开发

本地开发

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建
pnpm build

# 发布
pnpm release

代码规范

项目使用 TypeScript 强类型检查，请确保所有代码通过类型检查。

提交流程

使用 commit-and-tag-version 进行版本管理，提交前请确保代码已通过测试。

常见问题

Q: 为什么工作流编辑器无法保存？

A: 请检查是否调用了 getWorkflowXml() 方法获取XML内容，该方法返回Promise，需要使用 await 或 .then() 处理。

Q: 如何自定义节点图标？

A: 可以通过扩展 BPMN.js 的 PaletteProvider 来添加自定义节点。具体可参考 packages/components/Workflow/palette/ 下的实现。

Q: 如何处理表单权限与后端的交互？

A: 可通过 getPermissionJSON() 获取权限配置JSON，然后发送至后端保存。加载时通过 setPermissionByFields() 方法恢复配置。

参考文档

1. BPMN.js 官方文档
2. Vue 3 组件开发指南
3. Activiti 工作流引擎文档
4. Vue 3 组合式 API 参考
5. Vite 构建工具文档