LogicFlow 流程图编辑框架：从入门到进阶的技术实践

cursor\claule skill
感谢 Stars

一、为什么需要 LogicFlow？

在低代码、工作流、可视化编排等场景中，流程图编辑器是核心能力之一。无论是审批流程、业务编排、脑图、ER 图还是 UML 图，都需要一套可扩展、易集成的图编辑方案。LogicFlow 是滴滴开源的流程图编辑框架，基于 TypeScript 构建，支持 Vue 2/3、React 16+，用 JSON 数据驱动视图，适合快速搭建各类图编辑应用。

本文基于 LogicFlow 官方能力与常见实践，梳理从安装、核心概念、自定义节点与边、插件系统到 Vue/React 集成与 BPMN 工作流的一条龙技术路径，目标读者是需要在项目里落地流程图编辑器的前端开发者。

二、安装与快速开始

通过 npm / yarn / pnpm 安装核心库与扩展库：

npm install @logicflow/core @logicflow/extension --save

页面中准备一个固定宽高的容器，并引入样式：

<div id="container"></div>

#container { width: 100%; height: 500px; }

初始化实例并渲染简单图数据：

import LogicFlow from '@logicflow/core'
import '@logicflow/core/dist/style/index.css'

const lf = new LogicFlow({
  container: document.querySelector('#container'),
  grid: true,
})

lf.render({
  nodes: [
    { id: '1', type: 'rect', x: 100, y: 100, text: '节点1' },
    { id: '2', type: 'circle', x: 300, y: 100, text: '节点2' },
  ],
  edges: [
    { sourceNodeId: '1', targetNodeId: '2', type: 'polyline' }
  ]
})

即可得到一个可拖拽、可连线的流程图画布。图的数据结构是标准的 nodes + edges，便于与后端接口、本地存储对接。

三、核心概念：数据与内置图形

LogicFlow 使用 JSON 描述整张图。节点（NodeConfig）包含 id、type、x、y，以及可选的 text、properties；边（EdgeConfig）包含 sourceNodeId、targetNodeId、type 等。type 决定渲染成哪种图形。

内置节点类型包括：rect（矩形）、circle（圆形）、diamond（菱形）、polygon（多边形）、ellipse（椭圆），对应不同的 NodeModel/Node 基类。内置边类型包括：line（直线）、polyline（折线，默认）、bezier（贝塞尔曲线）。这些足以支撑简单流程图；复杂业务则依赖自定义节点与边。

四、自定义节点：MVVM 与 Model/View

LogicFlow 采用 MVVM：数据与行为在 Model，渲染在 View。自定义节点需要提供 type、model、view（view 可复用内置如 RectNode）。

在 Model 中通常重写：

• initNodeData(data)：设置宽高、默认属性；
• getNodeStyle()：返回填充、描边、圆角等样式；
• getTextStyle()：文本样式；
• getDefaultAnchor()：锚点位置，用于连线的起点/终点；
• getConnectedSourceRules() / getConnectedTargetRules()：连接规则，用于限制“谁可以连谁”。

示例：定义一个固定尺寸、带样式的“自定义节点”：

class CustomNodeModel extends RectNodeModel {
  initNodeData(data) {
    super.initNodeData(data)
    this.width = 120
    this.height = 60
  }
  getNodeStyle() {
    const style = super.getNodeStyle()
    style.fill = '#e8f4ff'
    style.stroke = '#1890ff'
    return style
  }
}

再用 lf.register({ type: 'custom-node', view: RectNode, model: CustomNodeModel }) 注册，即可在 nodes 里使用 type: 'custom-node'。

更复杂的节点（如带状态、图标、多行文案）可以在 Model 的 setAttributes() 或 getNodeStyle() 中根据 properties 分支样式，或在 View 中重写 getShape() 使用 LogicFlow 的 h() 渲染多元素。HTML 节点则可继承 HtmlNode / HtmlNodeModel，在 setHtml(rootEl) 里挂载 Vue/React 组件，实现完全自定义的 DOM 内容。

五、事件与常用 API

通过 lf.on(eventName, callback) 监听节点、边、画布等事件。常用事件包括：node:click、node:dblclick、node:add、node:delete、node:dragstart、node:drop、edge:click、edge:add、edge:delete、blank:click、selection:selected、history:change 等。回调中可拿到 data、e、position，便于做属性面板、右键菜单、拖拽结束后的业务校验。

常用 API 包括：lf.getGraphData() / lf.render(graphData) 读写整图；lf.addNode() / lf.deleteNode() / lf.addEdge() / lf.deleteEdge() 增删节点与边；lf.getSelectElements() 获取当前选中；lf.setProperties(id, props) 更新属性；lf.zoom() / lf.resetZoom() / lf.translateCenter() / lf.fitView() 控制视图；lf.undo() / lf.redo() 历史记录（需在初始化时开启 history: true）。配合事件与 API，可以轻松实现保存、加载、导出、撤销重做、属性编辑等能力。

