基于antv/g6与Vuex构建流程图编辑器：状态管理、交互实现与踩坑全记录

简介面向需要在前端项目中集成流程图绘制功能的开发者这份 Demo 基于 Vue 与 antv/g6 实现抽取了流程图创建、节点链接、节点删除、菜单操作、重新渲染及本地存储等基础交互适合作为入门参考。资源压缩包约 189KB共 93 个文件其中包含 38 个 js、34 个 vue、5 个 scss、3 个 json以及字体、图片等静态资源Vue 单文件组件与业务脚本结构清晰便于按模块阅读改造。已有 12812 人学习下载具备一定参考热度。通过该 Demo 可以直观了解 g6 在 Vue 项目中的挂载方式、节点与边数据的维护逻辑以及菜单操作和本地存储的常见写法虽然不含复杂业务算法但足以支撑快速搭建一套可交互的流程草图原型。遇到实际问题仍需结合官方文档自行调试扩展。 如果你接过后台系统需要加一个在线绘制分析流程图这样的需求一定知道它没有看起来那么简单节点能拖、能连、能改名画布支持缩放平移数据还要能保存、恢复最好还能撤销。我最终用 antv/g6 做画布渲染用 Vuex 做全局状态管理把整套流程跑通并沉淀成了一个可直接演示的 Demo。这篇文章就把这个 Demo 从零到一讲清楚内容覆盖 Vuex 状态模块怎么设计、g6 画布交互怎么接、图数据和 Vuex 怎么保持同步还有我在实际开发过程中踩过的几个坑。适合正在做类似图形化编辑器的同学参考也适合单纯想了解 g6 和 Vuex 如何协作的开发者。1. 为什么流程图编辑器离不开全局状态管理1.1 流程图编辑器本质是一台状态机把编辑器界面拆开看通常会包含左侧物料面板、中间画布、右侧属性面板、顶部工具栏。用户点一个节点右侧面板要显示属性在面板里改文本画布上的节点要立刻刷新删除一个节点和它相连的线也要跟着消失。这些看似由不同组件各自负责的功能实际上都在消费同一份图数据——节点集合、边集合、当前选中元素、画布缩放比例。如果每个组件都在自己的 data 里各存一份副本很快就会失去同步。组件 A 删掉一条边组件 B 的列表还显示着它画布缩小到 80%属性面板还不知道。这类问题在早期原型阶段不明显一旦功能叠加调试成本会指数级上升。我习惯打一个比方组件内的 data 是各房间的私人账本Vuex 是公司总账。表单页面的数据读写基本发生在同一个房间内私人账本够用但流程图编辑器每天有大量跨房间的读写只靠私人账本一定会对不上账。这也是我坚持在项目一开始就引入全局状态管理的原因而不是等功能写崩了再回头补。1.2 为什么是 Vuex 而不是 EventBus 或 props 逐层传用 Vue 做编辑器可选的状态方案还有 props 逐层传递和 EventBus。props 逐层传递的问题比较直观左侧物料面板要通知画布创建节点画布要通知右侧面板更新选中项右侧面板要通知画布修改节点样式这些跨平级组件的通信靠 props 根本走不通需要依赖一个公共父组件不断中转业务代码会被大量桥接逻辑淹没。EventBus 能解决跨组件通信但它更适合少量、低频的消息通知比如刷新列表弹出提示。一旦把图数据这种持续变化的核心状态放进 EventBus你就等于放弃了数据流的可追踪性。任何一个组件都可以往总线里丢数据时间一长根本说不清某个字段是从哪里改的、在哪一步丢的。相比之下Vuex 给了一个强制约束所有状态变更必须走 mutation所有异步流程必须走 action。调试时可以配合 DevTools 回放每次变更这在排查复杂交互问题时几乎是救命级的能力。三种方案的对比也很清晰方案数据流可追踪性跨组件共享调试体验长期维护props 逐层传一般依赖父组件中转弱平级难通信一般差桥接代码多EventBus差事件满天飞强但无约束差难定位来源差易失控Vuex强单向数据流强单一数据源好支持时间旅行好边界清晰需要说明的是Vuex 里管理的不是 g6 实例本身而是图数据。g6 实例是复杂的类对象直接塞进 Vuex 会被响应式系统代理反而引入性能隐患。正确做法是把图数据这种纯 JSON 结构放进 storeg6 实例单独维护后面第 2 章会细说这个分工。2. Demo 的整体架构画布、侧边栏和状态层的职责划分2.1 store 模块划分nodes、edges、canvas、historyDemo 我用了一个业务场景用户流失分析流程。左侧物料面板提供开始节点分析节点判断节点结束节点四种类型画布上通过连线表达分析路径。对应的 Vuex store 按功能拆了四个子模块目录结构如下src/store/ ├── index.js └── modules/ ├── nodes.js # 节点数据 ├── edges.js # 边数据 ├── canvas.js # 画布状态 └── history.js # 撤销重做快照nodes 模块里的数据刻意保持扁平每个节点一条记录const node { id: node_1628000000000, type: analysis, // 节点类型对应注册的 g6 节点 label: 计算流失率, x: 360, y: 240, status: default // 用于控制节点样式 }edges 模块记录边的两个端点、类型和文本标签{ id, source, target, type: polyline, label }。canvas 模块管的是和画布整体相关的状态比如当前缩放比例、选中节点 id、当前交互模式拖拽中还是连线中。history 模块后面第 5 章会专门讲先不展开。为什么这样划分核心原则是和渲染相关的归数据模块和交互相关的归画布模块。节点和边是流程图的实体必须持久化选中状态、放大比例属于临时 UI 状态刷新页面就该清掉。把这两类状态混在一起序列化保存时还得做一次过滤纯属给自己挖坑。2.2 g6 实例与 Vuex 之间的单向数据流约定这是整个 Demo 里最重要的一条约定。g6 实例单独放在一个工具模块里不隶属于任何组件也不放进 Vuex// src/graph/index.js import G6 from antv/g6 import { markRaw } from vue let graphInstance null export function initGraph(container) { graphInstance markRaw(new G6.Graph({ container, width: container.clientWidth, height: container.clientHeight, modes: { default: [drag-canvas, zoom-canvas, drag-node] } })) return graphInstance } export function getGraph() { return graphInstance }这里用 markRaw 包装了一次明确告诉 Vue这个对象不要做响应式代理。g6 内部有自己的渲染引擎和事件体系数据变更时需要由 g6 自己的 API 去驱动重绘而不是 Vue 的响应式系统去碰它。数据流我固定成一条单向链路用户操作画布 → g6 触发事件 → 组件 dispatch action → mutation 更新 Vuex state → 必要时调用 g6 API 做增量更新。反向的链路只有一条外部数据比如属性面板修改 label更新 state 后通过graph.updateItem()通知画布。组件模板里不会去 v-for 渲染 g6 的节点画布上的东西都交给 g6 自己画否则两套渲染逻辑会互相打架。3. 核心功能拆解节点拖拽、连线和画布交互的实现思路3.1 从物料面板拖入画布坐标换算与节点注册物料面板上的可拖拽元素用 HTML5 拖放实现。dragstart 时把节点类型写进dataTransfer画布容器监听 drop 事件拿到鼠标相对画布左上角的位置后换算成 g6 坐标系下的画布坐标再调用graph.addItem(node, {...})创建节点。关键点是坐标换算。g6 的坐标系和屏幕坐标系在画布缩放、平移之后会不一致直接用event.clientX减容器偏移量算出来的坐标是错的。必须用 g6 提供的转换方法function handleDrop(e) { const graph getGraph() const type e.dataTransfer.getData(nodeType) // 把浏览器客户端坐标转换成 g6 画布坐标 const point graph.getPointByClient(e.clientX, e.clientY) graph.addItem(node, { id: node_${Date.now()}, type, label: getDefaultLabel(type), x: point.x, y: point.y }) dispatch(nodes/addNode, payload) // 同步更新 Vuex }节点类型不能直接用 g6 内置的 rect那样子太丑也不利于后续扩展。我用G6.registerNode注册了一套自定义节点在默认 rect 基础上重新绘制了圆角、阴影和四个方向的锚点G6.registerNode(analysis-node, { draw(cfg, group) { const shape group.addShape(rect, { attrs: { x: -80, y: -32, width: 160, height: 64, radius: [4], fill: cfg.status success ? #e6fffb : #ffffff, stroke: cfg.status success ? #13c2c2 : #5b8ff9, lineWidth: 2, cursor: pointer } }) group.addShape(text, { attrs: { text: cfg.label || , x: 0, y: 6, textAlign: center, fontSize: 14, fill: #333 } }) return shape } }, rect)这里有个细节g6 的自定义节点 draw 函数配置的 x、y 是以节点中心为原点的相对坐标。第一次写的时候容易按左上角偏移去算结果文字位置全偏。记住这一点能省不少调试时间。3.2 节点连线锚点配置和边类型选择流程图的连线不能从节点中心连到节点中心那样线条会穿过节点内部非常难看。需要在注册节点时配置anchorPoints锚点按相对位置定义[[0, 0.5], [1, 0.5], [0.5, 0], [0.5, 1]]分别对应左、右、上、下四个边缘中点。连线交互我采用的是从锚点拉起一条临时线松手时落到目标锚点的模式。具体做法是监听 canvas 的 mousedown判断命中的图形是不是锚点区域是则进入连线模式移动鼠标时用 g6 的addItem(edge, {...})创建一条临时边mouseup 落在目标节点上时把临时边删除换成正式的边。边的类型选了 polyline 而不是默认的直线。流程图通常需要自动避让和拐点polyline 支持正交拐弯视觉上更像流程图。示例graph.addItem(edge, { source: node_xxx, target: node_yyy, type: polyline, label: 是, style: { endArrow: { path: G6.Arrow.triangle(8, 10, 0), d: 0 } } })给判断节点的边加 label比如是否会让分析流程图语义清晰很多。label 数据也可以存在边数据里属性面板选中边后直接编辑。3.3 选中联动与删除逻辑点击节点后g6 触发node:click事件事件对象里能拿到当前节点的 id。组件做一层转发把选中 id 提交给 Vuex右侧属性面板用 computed 从 state 里派生当前节点的详情graph.on(node:click, (e) { store.dispatch(canvas/setSelectedNode, e.item.get(id)) })删除逻辑里有一个很多人踩过的坑删除节点时必须同步删除和它相连的边否则图数据会出现悬挂边。g6 在渲染时会报错或者表现诡异。我的处理是在删除节点前先查一次所有边把 source 或 target 等于当前节点的边一起删掉再更新 Vuex 里的 nodes 和 edges。属性面板修改节点文本时同样要双写一边更新 state一边调用graph.updateItem(nodeId, { label: newText })否则画布和右侧面板会显示不一致。4. antv/g6 与 Vuex 联动时的性能与渲染陷阱4.1 响应式数组直接传给 g6 会导致渲染异常这是我在 Demo 开发中遇到的第一个严重问题。最初我把 Vuex state 里的 nodes 数组直接传给graph.data()结果是画布渲染正常但只要对节点做一次移动控制台立刻报错画布闪一下后节点全部消失。原因是 Vue 3 的响应式系统会用 Proxy 代理数组和对象而 g6 内部会直接对数据对象做属性赋值、属性遍历、甚至修改原型链上的方法。被 Proxy 代理后的数据对象在 g6 的赋值场景下会被响应式逻辑拦截产生不可预料的副作用。解决办法简单粗暴在把数据交给 g6 之前做一次深拷贝让 g6 操作的是普通对象而不是响应式代理对象const data JSON.parse(JSON.stringify({ nodes: store.state.nodes.list, edges: store.state.edges.list })) graph.data(data) graph.render()同理getGraph() 返回的实例在挂到组件 data 上时也建议用 markRaw 包装从根源上避免 Vue 去代理 g6 实例。这两处处理之后渲染和交互都稳定了下来。4.2 拖拽过程的频繁状态更新引发掉帧拖拽节点时g6 会持续触发node:drag事件每触发一次坐标就变一次。如果把这些坐标变更全部实时 commit 到 Vuex画布会明显掉帧。原因在于每次 commit 都会触发 state 更新而 state 一旦更新依赖它的 computed 和 watcher 都会跟着跑一遍加上 g6 自身渲染的开销六十帧根本撑不住。我的策略是分轻重拖拽过程中坐标数据不写入 Vuex只靠 g6 内部的渲染驱动位置变化拖拽结束时通过node:dragend事件把最终坐标批量提交一次。换到分析场景里用户拖了十次节点只产生十次最终结果的状态更新而不是每次都产生几十次中间态更新。真正的实时状态比如拖拽过程中的临时坐标如果确实需要暴露给其他组件可以在 store 里用一个轻量字段记录并且只存 id 和坐标不触发依赖它的重逻辑。总之不要因为 Vuex好用就把所有变化都塞进去状态更新的频率和范围是需要刻意控制的。4.3 g6 4.x 与 5.x 的版本差异是新手最大的坑网上搜索 antv/g6 相关 demo能搜到大量基于 4.x 的代码但 g6 5.x 的 API 变化非常大。最直接的差异我整理了一下对比项g6 4.xg6 5.x创建图new G6.Graph({ container, width, height, modes })new Graph({ container, width, height, behaviors })数据字段datamodel交互行为modes.default数组behaviors数组事件命名node:click、canvas:drag部分事件用法调整自定义节点G6.registerNode(type, fn, extendType)register(type, fn, extendType)如果跟着旧 demo 写最典型的报错是modes is not defined或者graph.data is not a function。我实际开发时锁定的是 4.8.x 稳定版本因为公司现有项目里已经跑过不少基于 4.x 的业务踩坑经验更充分。如果你是从零开始的新项目也可以直接用 5.x但记得把官方文档切换到对应版本别拿 4.x 的代码去套 5.x 的 API。版本锁死这件事写进 package.json 还不够最好在 README 里说明本 Demo 基于 g6 4.8.x避免同事升级依赖后一脸懵。5. 从 Demo 到生产持久化、撤销重做与协作扩展5.1 图数据的序列化与本地持久化Demo 阶段可以把图数据直接存 localStorage刷新页面后自动恢复。序列化我用的是graph.save()方法它会返回包含 nodes 和 edges 的完整 JSON 结构。保存时机选择在 dragend、删除节点、修改文本这类关键操作之后避免频繁写入。恢复数据时要注意版本兼容。我在 localStorage 里额外存了一个schemaVersion字段例如{ version: 1.0.0, graphData: {...} }。将来字段结构发生变化可以针对不同版本写迁移函数。别等到线上用户已经有存量数据了再考虑这个Demo 阶段养成习惯成本很低。5.2 用 Vuex 插件实现撤销重做流程图编辑器的撤销重做本质是对状态快照的管理。用 Vuex 的store.subscribe插件每次 mutation 提交后把当前 state 里的 nodes 和 edges 深拷贝压入历史栈撤销时从栈里弹出上一份快照重新渲染画布。有两个注意点。第一不是所有 mutation 都值得记录比如设置选中节点这种临时 UI 状态撤销栈里留下这种快照只会白占内存。我通过 mutation 的 type 前缀做过滤只有nodes/、edges/开头的变更才入栈。第二历史栈要设上限我只保留最近 50 步防止长时间操作后内存膨胀。撤销的具体逻辑是从 history 栈中取出上一份快照 → 把 nodes 和 edges 的 state 替换成快照 → 清空画布重绘。整个过程不复杂但因为节点 id 在快照里保持一致画布重绘后选中状态和连线关系都能恢复。5.3 多人实时协作的扩展思路多人协作是这类编辑器后续大概率会碰到的需求。Vuex 的架构在这里能派上大用场协作的本质就是把本地的 mutation变成远端的 mutation。本地操作不再直接 commit而是通过 WebSocket 把 action 类型和 payload 广播出去远端收到后执行同一个 mutation。只要两端初始数据一致操作序列一致最终状态就能收敛到一致。当然真实场景要比这个复杂得多还要考虑操作顺序、版本冲突、光标位置同步等问题。但从 Demo 层面验证广播 mutation这条路是可行的。如果你打算做多人协作我建议先在 Vuex 里把所有画布操作统一成几个标准 action比如addNode、removeNode、updateNode、addEdge、removeEdge再让 WebSocket 层去转发这些标准动作而不是把各种组件里的杂散操作都广播出去。最后再说一个我个人的体会。Demo 阶段最容易忽略的是数据流的边界很多人写着写着就把 g6 实例、节点数组、临时状态混在了一起导致后面重构成本非常高。我建议你动手之前先画一张图写在 README 里也行谁产生数据、谁消费数据、谁负责渲染、谁负责落盘。把这条链路想清楚这个 Demo 写起来会顺手很多后续接持久化、协作也不会推翻重来。希望这篇内容能帮你少踩点坑。本文还有配套的精品资源点击获取