LogicFlow流程可视化框架：从零跑通可拖拽节点与连线

简介：LogicFlow 是一套面向业务流程可视化的前端框架资源，适合需要在前端项目中快速搭建流程图编辑器的开发者，尤其是使用 TypeScript 与 MVVM 架构的中高级工程师。它聚焦于流程交互与编辑能力，提供撤销重做、对齐线、键盘操作等配套功能，并支持自定义节点与插件扩展，可满足业务系统内类流程图的定制需求。资源包共 333 个文件，约 997KB，以 tsx 与 ts 源码为主，辅以 md 文档、js 脚本、png 示意图、css/less 样式及 json 配置，整体结构清晰，便于按模块阅读与二次开发。目前已有 3784 人学习下载，读者可从中获取框架核心实现思路、组件组织方式与扩展机制示例，适合作为流程可视化项目的参考实现或学习 TypeScript 前端架构的实践素材。

1. LogicFlow：流程可视化的前端框架，为什么它值得你花一个下午跑通

很多前端团队第一次接到「画流程图」的需求时，第一反应是上 Canvas 手撸，或者找个通用绘图库硬改。结果往往是连线逻辑写了两千行，节点拖拽和缩放互相打架，最后交付一个只能看不能改的「图片生成器」。LogicFlow 这个流程可视化的前端框架，解决的正是这类场景：它把节点、连线、画布坐标系、事件系统、数据模型这些脏活累活封装好，你只需要关心业务节点长什么样、连线规则怎么定。它适合谁？适合需要做审批流编排、DAG 任务调度面板、低代码平台流程设计器、状态机编辑器的前端工程师。一句话，只要你的页面里需要「用户自己拖拽节点、连线、保存成 JSON」这件事，LogicFlow 就值得你花一个下午跑通最小闭环。

2. 把 LogicFlow 跑起来：从零到画布上出现第一个可拖拽节点

2.1 选型理由：为什么不是手写 Canvas 或直接用 X6

先说清楚为什么选它。市面上的图形方案大致分三层：最底层是原生 Canvas/SVG，中间是 X6、G6 这类通用图编辑引擎，最上层是 LogicFlow 这种面向「流程」场景的框架。手写 Canvas 的问题在于，你要自己实现命中检测、坐标变换、连线锚点吸附，这些逻辑一旦节点类型超过三种就会失控。X6 能力很强，但它的定位是「图编辑引擎」，节点和连线的业务语义需要你自己搭一层。LogicFlow 的取舍是：它基于 SVG 渲染，内置了流程场景最常用的节点（矩形、圆形、多边形）和连线（直线、折线、贝塞尔），并且把「数据驱动」这件事做成了核心——你改数据模型，画布自动更新，反过来用户拖拽，数据模型也自动同步。这个双向绑定是它和通用绘图库最大的区别。

我一般会这样判断：如果你的需求里出现「节点有业务类型」「连线有校验规则」「需要导出结构化数据」这三个特征中的两个，就直接上 LogicFlow，别犹豫。

2.2 最小可运行示例：三行依赖加一个容器

先装依赖。LogicFlow 的核心包和它的 React/Vue 适配层是分开的，如果你用框架开发，建议直接装对应适配包。

# 核心包，必须装 npm install @logicflow/core # 如果你用 React，装这个，省去自己写生命周期 npm install @logicflow/extension

然后是最小初始化代码。注意容器必须给明确宽高，否则 SVG 画布会塌成 0 高度，这是新手第一个翻车点。