六、插件系统：控制栏、小地图、导出、拖拽面板

LogicFlow 的扩展能力通过插件注入。从 @logicflow/extension 引入样式后，在 new LogicFlow({ plugins: [...] }) 中注册即可。

常用插件包括：Control（缩放、重置、撤销、重做等控制按钮）、Menu（节点/边/画布右键菜单）、DndPanel（从面板拖拽节点到画布）、MiniMap（小地图）、Snapshot（导出图片）、SelectionSelect（框选）、BpmnElement（BPMN 节点与边）、NodeResize（节点缩放）、DynamicGroup（分组）等。

例如启用 Control、MiniMap、Snapshot：

import { Control, MiniMap, Snapshot } from '@logicflow/extension'
import '@logicflow/extension/lib/style/index.css'

const lf = new LogicFlow({
  container: document.querySelector('#container'),
  plugins: [Control, MiniMap, Snapshot]
})

DndPanel 可通过 lf.extension.dndPanel.setPatternItems([...]) 配置可拖拽的节点类型（含 type、text、label、icon 等），Menu 通过 lf.extension.menu.setMenuConfig({ nodeMenu, edgeMenu, graphMenu }) 配置右键项与回调。这样无需从零实现工具栏和侧边栏，即可得到一个功能完整的流程图编辑器壳子。

七、Vue3 / React 集成要点

在 Vue3 中，一般在 onMounted 里根据 ref 容器创建 LogicFlow 实例，在 onUnmounted 里做清理（如置空实例、按需销毁）。在 React 中，在 useEffect 里创建实例并 return 清理函数。注意单页应用路由切换时务必销毁实例，避免重复挂载和内存泄漏。

将 lf.getGraphData() 与后端接口或本地状态同步即可实现保存与加载；选中状态可用 lf.on('node:click', ...) 更新到组件的 ref/state，驱动属性面板展示与编辑。若使用 DndPanel，也可在 Vue/React 中自建节点列表，通过 lf.dnd.startDrag({ type, text }) 在拖拽开始时交给 LogicFlow 处理，实现与现有 UI 库一致的交互。

八、进阶：自定义边、连接规则与 BPMN

自定义边时，继承 PolylineEdgeModel（或 BezierEdgeModel 等），重写 getEdgeStyle()、getEdgeAnimationStyle() 即可改变线条样式与动画（如虚线流动）。连接规则在节点的 Model 中通过 getConnectedSourceRules() / getConnectedTargetRules() 返回校验数组，每条规则包含 message 与 validate(source, target)，返回 false 时连接被禁止并可选提示 message。例如开始节点只允许作为源、结束节点只允许作为目标、某类节点限制连出数量等，都可在此实现。

BPMN 工作流场景可使用官方提供的 BpmnElement 与 BpmnXmlAdapter。BpmnElement 会注册如 bpmn:startEvent、bpmn:endEvent、bpmn:userTask、bpmn:serviceTask、bpmn:exclusiveGateway、bpmn:parallelGateway、bpmn:sequenceFlow 等类型；BpmnXmlAdapter 提供 lf.adapterOut(data) 导出为 BPMN XML、lf.adapterIn(xml) 从 XML 导入为图数据，便于与流程引擎或第三方 BPMN 工具对接。

九、初始化配置与主题

new LogicFlow({ ... }) 时常用配置包括：grid、background、keyboard: { enabled: true }（快捷键）、history: true、snapline: true（对齐线）、edgeType（默认边类型）、adjustEdge、adjustNodePosition、hideAnchors 等。静默模式（只读展示）可通过 isSilentMode、stopScrollGraph、stopMoveGraph、stopZoomGraph 等关闭交互。主题通过 style 传入，可统一配置 rect、circle、polyline、anchor、arrow、snapline 等样式，便于与产品视觉规范一致。

十、实践建议

在实际项目中落地 LogicFlow 时，建议优先做三件事：一是用 lf.getGraphData() 做自动保存或定时同步，避免用户误关页导致数据丢失；二是为节点和边预留 properties 字段，把业务字段（如审批人、超时时间、表单 ID）存进去，便于与后端流程定义一致；三是利用 keyboard: { enabled: true } 和默认的 Ctrl+Z/Y、Delete 等快捷键，减少重复开发。若需要只读展示（如流程进度图），开启 isSilentMode: true 即可禁用拖拽与连线。自定义节点较多时，可统一放在单独目录、按业务模块注册，并配合 DndPanel 分组展示，便于维护与迭代。

十一、小结

LogicFlow 通过“图数据 + 内置图形 + 自定义 Model/View + 插件”的组合，覆盖了从简单流程图到工作流、BPMN 的常见需求。掌握其数据结构、事件与 API、自定义节点与边的扩展方式，以及插件与 Vue/React 的集成方式，即可在业务中快速落地可维护、可扩展的流程图编辑器。更多 API、主题和高级用法可参考官方文档（https://site.logic-flow.cn/）与 GitHub（https://github.com/didi/LogicFlow）。