# workflow-vue3

**Repository Path**: ding-zhiwen/workflow-vue3

## Basic Information

- **Project Name**: workflow-vue3
- **Description**: 使用flowvue重构 +vue3 + ts + elementUI-plus 实现的前端工作流框架，内容非常简单。内涵汉 .net  工作流框架 Elsa 汉化版 #.net #Elsa #workflow #工作流
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 14
- **Forks**: 1
- **Created**: 2025-01-05
- **Last Updated**: 2025-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Elsa, 工作流, workflow, Vue

## README

# Vue Flow 工作流设计器

一个基于 Vue 3 + TypeScript + Vue Flow 的现代化工作流设计器，支持拖拽创建、编辑和连接各种工作流节点，并可将设计结果导出为 Elsa 框架格式。

## ✨ 功能特性
![输入图片说明](src/assets/%E5%BE%AE%E4%BF%A1%E5%9B%BE%E7%89%87_20250907155143_72_95.png)
### 🎯 核心功能
- **拖拽创建节点**：从左侧菜单拖拽节点到画布
- **节点连接**：支持节点之间的连线，带动画效果
- **节点编辑**：双击节点编辑属性（审批人、抄送人）
- **节点删除**：右键删除节点和连接线
- **工作流导入导出**：支持JSON格式的导入导出
- **Elsa格式转换**：双向转换Vue Flow ↔ Elsa格式
- **Elsa格式导出**：一键转换为Elsa工作流框架格式


# Workflow for Elsa 使用指南

## 📖 简介

`workflow_for_elsa` 是一个基于 Vue 3 的工作流设计器组件，专为 Elsa 工作流引擎设计。它提供了直观的拖拽界面，让您可以轻松创建、编辑和管理工作流程。

## 🚀 快速开始

### 安装

```bash
npm install workflow_for_elsa
```

### 基础使用

```vue
<template>
  <div>
    <WorkflowDesigner />
  </div>
</template>

<script setup>
import { WorkflowDesigner } from 'workflow_for_elsa'
import 'workflow_for_elsa/dist/style.css'
</script>
```

## 🎯 核心功能

### 1. 拖拽创建节点
- 从左侧节点库拖拽节点到画布
- 支持开始、审批、抄送、结束四种节点类型
- 自动计算节点位置

### 2. 节点连接
- 拖拽节点连接点创建连接线
- 支持动画效果
- 可自定义连接线样式

### 3. 节点编辑
- 双击节点编辑属性
- 审批节点：设置审批人
- 抄送节点：设置抄送人

### 4. 数据管理
- 支持导入/导出 JSON 格式
- 支持 Elsa 格式转换
- 实时数据变化监听

## 📋 详细使用

### 基础配置

```vue
<template>
  <WorkflowDesigner 
    :initial-nodes="nodes"
    :initial-edges="edges"
    @workflow-change="handleChange"
  />
</template>

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

const nodes = ref([
  {
    id: 'start-1',
    type: 'start',
    position: { x: 100, y: 100 },
    data: { label: '开始', type: 'start' }
  }
])

const edges = ref([])

const handleChange = (nodes, edges) => {
  console.log('工作流变化:', { nodes, edges })
}
</script>
```

### 只读模式

```vue
<template>
  <WorkflowDesigner 
    :readonly="true"
    :initial-nodes="nodes"
    :initial-edges="edges"
  />
</template>
```

### 自定义配置

```vue
<template>
  <WorkflowDesigner 
    :initial-nodes="nodes"
    :initial-edges="edges"
    :node-types="['start', 'approve', 'end']"
    :person-list="personList"
    :theme="'dark'"
    :primary-color="'#ff6b6b'"
    :show-toolbar="true"
    :show-sidebar="true"
    :allow-drag="true"
    :allow-edit="true"
    :allow-delete="true"
    @workflow-change="handleWorkflowChange"
    @save-elsa="handleSaveElsa"
  />
</template>

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

const nodes = ref([])
const edges = ref([])

const personList = ref([
  { id: '1', name: '张三', department: '技术部', position: '高级工程师' },
  { id: '2', name: '李四', department: '技术部', position: '工程师' }
])

const handleWorkflowChange = (nodes, edges) => {
  console.log('工作流变化:', { nodes, edges })
}

const handleSaveElsa = (workflow) => {
  console.log('保存Elsa格式:', workflow)
}
</script>
```

## 🎪 事件处理

### 数据变化事件