import LogicFlow from '@logicflow/core'; import '@logicflow/core/dist/style/index.css'; // 容器需要提前在 DOM 里存在，且必须有宽高 const lf = new LogicFlow({ container: document.querySelector('#graph'), width: 800, height: 600, // 网格配置，后面调对齐会用到 grid: { size: 20, visible: true, type: 'dot', }, }); // 渲染数据，nodes 和 edges 是 LogicFlow 的标准数据结构 lf.render({ nodes: [ { id: 'node_1', type: 'rect', // 内置矩形节点 x: 100, y: 100, text: '开始', }, { id: 'node_2', type: 'circle', x: 300, y: 100, text: '审批', }, ], edges: [ { id: 'edge_1', type: 'polyline', // 折线，流程场景最常用 sourceNodeId: 'node_1', targetNodeId: 'node_2', text: '提交', }, ], });

这段代码的逻辑说明：new LogicFlow做了三件事——创建 SVG 画布、初始化数据模型、绑定默认交互（拖拽、缩放、框选）。render接收的是纯 JSON，节点用x/y定位，连线用sourceNodeId/targetNodeId关联。参数上，grid.size控制网格间距，grid.type可选dot和mesh，流程编辑器一般用dot视觉更轻。width/height如果不传，会读取容器计算样式，但容器如果是display:none或者还没挂载，就会拿到 0，所以显式传更稳。

2.3 数据模型长什么样：nodes 和 edges 的字段约定

LogicFlow 的数据模型是它最值得先吃透的部分。节点对象里，id全局唯一，type决定渲染成什么形状，x/y是画布坐标系（不是屏幕坐标，缩放后不变），text是显示文本，properties是你放业务字段的地方。连线对象里，sourceNodeId和targetNodeId是必填，sourceAnchorId和targetAnchorId用来指定从节点的哪个锚点连出，不填就自动选最近锚点。

这里有个血泪经验：properties里的字段不要放函数或 DOM 引用，因为导出 JSON 时会丢失，回显时直接报错。所有业务状态都应该是可序列化的原始类型。

3. 自定义节点与连线：把业务语义塞进画布

3.1 继承 RectNode 写一个带图标的审批节点

内置节点够用，但真实业务里节点往往要带图标、状态色、多个锚点。LogicFlow 的自定义节点机制是继承内置类，重写getShape方法。下面是一个带左侧图标和状态边框的审批节点。

import { RectNode, RectNodeModel } from '@logicflow/core'; // 模型层：管数据、管状态、管锚点 class ApprovalModel extends RectNodeModel { initNodeData(data) { super.initNodeData(data); // 从 properties 里读业务状态，决定边框颜色 this.status = data.properties?.status || 'pending'; // 定义四个锚点，上下左右各一个 this.anchorsOffset = [ [this.width / 2, 0], [-this.width / 2, 0], [0, -this.height / 2], [0, this.height / 2], ]; } getNodeStyle() { const style = super.getNodeStyle(); const colorMap = { pending: '#faad14', approved: '#52c41a', rejected: '#ff4d4f', }; style.stroke = colorMap[this.status] || '#999'; style.strokeWidth = 2; return style; } } // 视图层：管长什么样 class ApprovalNode extends RectNode { getShape() { const { x, y, width, height, radius } = this.props.model; const style = this.props.model.getNodeStyle(); return { type: 'g', children: [ { type: 'rect', x: x - width / 2, y: y - height / 2, width, height, radius, ...style, }, { type: 'text', x, y, text: this.props.model.text.value, fill: '#333', }, ], }; } } // 注册，type 名字就是数据里的 type lf.register('approval-node', ApprovalNode, ApprovalModel);

逻辑说明：initNodeData是初始化钩子，适合读properties并设置内部状态。anchorsOffset定义锚点相对节点中心的偏移，不定义的话默认只有上下左右四个，但位置是节点边缘中点。getNodeStyle返回的是 SVG 属性对象，会被合并到最终渲染。getShape返回的是虚拟节点树，LogicFlow 内部会把它转成真实 SVG。参数上，width/height默认 100x60，可以在initNodeData里改this.width。

3.2 连线校验：用 getConnectedTargetRules 拦住非法连接

流程编辑器里，不是所有节点都能互相连。比如「开始」节点不能有入边，「结束」节点不能有出边，审批节点不能连到自己。LogicFlow 提供了连线规则校验钩子。

