# liteflow流程可视化

**Repository Path**: sine/liteflow-process-visualization

## Basic Information

- **Project Name**: liteflow流程可视化
- **Description**: 基于logicflow的liteflow流程可视化设计组件
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LiteFlow Designer

> 基于 **Vue 3 + LogicFlow + ElementPlus** 的独立流程编排拖拽设计器组件，对标 [LiteFlow](https://liteflow.cc/) 规则引擎，支持可视化编排、XML / DSL / EL 格式转换、流程模拟执行，可作为 Vue3 组件库独立打包被其他项目引用。

---

## 目录

- [快速开始](#快速开始)
- [功能特性](#功能特性)
- [节点类型参考](#节点类型参考)
- [技术栈](#技术栈)
- [对外接口](#对外接口)
- [外部引用集成](#外部引用集成)
- [项目结构](#项目结构)
- [架构说明](#架构说明)
- [开发指南](#开发指南)
- [构建打包](#构建打包)
- [开发阶段](#开发阶段)

---

## 快速开始

### 环境要求

- **Node.js** >= 18
- **npm** >= 9

### 安装依赖并启动

```bash
npm install
npm run dev
```

浏览器自动打开 `http://localhost:3000`，进入流程设计器预览页。

> 开发模式下 [`views/Designer.vue`](src/views/Designer.vue) 引用 [`DesignerPanel.vue`](src/components/designer/DesignerPanel.vue)，可在此页面调试所有功能。

---

## 功能特性

### 画布操作

| 功能 | 说明 |
|------|------|
| ✅ 自动布局 | dagre LR 层次布局，节点增删后自动触发 |
| ✅ 缩放滑块 | 画布右侧纵向滑块，范围 25% ~ 200% |
| ✅ 滚轮缩放 / 平移 | 画布拖拽平移 + 鼠标滚轮缩放 |
| ✅ 网格 / 对齐线 | 背景网格 + 拖拽对齐辅助线 |
| ✅ 撤销 / 重做 | Ctrl+Z / Ctrl+Y |
| ✅ 小地图 | 画布工具栏一键开关 |
| ✅ 自适应画布 | 工具栏 fit 按钮 / 窗口尺寸变化自适应 |

### 节点操作

| 功能 | 说明 |
|------|------|
| ✅ 连线添加节点 | 边线中点 `+` 按钮追加，**唯一添加方式** |
| ✅ 选中 / 删除 | 点选高亮，Delete 键删除，自动重连上下游 |
| ✅ 复制粘贴 | Ctrl+C / Ctrl+V |
| ✅ 左侧面板 | SidePanel 展示脚本节点与流程链，InsertNodeDialog 按分类展示可插入节点 |
| ❌ 禁止拖拽 | 节点不可拖拽移动 |
| ❌ 禁止删除 | START / END 节点不可删除 |

### 边线与分支

| 功能 | 说明 |
|------|------|
| ✅ polyline 折线 | 直角折线连线，中点带 `+` 添加按钮 |
| ✅ 边线选中 | 高亮显示 + 条件表达式显示 |
| ✅ 自动聚合 | WHEN/SWITCH/IF/FOR/WHILE/ITERATOR 创建时自动生成 AND 聚合节点 |
| ✅ IF 分支 | 支持 true / false 双分支，属性面板可管理 |
| ✅ PRE / FINALLY | 前置/后置容器，仅允许在 THEN 容器内创建 |
| ✅ 递归清理 | 分支删除时递归清理到 AND 节点并重连 |
| ❌ 禁止删除边线 | 边线仅随节点删除而连带删除 |
| ❌ AND 节点受限 | AND 不可手动创建/删除 |

### 数据导入导出

| 格式 | 说明 |
|------|------|
| ✅ XML | 顶层数据模型（脚本 + 流程链），TopToolbar 导入/查看 |
| ✅ DSL | 画布工具栏导入/查看 LiteFlow 规则 DSL |
| ✅ EL | 画布工具栏导入 LiteFlow EL 表达式（链式风格） |
| ✅ JSON | FlowData 内部格式，@save / @change 事件传出 |

### 流程模拟

| 功能 | 说明 |
|------|------|
| ✅ 模拟面板 | 画布工具栏「播放」按钮打开 SimulatePanel |
| ✅ 执行模式 | 单步执行 / 自动执行（可调速度） |
| ✅ 路径高亮 | 执行路径实时高亮显示 |
| ✅ 模拟日志 | 实时模拟日志输出 |

### 对外能力

| 能力 | 说明 |
|------|------|
| ✅ `@save` 事件 | 保存时传出当前流程 XML 数据 |
| ✅ `@change` 事件 | 流程变更时实时传出最新 XML |
| ✅ `getSnapshot()` | 获取画布截图（base64 PNG） |

---

## 节点类型参考

### 流程控制 (control)

| 类型 | 名称 | 形状 | 颜色 | 说明 |
|------|------|------|------|------|
| `THEN` | 串行 | ▬ 矩形 | `#1890FF` | 顺序执行后续节点 |
| `PRE` | 前置 | ▬ 矩形 | `#1890FF` | 流程开始前串行执行 |
| `FINALLY` | 后置 | ▬ 矩形 | `#1890FF` | 流程结束后串行执行（不受异常影响） |
| `WHEN` | 并行 | ◇ 菱形 | `#1890FF` | 并行执行多个分支，需聚合 |
| `SWITCH` | 选择 | ◇ 菱形 | `#2F54EB` | 条件分支选择，需聚合 |
| `IF` | 条件 | ◇ 菱形 | `#2F54EB` | 条件判断，支持 true/false 分支 |
| `FOR` | 循环 | ⬡ 六边形 | `#531DAB` | 固定次数循环，需聚合 |
| `WHILE` | 条件循环 | ⬡ 六边形 | `#531DAB` | 条件循环，需聚合 |
| `ITERATOR` | 迭代器 | ⬡ 六边形 | `#531DAB` | 遍历集合，需聚合 |

### 业务组件 (component)

| 类型 | 名称 | 形状 | 颜色 | 说明 |
|------|------|------|------|------|
| `CMP` | 组件 | ▬ 矩形 | `#52C41A` | 普通业务组件 |
| `SCRIPT` | 脚本 | ▬ 矩形 | `#52C41A` | Groovy / JavaScript 脚本节点 |
| `SUB_FLOW` | 子流程 | ▬ 矩形 | `#52C41A` | 子流程引用节点 |

### 特殊节点 (special)

| 类型 | 名称 | 形状 | 颜色 | 说明 |
|------|------|------|------|------|
| `START` | 开始 | ● 圆形 | `#722ED1` | 流程起点（唯一，不可删除） |
| `END` | 结束 | ● 圆形 | `#FF4D4F` | 流程终点（唯一，不可删除） |
| `AND` | 聚合 | ● 圆形 | `#FAAD14` | 自动生成，不可手动操作 |

---

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue 3 | ^3.5 | 前端框架 (Composition API) |
| Vite | ^6.0 | 构建工具 + 组件库打包 |
| ElementPlus | ^2.9 | UI 组件库 |
| @logicflow/core | ^2.0 | 流程图画布核心引擎（内置 Preact） |
| @logicflow/extension | ^2.0 | 扩展（Snapshot / MiniMap 等） |
| dagre | ^0.8 | 自动布局算法（LR 层次布局，LogicFlow 内置） |
| CodeMirror 6 | ^6.0 | 脚本编辑器 |
| highlight.js | ^11.11 | DSL/XML 语法高亮 |

---

## 对外接口

### Props

| Prop | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `data` | `string \| object` | 否 | `null` | 流程 XML 字符串或 FlowModel 对象 |
| `readonly` | `boolean` | 否 | `false` | 只读模式 |
| `defaultLanguage` | `string` | 否 | `'java'` | 脚本默认语言 |

### Events

| Event | 参数 | 说明 |
|-------|------|------|
| `@save` | `(xml: string)` | 用户点击保存时触发，传出当前 XML |
| `@change` | `(xml: string)` | 流程数据变更时触发，传出最新 XML |

### Expose

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `getSnapshot()` | `Promise<string>` | 获取当前画布截图（base64 PNG） |

---

## 外部引用集成

### 安装

```bash
npm install liteflow-designer
```

### 按需引入（推荐）

```vue
<template>
  <DesignerPanel
    ref="designerRef"
    :data="flowXml"
    :readonly="false"
    @save="handleSave"
    @change="handleChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { DesignerPanel } from 'liteflow-designer'
import 'liteflow-designer/dist/style.css'

const designerRef = ref(null)
const flowXml = ref('<flow>...</flow>')

function handleSave(xml) {
  console.log('保存流程:', xml)
}

function handleChange(xml) {
  console.log('变更:', xml)
}

async function exportImage() {
  const base64 = await designerRef.value.getSnapshot()
}
</script>
```

### 全局注册

```js
import { createApp } from 'vue'
import LiteFlowDesigner from 'liteflow-designer'
import 'liteflow-designer/dist/style.css'

const app = createApp(App)
app.use(LiteFlowDesigner)       // 注册为 <lite-flow-designer />
app.mount('#app')
```

### FlowModel / XML 数据模型

```js
import { FlowModel, xmlToFlowModel, flowModelToXML } from 'liteflow-designer'

const model = xmlToFlowModel('<flow>...</flow>')
const xml = flowModelToXML(model)
```

---

## 项目结构

```
liteflow/
├── index.html
├── package.json
├── vite.config.js
├── README.md
├── ARCHITECTURE.md                    # 详细架构设计文档
│
├── src/
│   ├── main.js                        # 开发预览入口
│   ├── index.js                       # 组件库对外导出
│   ├── App.vue
│   │
│   ├── views/
│   │   └── Designer.vue               # 本地开发预览页
│   │
│   ├── components/designer/           # 设计器组件包 ⭐
│   │   ├── DesignerPanel.vue          # 对外顶层容器
│   │   ├── TopToolbar.vue             # 顶部 XML 工具栏
│   │   ├── SidePanel.vue              # 左侧脚本/链列表面板
│   │   ├── FlowCanvas.vue             # 中央画布
│   │   ├── CanvasToolbar.vue          # 画布悬浮工具栏（DSL/缩放/模拟）
│   │   ├── PropsPanel.vue             # 右侧属性面板
│   │   ├── SimulatePanel.vue          # 流程模拟浮动面板
│   │   ├── InsertNodeDialog.vue       # 插入/追加节点弹窗
│   │   ├── ScriptDialog.vue           # 脚本编辑弹窗
│   │   ├── ScriptEditor.vue           # CodeMirror 编辑器
│   │   ├── ChainDialog.vue            # 流程链编辑弹窗
│   │   ├── nodes/                     # LogicFlow 自定义 Preact 节点/边
│   │   │   ├── EdgePlusButton.jsx
│   │   │   └── LiteFlow*Node.jsx
│   │   ├── props/                     # 节点类型属性编辑子组件
│   │   └── sub-keywords/              # 子关键字表单控件
│   │
│   ├── composables/
│   │   ├── useFlowDesigner.js         # 画布核心逻辑
│   │   └── useFlowManager.js          # XML/链/脚本管理
│   │
│   ├── config/
│   │   ├── NodeEnum.js                # 节点类型枚举
│   │   ├── KeywordEnum.js             # 子关键字枚举
│   │   ├── EdgeEnum.js                # 边类型枚举
│   │   └── nodes.js                   # 节点视觉配置
│   │
│   ├── core/
│   │   ├── FlowData.js                # 单链图数据 + DSL/EL 转换
│   │   ├── FlowModel.js               # XML 顶层数据模型
│   │   ├── DSLParser.js / ELParser.js / XMLParser.js
│   │   ├── Simulator.js               # 流程模拟引擎
│   │   ├── ELNode.js                  # AST 转换管道（graph↔tree↔text）
│   │   ├── FlowParserBase.js          # 解析共用工具
│   │   ├── utils/                     # 画布辅助工具
│   │   │   ├── containerUtils.js      # THEN/PRE/FINALLY 容器约束
│   │   │   └── ifBranchUtils.js       # IF 分支边管理
│   │   └── ast/                       # AST 节点类 + 子关键字注册表
│   │
│   ├── router/
│   ├── styles/
│   │   └── global.css
│   └── views/
│
└── dist/                              # 构建产物
    ├── liteflow-designer.es.js
    ├── liteflow-designer.umd.js
    └── style.css
```

---

## 架构说明

详细分层设计、数据流、AST 管道说明见 [ARCHITECTURE.md](./ARCHITECTURE.md)。

**核心要点：**

- **双模式**：开发预览应用 + 可发布组件库
- **双数据模型**：对外 XML（FlowModel），链内 JSON 图（FlowData）
- **连线驱动**：仅通过边线 `+` 追加节点
- **Preact ↔ Vue**：LogicFlow 自定义组件用 JSX，经 eventCenter 通信

---

## 开发指南

### 核心设计理念

| 理念 | 说明 |
|------|------|
| **连线驱动** | 所有节点通过边线上的 `+` 按钮追加，禁止自由拖拽 |
| **分支即聚合** | 分支节点创建时自动生成 AND 聚合节点，删除时递归清理 |
| **内部封装** | FlowData 完全内部化，外部只需关心 XML / `@save` / `@change` |
| **独立打包** | 整体可作为 Vue3 组件库被其他项目引用 |

### 开发约定

- **Preact ↔ Vue 通信**：LogicFlow 自定义节点/边用 Preact 编写（`.jsx`），通过 `eventCenter` 与 Vue 侧通信
- **节点类型策略**：通过 `properties.nodeType` 区分业务类型，自定义视图在 `nodes/` 目录
- **自动布局**：dagre（`rankdir: 'LR'`）计算坐标，防抖 300ms 自动触发
- **状态注入**：`provideDesigner()` / `injectDesigner()` 向子组件注入画布状态

### 添加新节点类型

1. 在 [`src/config/NodeEnum.js`](src/config/NodeEnum.js) 添加类型常量
2. 在 [`src/config/nodes.js`](src/config/nodes.js) 添加视觉配置
3. 如需分支行为，更新 `BRANCH_NODE_TYPES` 等集合
4. 在 [`src/components/designer/props/`](src/components/designer/props/) 添加属性编辑组件
5. 在 [`src/core/ast/`](src/core/ast/) 添加 AST 节点类并 `ELNode.register()`

### 手动测试

1. **开发预览**：`npm run dev`，操作所有功能
2. **构建验证**：`npm run build:lib`，在外部项目引用打包产物

> 后续建议引入 **Vitest** + **@vue/test-utils** 进行组件单元测试。

---

## 构建打包

### 组件库打包

```bash
npm run build:lib
```

| 文件 | 格式 | 说明 |
|------|------|------|
| `liteflow-designer.es.js` | ES Module | 支持 `import` 按需引入 |
| `liteflow-designer.umd.js` | UMD | 支持 `<script>` 标签或 CommonJS |
| `style.css` | CSS | 组件样式 |

### External 依赖

以下依赖设为 **external**，不打包进组件库，由使用方提供：

`vue` · `element-plus` · `@logicflow/core` · `@logicflow/extension` · `preact` · `@codemirror/*`

### 普通构建

```bash
npm run build
npm run preview
```

---

## 开发阶段

| 阶段 | 内容 | 状态 |
|------|------|------|
| Phase 1 | 项目骨架：DesignerPanel 布局、FlowCanvas 封装、禁止拖拽 | ✅ |
| Phase 2 | 边线 + 按钮：EdgePlusButton、InsertNodeDialog | ✅ |
| Phase 3 | 节点删除重连、分支递归删除 + AND 管理 | ✅ |
| Phase 4 | 自动布局：dagre LR 层次布局 | ✅ |
| Phase 5 | FlowData + DSL/EL + XML 数据模型 | ✅ |
| Phase 6 | 工具栏 + 属性面板 + 缩放 + getSnapshot | ✅ |
| Phase 7 | 流程模拟：Simulator + SimulatePanel | ✅ |
| Phase 8 | 组件打包：library mode | ✅ |
| Phase 9 | PRE/FINALLY 容器 + IF 双分支 | ✅ |

---

## License

[Apache-2.0](LICENSE)