```vue
<template>
  <WorkflowDesigner 
    @workflow-change="handleWorkflowChange"
    @node-add="handleNodeAdd"
    @node-edit="handleNodeEdit"
    @node-delete="handleNodeDelete"
    @edge-add="handleEdgeAdd"
    @edge-delete="handleEdgeDelete"
  />
</template>

<script setup>
const handleWorkflowChange = (nodes, edges) => {
  console.log('工作流变化:', { nodes, edges })
  // 可以在这里保存数据到服务器
}

const handleNodeAdd = (node) => {
  console.log('节点添加:', node)
}

const handleNodeEdit = (node) => {
  console.log('节点编辑:', node)
}

const handleNodeDelete = (nodeId) => {
  console.log('节点删除:', nodeId)
}

const handleEdgeAdd = (edge) => {
  console.log('边添加:', edge)
}

const handleEdgeDelete = (edgeId) => {
  console.log('边删除:', edgeId)
}
</script>
```

### 保存事件

```vue
<template>
  <WorkflowDesigner 
    @save-elsa="handleSaveElsa"
    @save-json="handleSaveJson"
  />
</template>

<script setup>
const handleSaveElsa = (workflow) => {
  console.log('保存Elsa格式:', workflow)
  // 发送到Elsa服务器
  fetch('/api/workflows', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(workflow)
  })
}

const handleSaveJson = (workflow) => {
  console.log('保存JSON格式:', workflow)
  // 保存到本地存储
  localStorage.setItem('workflow', JSON.stringify(workflow))
}
</script>
```

## 🎨 样式自定义

### CSS 变量

```css
:root {
  --workflow-primary-color: #1890ff;
  --workflow-success-color: #52c41a;
  --workflow-warning-color: #faad14;
  --workflow-danger-color: #ff4d4f;
}
```

### 自定义样式

```css
/* 自定义节点样式 */
.vue-flow__node {
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* 自定义连接线样式 */
.vue-flow__edge-path {
  stroke-width: 3;
  stroke: #1890ff;
}

/* 自定义工具栏样式 */
.workflow-designer .toolbar {
  background: #f5f5f5;
  border-bottom: 1px solid #e0e0e0;
}
```

## 🔧 高级功能

### 自定义工具栏按钮

```vue
<template>
  <WorkflowDesigner 
    :toolbar-buttons="customButtons"
  />
</template>

<script setup>
const customButtons = ref([
  {
    key: 'custom-save',
    label: '自定义保存',
    icon: 'Document',
    type: 'primary',
    onClick: () => {
      console.log('自定义保存')
      // 自定义保存逻辑
    }
  },
  {
    key: 'custom-export',
    label: '导出PDF',
    icon: 'Download',
    type: 'success',
    onClick: () => {
      console.log('导出PDF')
      // 导出PDF逻辑
    }
  }
])
</script>
```

### 自定义人员列表

```vue
<template>
  <WorkflowDesigner 
    :person-list="personList"
  />
</template>

<script setup>
const personList = ref([
  { id: '1', name: '张三', department: '技术部', position: '高级工程师' },
  { id: '2', name: '李四', department: '技术部', position: '工程师' },
  { id: '3', name: '王五', department: '产品部', position: '产品经理' },
  { id: '4', name: '赵六', department: '产品部', position: '产品专员' }
])
</script>
```

### 主题切换

```vue
<template>
  <div>
    <el-button @click="toggleTheme">
      切换主题: {{ theme }}
    </el-button>
    <WorkflowDesigner 
      :theme="theme"
      :primary-color="primaryColor"
    />
  </div>
</template>

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

const theme = ref('light')
const primaryColor = ref('#1890ff')

const toggleTheme = () => {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
  primaryColor.value = theme.value === 'light' ? '#1890ff' : '#ff6b6b'
}
</script>
```

## 🔄 Elsa 集成

### 导入 Elsa 工作流

```vue
<template>
  <WorkflowDesigner 
    @import="handleImport"
  />
</template>

<script setup>
const handleImport = (data) => {
  console.log('导入数据:', data)
  // 处理导入的Elsa工作流数据
}
</script>
```

### 导出到 Elsa

```vue
<template>
  <WorkflowDesigner 
    @save-elsa="handleSaveElsa"
  />
</template>

<script setup>
const handleSaveElsa = (workflow) => {
  // 发送到Elsa服务器
  fetch('/api/elsa/workflows', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(workflow)
  })
  .then(response => response.json())
  .then(data => {
    console.log('Elsa工作流保存成功:', data)
  })
  .catch(error => {
    console.error('保存失败:', error)
  })
}
</script>
```