class ApprovalModel extends RectNodeModel { // 校验这条边能不能连到目标节点 getConnectedTargetRules() { const rules = super.getConnectedTargetRules(); const notSelfRule = { message: '不能连接到自身', validate: (source, target) => source.id !== target.id, }; const startNoInRule = { message: '开始节点不能作为终点', validate: (source, target) => target.type !== 'start-node', }; return [...rules, notSelfRule, startNoInRule]; } }

逻辑说明：getConnectedTargetRules返回一个规则数组，每条规则有message和validate。validate返回false时，连线会被拒绝，并弹出message。参数上，source是起点节点模型，target是终点节点模型，你可以读它们的type、properties做任意判断。注意这个钩子是在拖拽连线过程中实时调用的，所以validate里不要做重计算或异步请求，否则拖拽会卡。

3.3 事件系统：监听节点点击、连线完成、数据变更

LogicFlow 的事件分三类：节点事件、连线事件、画布事件。最常用的是node:click、edge:add、graph:updated。

// 节点点击，拿到节点数据 lf.on('node:click', ({ data }) => { console.log('点击了节点', data.id, data.properties); }); // 连线完成，可以在这里做持久化 lf.on('edge:add', ({ data }) => { console.log('新增连线', data.sourceNodeId, '->', data.targetNodeId); }); // 画布数据变更，任何拖拽、删除、属性修改都会触发 lf.on('graph:updated', () => { const graphData = lf.getGraphData(); // 这里做防抖后保存到后端 saveToServer(graphData); });

逻辑说明：node:click的回调参数里data是节点的完整数据对象，包含properties。edge:add在连线创建完成后触发，此时数据已经写入模型。graph:updated是最粗粒度的事件，任何变更都会触发，适合做自动保存，但一定要加防抖，否则拖拽过程中会疯狂触发。参数上，getGraphData()返回的就是标准{ nodes, edges }结构，可以直接JSON.stringify存库。

4. 避坑与排查：那些让画布白屏、连线错位的真实原因

4.1 容器宽高为 0 导致画布不显示

现象：代码没报错，但页面上什么都没有。原因：LogicFlow 初始化时读取容器尺寸，如果容器是display:none、还没挂载、或者父级没有高度，读到的就是 0。解决：要么在mounted之后再初始化，要么显式传width/height，要么给容器加min-height。我一般会在容器上写style="width:100%;height:600px"，不依赖父级。

4.2 节点拖拽后坐标偏移

现象：拖拽节点，松手后节点跳到别的位置。原因：画布做了缩放或平移，但自定义节点里用了屏幕坐标计算。解决：所有节点内部计算都用this.props.model.x/y，这是画布坐标，不要用event.clientX。如果确实需要屏幕坐标，用lf.getPointByClient转换。

4.3 自定义节点注册后不生效

现象：lf.register调了，但render时还是渲染成默认矩形。原因：注册的type名字和数据里的type不一致，或者注册时机在render之后。解决：先register再render，并且检查type字符串完全一致，包括大小写和连字符。

4.4 导出 JSON 丢失业务字段

现象：getGraphData()拿到的数据里properties是空的。原因：业务字段没有放在properties里，而是直接挂在节点对象顶层，或者放了不可序列化的值。解决：所有业务数据统一放properties，并且只放字符串、数字、布尔、数组、普通对象。

4.5 大量节点时拖拽卡顿

现象：节点超过 200 个后，拖拽明显掉帧。原因：每次拖拽都触发全量重渲染，且graph:updated里做了同步保存。解决：开启lf.setTheme里的grid隐藏，减少 SVG 节点数；graph:updated加 500ms 防抖；如果还卡，考虑用lf.use引入snapshot插件做离屏渲染，或者把非可视区域节点做虚拟化。

5. 进阶技巧：用插件和自定义命令把编辑器做成产品

5.1 用 extension 包快速接入对齐线、快捷键、菜单

@logicflow/extension里有一批开箱即用的插件，最值得先接的是Menu、Snapshot、SelectionSelect。

import { Menu, Snapshot, SelectionSelect } from '@logicflow/extension'; import '@logicflow/extension/lib/style/index.css'; lf.use(Menu); lf.use(Snapshot); lf.use(SelectionSelect); // 配置右键菜单 lf.extension.menu.setMenuConfig({ nodeMenu: [ { text: '复制', callback: (node) => lf.cloneNode(node.id) }, { text: '删除', callback: (node) => lf.deleteNode(node.id) }, ], edgeMenu: [ { text: '删除', callback: (edge) => lf.deleteEdge(edge.id) }, ], });

逻辑说明：lf.use是插件注册入口，注册后插件会挂到lf.extension下。Menu插件接管右键菜单，setMenuConfig分别配置节点和连线的菜单项。Snapshot提供lf.extension.snapshot.getSnapshot()导出图片。SelectionSelect开启框选，默认是关闭的。参数上，cloneNode会自动生成新 id 并偏移位置，deleteNode会同时删除关联的边。

5.2 自定义命令：把「撤销重做」做成可扩展的

LogicFlow 内置了撤销重做，但只覆盖默认操作。如果你自定义了节点属性修改，需要注册自定义命令。

// 注册一个修改节点属性的命令 lf.registerCommand('updateNodeStatus', { execute: (nodeId, status) => { const model = lf.getNodeModelById(nodeId); const oldStatus = model.properties.status; model.setProperties({ status }); return { nodeId, oldStatus, newStatus: status }; }, undo: (params) => { const model = lf.getNodeModelById(params.nodeId); model.setProperties({ status: params.oldStatus }); }, redo: (params) => { const model = lf.getNodeModelById(params.nodeId); model.setProperties({ status: params.newStatus }); }, }); // 调用 lf.executeCommand('updateNodeStatus', 'node_1', 'approved');

逻辑说明：registerCommand接收命令名和三个函数。execute做实际操作并返回一个参数对象，这个对象会传给undo和redo。undo和redo分别做反向和正向操作。参数上，execute的返回值必须是可序列化的，因为撤销栈里存的就是它。这个机制的好处是，你的业务操作只要注册成命令，就自动进入撤销重做体系，不用自己维护历史栈。

5.3 一个验证方法：用 JSON 快照做回归测试

流程编辑器最容易出的 bug 是「拖拽后数据不对」。我一般会写一个简单的回归测试：准备一组标准 JSON，render后执行一系列操作（拖拽、连线、删除），再getGraphData，和预期 JSON 做深度对比。

function runRegression(lf, actions, expected) { actions.forEach((action) => { if (action.type === 'move') { lf.getNodeModelById(action.id).moveTo(action.x, action.y); } else if (action.type === 'addEdge') { lf.addEdge({ sourceNodeId: action.source, targetNodeId: action.target, }); } }); const result = lf.getGraphData(); // 只对比关键字段，忽略内部生成的 id const simplified = { nodes: result.nodes.map((n) => ({ id: n.id, x: n.x, y: n.y })), edges: result.edges.map((e) => ({ source: e.sourceNodeId, target: e.targetNodeId, })), }; return JSON.stringify(simplified) === JSON.stringify(expected); }

这个方法的要点是：不要对比完整 JSON，因为 LogicFlow 会生成一些内部字段（比如points、zIndex），对比关键字段就够了。每次改自定义节点逻辑，跑一遍这个回归，能拦住大部分「改 A 坏 B」的问题。

最后说个我自己的习惯：每次接流程编辑器需求，先花半小时把 LogicFlow 官方示例里的「自定义节点」和「连线规则」两个 demo 跑一遍，再动手写业务代码。这半小时能省掉后面至少两天的调试。希望帮到你。

本文还有配套的精品资源，点击获取