## 📱 响应式设计

### 移动端适配

```vue
<template>
  <div class="workflow-container">
    <WorkflowDesigner 
      :show-sidebar="!isMobile"
      :show-toolbar="true"
    />
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const isMobile = ref(false)

const checkMobile = () => {
  isMobile.value = window.innerWidth < 768
}

onMounted(() => {
  checkMobile()
  window.addEventListener('resize', checkMobile)
})

onUnmounted(() => {
  window.removeEventListener('resize', checkMobile)
})
</script>

<style scoped>
.workflow-container {
  height: 100vh;
  overflow: hidden;
}

@media (max-width: 768px) {
  .workflow-container {
    height: 100vh;
  }
}
</style>
```

## 🐛 常见问题

### 1. 组件不显示
**问题**: 组件渲染为空白
**解决**: 
- 确保已导入样式文件
- 检查所有依赖是否正确安装
- 确认Vue版本兼容性

### 2. 拖拽不工作
**问题**: 无法拖拽节点
**解决**:
- 检查 `allowDrag` 属性
- 确保不在只读模式
- 检查浏览器控制台错误

### 3. 样式不生效
**问题**: 自定义样式不显示
**解决**:
- 检查CSS选择器优先级
- 使用 `:deep()` 选择器
- 确认样式文件导入顺序

### 4. 事件不触发
**问题**: 事件监听器不工作
**解决**:
- 检查事件名称拼写
- 确认事件处理函数定义
- 检查Vue版本兼容性

## 📚 完整示例

### 完整的工作流应用

```vue
<template>
  <div class="workflow-app">
    <header class="app-header">
      <h1>工作流设计器</h1>
      <div class="header-actions">
        <el-button @click="saveWorkflow" type="primary">
          保存工作流
        </el-button>
        <el-button @click="loadWorkflow">
          加载工作流
        </el-button>
      </div>
    </header>
    
    <main class="app-main">
      <WorkflowDesigner 
        :initial-nodes="nodes"
        :initial-edges="edges"
        :person-list="personList"
        :theme="theme"
        :primary-color="primaryColor"
        @workflow-change="handleWorkflowChange"
        @save-elsa="handleSaveElsa"
        @save-json="handleSaveJson"
      />
    </main>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { WorkflowDesigner } from 'workflow_for_elsa'
import { ElMessage } from 'element-plus'

const nodes = ref([])
const edges = ref([])
const theme = ref('light')
const primaryColor = ref('#1890ff')

const personList = ref([
  { id: '1', name: '张三', department: '技术部', position: '高级工程师' },
  { id: '2', name: '李四', department: '技术部', position: '工程师' },
  { id: '3', name: '王五', department: '产品部', position: '产品经理' }
])

const handleWorkflowChange = (newNodes, newEdges) => {
  nodes.value = newNodes
  edges.value = newEdges
  console.log('工作流变化:', { nodes: newNodes, edges: newEdges })
}

const handleSaveElsa = (workflow) => {
  console.log('保存Elsa格式:', workflow)
  ElMessage.success('Elsa格式已保存到控制台')
}

const handleSaveJson = (workflow) => {
  console.log('保存JSON格式:', workflow)
  ElMessage.success('JSON格式已保存到控制台')
}

const saveWorkflow = () => {
  const workflow = {
    nodes: nodes.value,
    edges: edges.value,
    timestamp: new Date().toISOString()
  }
  
  // 保存到本地存储
  localStorage.setItem('workflow', JSON.stringify(workflow))
  ElMessage.success('工作流已保存')
}

const loadWorkflow = () => {
  const saved = localStorage.getItem('workflow')
  if (saved) {
    const workflow = JSON.parse(saved)
    nodes.value = workflow.nodes || []
    edges.value = workflow.edges || []
    ElMessage.success('工作流已加载')
  } else {
    ElMessage.warning('没有找到保存的工作流')
  }
}

onMounted(() => {
  // 加载保存的工作流
  loadWorkflow()
})
</script>

<style scoped>
.workflow-app {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.app-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0 20px;
  height: 60px;
  background: #fff;
  border-bottom: 1px solid #e0e0e0;
}

.app-main {
  flex: 1;
  overflow: hidden;
}

.header-actions {
  display: flex;
  gap: 10px;
}
</style>
```

## 🔗 相关链接

- [NPM 包地址](https://www.npmjs.com/package/workflow_for_elsa)
- [GitHub 仓库](https://github.com/your-username/workflow_for_elsa)
- [API 参考文档](API_REFERENCE.md)
- [Elsa 工作流引擎](https://elsaworkflows.io/)

## 📞 技术支持

如有问题或建议，请通过以下方式联系：
- 发送邮件至 1145480106@qq.com

---

**祝您使用愉快！** 🎉
**你也可以直接拉取源码，在之上进行更改,源码说明 👇**

### 📦 节点类型
- **开始节点**：绿色圆形图标，表示工作流开始
- **审批节点**：蓝色方形图标，可设置审批人
- **抄送节点**：黄色方形图标，可设置抄送人
- **结束节点**：红色圆形图标，表示工作流结束

### 🎨 界面特性
- **左右布局**：左侧节点库，右侧设计画布
- **工具栏**：清空、导入、导出、保存等功能
- **人员选择**：支持下拉选择和树形选择两种方式
- **响应式设计**：适配不同屏幕尺寸
- **现代化UI**：基于Element Plus的美观界面

## 🚀 快速开始

### 环境要求
- Node.js >= 16.0.0
- npm >= 8.0.0

### 安装依赖
```bash
npm install
```

### 启动开发服务器
```bash
npm run dev
```

### 构建生产版本
```bash
npm run build
```

### 预览生产版本
```bash
npm run preview
```

## 📖 使用指南

### 基本操作

#### 1. 添加节点
- 从左侧菜单拖拽节点类型到画布
- 节点会自动添加到拖拽位置
- 支持实时预览拖拽效果

#### 2. 连接节点
- 从一个节点的连接点拖拽到另一个节点
- 支持平滑的连线动画
- 连接线宽度为3px，颜色为蓝色

#### 3. 编辑节点
- **审批节点**：双击编辑审批人
- **抄送节点**：双击编辑抄送人
- 支持人员选择弹窗，提供下拉和树形两种选择方式

#### 4. 删除操作
- **删除节点**：右键点击节点选择删除
- **删除连接线**：右键点击连接线选择删除
- 删除节点时会自动删除相关连线

#### 5. 工具栏操作
- **清空画布**：删除所有节点和连线
- **导出工作流**：保存为JSON文件
- **导入工作流**：从JSON文件加载
- **导入Elsa格式**：从Elsa工作流文件导入并转换为Vue Flow格式
- **保存为Elsa格式**：转换为Elsa工作流格式并打印到控制台

### 人员选择功能

#### 下拉选择模式
- 支持多选和搜索过滤
- 显示人员姓名、部门、职位信息
- 已选择人员以标签形式显示

#### 树形选择模式
- 按部门分组显示人员
- 支持部门和个人选择
- 更直观的层级结构

## 🏗️ 项目结构

```
src/
├── components/
│   └── VueFlow/
│       ├── FullWorkflowDesigner.vue    # 主设计器组件
│       ├── PersonSelector.vue          # 人员选择弹窗组件
│       ├── nodes/                      # 节点组件目录
│       │   ├── StartNode.vue          # 开始节点
│       │   ├── ApproveNode.vue        # 审批节点
│       │   ├── SendNode.vue           # 抄送节点
│       │   └── EndNode.vue            # 结束节点
│       └── README.md                  # 组件说明文档
├── App.vue                            # 根组件
├── main.ts                           # 入口文件
└── style.css                         # 全局样式
```

## 🛠️ 技术栈

- **Vue 3** - 渐进式JavaScript框架
- **TypeScript** - 类型安全的JavaScript超集
- **Vue Flow** - 流程图和节点编辑器
- **Element Plus** - Vue 3 UI组件库
- **Vite** - 快速的前端构建工具

### 核心依赖
```json
{
  "@vue-flow/core": "^1.46.3",
  "@vue-flow/background": "^1.3.2",
  "@vue-flow/controls": "^1.1.3",
  "@vue-flow/minimap": "^1.5.4",
  "element-plus": "^2.9.1",
  "vue": "^3.5.13"
}
```

## 📋 API 文档

### 主要组件

#### FullWorkflowDesigner
主工作流设计器组件，提供完整的工作流设计功能。

**Props**: 无

**Events**:
- `@save-elsa`: 保存为Elsa格式时触发

#### PersonSelector
人员选择弹窗组件，支持下拉和树形两种选择方式。

**Props**:
- `modelValue: boolean` - 弹窗显示状态
- `title: string` - 弹窗标题
- `selectedPersonIds?: string[]` - 已选择的人员ID列表

**Events**:
- `@update:modelValue` - 更新弹窗显示状态
- `@confirm` - 确认选择时触发，参数为人员ID和人员信息

### 节点类型

#### StartNode
开始节点组件，表示工作流的起始点。

**Features**:
- 绿色圆形图标
- 底部连接点
- 不可编辑属性

#### ApproveNode
审批节点组件，用于设置审批流程。

**Features**:
- 蓝色方形图标
- 顶部和底部连接点
- 可编辑审批人属性
- 支持人员选择弹窗

#### SendNode
抄送节点组件，用于设置抄送通知。

**Features**:
- 黄色方形图标
- 顶部和底部连接点
- 可编辑抄送人属性
- 支持人员选择弹窗

#### EndNode
结束节点组件，表示工作流的结束点。

**Features**:
- 红色圆形图标
- 顶部连接点
- 不可编辑属性

## 🔧 自定义开发

### 添加新节点类型

1. 在 `nodes/` 目录下创建新的节点组件
2. 在 `FullWorkflowDesigner.vue` 中注册新节点类型
3. 在 `nodeTypes` 数组中添加节点配置

示例：
```typescript
// 在 customNodeTypes 中添加
const customNodeTypes: any = {
  // ... 现有节点
  custom: CustomNode
}

// 在 nodeTypes 中添加
const nodeTypes = [
  // ... 现有类型
  { type: 'custom', label: '自定义', icon: 'CustomIcon' }
]
```

### 自定义节点属性

每个节点组件都可以通过 `props.data` 接收自定义数据：

```typescript
const props = defineProps<{
  data?: {
    label?: string
    customProperty?: any
  }
}>()
```

### 样式定制

组件使用CSS变量和scoped样式，可以通过以下方式定制：

- 修改节点颜色：编辑各节点组件中的CSS变量
- 调整布局：修改 `FullWorkflowDesigner.vue` 中的样式
- 自定义主题：通过Element Plus主题系统

## 📊 Elsa格式转换

### 双向转换支持

本项目支持Vue Flow格式与Elsa格式之间的双向转换：

- **Vue Flow → Elsa**：将设计的工作流转换为Elsa格式
- **Elsa → Vue Flow**：将Elsa工作流导入并转换为Vue Flow格式

### 导出到Elsa格式

#### 数据结构

导出的Elsa格式包含以下主要部分：

```typescript
{
  id: string,                    // 工作流ID
  name: string,                  // 工作流名称
  description: string,           // 工作流描述
  version: number,              // 版本号
  activities: Activity[],       // 活动列表
  connections: Connection[],    // 连接列表
  variables: any[],            // 变量列表
  customAttributes: any[],     // 自定义属性
  persistenceBehavior: {       // 持久化行为配置
    // ... 持久化相关配置
  }
}
```

#### 活动类型映射

| Vue Flow节点类型 | Elsa活动类型 | 说明 |
|----------------|-------------|------|
| start | Start | 工作流开始 |
| approve | Approval | 审批活动 |
| send | SendEmail | 邮件发送活动 |
| end | Finish | 工作流结束 |

### 从Elsa格式导入

#### 支持的Elsa活动类型

- **Start** → 开始节点
- **Approval** → 审批节点（自动提取审批人信息）
- **SendEmail** → 抄送节点（自动提取收件人信息）
- **Finish** → 结束节点

#### 自动属性映射

- **审批人信息**：从`Approver`属性自动提取
- **收件人信息**：从`Recipients`属性自动提取
- **位置信息**：从`x`、`y`坐标自动映射
- **连接关系**：从`connections`数组自动重建

#### 导入流程

1. 点击工具栏的"导入Elsa格式"按钮
2. 选择Elsa工作流JSON文件
3. 系统自动解析并转换为Vue Flow格式
4. 在画布中显示转换后的工作流

#### 错误处理

- **格式验证**：检查Elsa格式的完整性
- **类型识别**：智能识别未知活动类型
- **属性提取**：安全提取节点属性
- **错误提示**：详细的错误信息和解决建议


## 📄 更新日志

### v1.0.0 (2024-01-XX)
- ✨ 初始版本发布
- 🎯 支持四种节点类型（开始、审批、抄送、结束）
- 🖱️ 拖拽创建和编辑节点
- 🔗 节点连接和连接线管理
- 👥 人员选择弹窗（下拉和树形选择）
- 💾 工作流导入导出功能
- 🔄 Elsa格式数据转换
- 🎨 现代化UI设计
- 📱 响应式布局支持

---

**享受使用 Vue Flow 工作流设计器！** 🎉