Vue3+TS实战：用AntV X6快速搭建图编辑画布

先说我自己的一个直观感受：凡是做“流程编排”“脑图”“拓扑图”这类可视化功能的团队，一两周后都会聚到一起吵同一个问题——到底用自研 Canvas，还是套一个现成的图编辑引擎。去年我在某个中后台项目里做流程设计器，最初天真地想自己用 Canvas 画，结果光是“节点拖拽后的连线跟手”“撤销回退到上一步”“线自动避开其他节点”这三件事就耗掉了两轮迭代。最后切到 X6，配合 Vue3 和 TypeScript，反而几天就把第一版业务跑通了。这篇就把我实战中的上手路径和实用属性配置一次说清楚，给正在 Vue3 + TS 技术栈里选型图编辑方案的读者一个可直接参考的版本。

1. 先聊清楚：业务系统里的“连线画布”到底要怎么选型

1.1 三种常见的错误开局方式

我接触过不少团队做可视化连线功能，起步方式基本逃不过三种。

第一种是直接用 DOM 定位 + CSS 连线。节点用 div 摆，连线用 SVG 标签拼，缩放平移全靠手动改坐标。这种方式做静态展示还行，一旦需要拖拽、吸附、路由避障、撤销重做，代码量会失控到吓人的程度，而且每一步操作基本都绕不开手动计算坐标，后续维护基本是一条不归路。

第二种是自己在 Canvas 上从零实现。画矩形、画圆、画贝塞尔曲线本身不难，难的是坐标变换、事件命中检测、拖拽时的局部重绘、命中区域放大后的显示优化。这些能力任何一个拿出来都要按周计算排期。尤其是“线的端点要能被拖拽重连”“节点移动时线要跟着动”，自己写会陷入几何计算的无底洞。如果项目周期只有一两个月，我真心不建议从头造这个轮子。

第三种是用开源图编辑引擎，但只用了它的静态渲染能力。很多团队引入 X6 这类引擎后，只调用graph.addNode、graph.addEdge就把图画出来，然后就开始吐槽“这不就是个加强版 SVG 吗”。其实这不是引擎的问题，是还没理解它真正的价值在于交互层的整套能力，比如网格吸附、对齐辅助线、框选、撤销重做、快捷键、端口磁吸。这些东西如果全都自己实现，量级完全是另一个故事。

1.2 图编辑引擎到底帮你省掉了什么

选图编辑引擎之前，先搞清楚这类引擎的核心抽象。它把图上的所有元素统一成两类对象：节点（Node）和边（Edge）。节点负责承载内容，边负责表达关系。而连接关系里又有一个非常关键的概念叫端口（Port），也就是节点上允许连线接入的“连接桩”。

这三层抽象意味着什么？意味着你写业务代码时不再纠结“两个矩形之间画一条线需要计算端点的坐标”，而是直接说：“从 A 节点的右侧端口连到 B 节点的左侧端口”。引擎自己会处理端点跟随节点位置变化、连线在拖拽过程中的重绘、以及线条在不同路由策略下的走线方式。

实际开发中，图编辑引擎帮你省掉的大头是这三个方面：

• 交互层：拖拽节点、拖拽连线、框选、平移缩放、滚轮缩放，这些能力在引擎里是内置或插件化的，不需要你操心 DOM 事件绑定和坐标转换。
• 数据层：整个图是一个数据模型，节点、边、端口、元信息都可以序列化成 JSON。这意味着你从后端拿到配置数据，就能直接渲染出整张图；用户改完也能一键导出回传。
• 视图层：渲染方式支持 SVG 和 Vue/React 组件化节点，复杂业务节点可以直接用组件写，不用在底层绘制 API 里硬磕样式。

我的经验是：如果需求里包含“拖拽”“连线”“撤销”“缩放平移”中的任意两项，就别再用 DOM 硬凑了，直接评估引擎方案性价比更高。

1.3 为什么 Vue3 + TS 的组合更适合 X6

Vue3 的 Composition API 和组织拓扑管理图数据有天然契合点。图编辑场景里，图配置、选中状态、历史记录、数据快照是不是响应式对象、是否触发视图更新，这些都需要精准控制。Composition API 里可以用ref、computed、watch把这些状态组织得明明白白，比 Options API 下散落在各个data字段里的逻辑要清楚得多。

TypeScript 的最大价值则体现在 Graph 的配置项和节点数据结构上。X6 的配置项非常多，Graph 构造参数、节点属性、边属性、插件选项，如果没有类型提示，写错一个字段名可能要运行半天才发现。加上 TS 后，写配置时编辑器会直接把可选项列出来，这在属性记忆成本不低的引擎面前非常省心。

另外，X6 社区在 Vue 生态里的支持也一直跟得比较紧，Vue3 的组件节点、xx-vue-shape 渲染方案、状态同步这些都有现成实践。下面我直接从工程初始化的每一步说起，保证照着做就能看到画布。

2. 最小工程落地：Vite + Vue3 + TS + X6 怎么快速跑起来

2.1 脚手架创建与依赖明细

先创建一个干净的 Vue3 + TS 工程。我习惯用 Vite，起项目快，开发服务器热更新也快：

npm create vue@latest x6-demo

脚手架选项里选上 TypeScript，不要选 Router 和 Pinia，因为我们只做一个纯粹的图编辑验证工程，减少干扰项。

进到目录后安装核心依赖：

npm install @antv/x6

按官方文档和当前版本的推荐，如果需要 Vue 组件节点，还要安装对应的 Vue3 适配包。我实际使用的是@antv/x6-vue-shape，安装时它会自动匹配当前工程里的 Vue3 版本。如果后续需要选择、撤销、对齐线这类增强交互，再逐个安装插件包。这里有一个容易踩的版本坑：X6 2.x 的插件的 API 和 1.x 有较大变化，安装前一定要去仓库确认最新的 README，别直接复制旧教程里的初始化命令。

依赖装完后，我建议在vite.config.ts里确认一下项目的更目录和别名配置，后续写业务组件的时候用@别名会舒服很多：

import { fileURLToPath, URL } from 'node:url' import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)), }, }, })

2.2 第一个 Graph 实例：三行代码看到画布

在正式开始写节点之前，先做一个最小渲染。在src/components/下新建GraphContainer.vue，模板里放一个容器 div。注意 X6 是直接在这个 div 上创建 SVG 画布，所以必须给这个 div 一个确定的高度，否则画布会没高度，看起来就是白屏：

<template> <div ref="containerRef" class="graph-container" /> </template>

样式部分：

.graph-container { width: 1000px; height: 600px; border: 1px solid #d9d9d9; }

逻辑部分：

<script setup lang="ts"> import { onMounted, onBeforeUnmount, ref } from 'vue' import { Graph } from '@antv/x6' const containerRef = ref<HTMLDivElement | null>(null) let graph: Graph onMounted(() => { // 容器元素一定存在；通过非空断言让 TS 满意 graph = new Graph({ container: containerRef.value!, grid: true, background: { color: '#fafafa', }, }) }) onBeforeUnmount(() => { graph.dispose() }) </script>

这段代码跑起来后，页面中心会显示一个带网格背景的空白画布。网格是 X6 里最直观的视觉反馈，它可以帮助感知节点位置。grid: true等价于grid: { size: 10, visible: true }，表示网格点间距 10 像素、可见。如果你希望网格是双线网格（看起来更像方格纸），可以配置成：

grid: { size: 10, visible: true, type: 'doubleMesh', args: [{ color: '#eee', thickness: 1 }, { color: '#ddd', thickness: 1 }], },

2.3 TS 类型带来的配置安全感

用 TypeScript 写 Graph 配置时，我最想强调的一点是：Graph 构造参数的类型定义非常全，几乎涵盖了所有可开启的交互能力。你在编码时会发现，写mousewheel、panning、connecting这些字段时，编辑器会自动提示子选项，这个体验比对着文档翻半天要高效得多。

初始化时建议把Graph.Options的类型单独抽出来定义成变量，一方面是便于复用，另一方面也方便后续集中管理画布配置。比如：

import { Graph } from '@antv/x6' import type { GraphOptions } from '@antv/x6' const createGraphOptions = (container: HTMLElement): GraphOptions => ({ container, autoResize: true, grid: { size: 10, visible: true }, panning: { enabled: true, eventTypes: ['leftMouseDown'] }, mousewheel: { enabled: true, modifiers: ['ctrl', 'meta'], minScale: 0.5, maxScale: 2 }, })

这里autoResize: true会监听容器尺寸变化并自动重绘画布，对中后台动态布局很实用。panning开启后按住鼠标左键可以直接拖动画布，mousewheel配置成按住 Ctrl / Command 再滚轮缩放，符合大多数用户习惯。

3. 画图核心概念拆解：节点、边、端口背后的数据设计

3.1 节点数据模型：用 JSON 描述图形，而不是操作 DOM

X6 最大的思维转变在于：你要把图画看成一组可序列化数据，而不是一堆 DOM 或 Canvas 图元的操作指令。一个节点在代码里就是一个普通对象：

import { Graph } from '@antv/x6' graph.addNode({ id: 'start-node', x: 120, y: 80, width: 120, height: 48, label: '开始节点', attrs: { body: { fill: '#e6f7ff', stroke: '#1890ff', rx: 8, ry: 8, }, label: { text: '开始节点', fill: '#333', fontSize: 14, }, }, })

这里的attrs是用来描述节点内部 SVG 元素的属性。X6 的节点默认有一个body（矩形主体）和一个label（文本标签），这两个名字是内置的。如果你了解 SVG 基础，就能很快上手：rx和ry是矩形圆角，fill是填充色，stroke是边框色。

节点 ID 是一个重要设计。如果你不手动传 id，X6 会生成一个随机字符串，这在图表数据回传时会造成不稳定。我的习惯是所有节点都手动给业务语义化的 id，比如node-start-001，排查数据和做图间关联时会直观很多。

3.2 边的两种创建方式：引用 ID 和直接坐标

边表达的是连接关系，它有source和target两个端点。创建边最推荐的方式是通过节点 ID 引用：

graph.addEdge({ id: 'edge-start-to-task', source: 'start-node', target: 'task-node', router: 'manhattan', connector: 'rounded', attrs: { line: { stroke: '#333', strokeWidth: 2, targetMarker: 'block', }, }, })

这种方式的好处显而易见：当你拖动某个节点时，只要它和边的关系没有变，边就会自动跟随节点的新位置重新渲染。如果用直接坐标创建边，坐标是固定死的，节点一动，线就连不上了。

source和target也可以是更精细的对象，指定具体端口：

graph.addEdge({ source: { cell: 'start-node', port: 'out-port' }, target: { cell: 'task-node', port: 'in-port' }, })

这样连线就从 start-node 的 out-port 出发，指向 task-node 的 in-port。端口是图编辑中连线关系稳定的关键，下面细说。

router和connector这里也想多说一句。router 负责决定线的“路径算法”，manhattan 是很常用的正交路线，线会先水平走一段、再垂直走一段，整体是横平竖直的，看起来非常规整；connector 负责两个路径点之间的“连接方式”，rounded 会把折角变成圆角，视觉上更柔和。这两个属性在 X6 里是边上的独立配置，不是全局配置，当然也可以在 Graph 的 connecting 配置里统一设置默认值。

3.3 Port 端口配置：连接桩怎么做才顺手

端口是节点上可连接线的“挂载点”。没有端口时，边可以连接在节点边界上的任意点，用户连线很容易产生位置漂移。有了端口，边就会吸附到固定的连接桩上，连线关系看起来稳定很多。

端口的基本结构是groups加items。groups 定义一组端口的通用位置和样式，items 是具体的端口实例：

graph.addNode({ id: 'task-node', x: 360, y: 80, width: 160, height: 64, label: '任务节点', ports: { groups: { left: { position: 'left', attrs: { circle: { r: 4, magnet: true, stroke: '#1890ff', fill: '#fff', }, }, }, right: { position: 'right', attrs: { circle: { r: 4, magnet: true, stroke: '#1890ff', fill: '#fff', }, }, }, }, items: [ { id: 'in-port', group: 'left' }, { id: 'out-port', group: 'right' }, ], }, })

magnet: true这个属性很关键，它表示该端口可以作为连线的目标吸附点。我见过不少新人配了端口却发现还是不能吸附，十有八九是漏了magnet。

端口的位置不仅支持left、right这种内置枚举，也可以使用自定义坐标。比如希望端口均匀分布在节点底部，可以用一个字符串：

position: { name: 'bottom', args: { dx: 0, dy: 4, }, },

这里name是端口位置算法名，args是偏移参数。X6 内置的位置算法还挺多，left、right、top、bottom、absolute、ellipse等等。端口样式也完全可以自定义，不只是小圆点，还可以是方块、三角、带边框的圆，只要你愿意改 SVG 结构。

4. 高频实用属性清单：把编辑器调成“顺手”的状态

4.1 画布级配置开关：网格、缩放、平移、自动尺寸

Graph 的初始化参数里有一大批控制编辑器手感的能力，我按实用程度排个序，你配置的时候可以直接抄。

这里比较容易被忽视的是panning和scroller的区别。panning 是“手抓画布移动视角”，scroller 是“画布内嵌滚动容器”。它们可以同时存在，也可以只开其中一个。需求是“大画布小视口”的场景，比如一个 3000 × 2000 的画布放在 800 × 600 的容器里，最顺手的配置就是同时开启 scroller 和 panning，既可以用手拖，也可以通过滚动条看。

4.2 连接体验：校验、吸附、交互路由

连线是图编辑器的核心操作，X6 的 connecting 配置项基本决定了用户连线的体验。我常用的配置如下：

connecting: { snap: true, allowBlank: false, allowLoop: false, allowNode: false, allowEdge: false, highlight: true, connector: 'rounded', connectionPoint: 'boundary', }

逐项解释一下：

• snap: true表示连线时端点会磁吸到附近的端口或节点边界，也就是鼠标接近端口一定距离时自动吸附过去。这个对提升连线成功率体验帮助很大。
• allowBlank: false禁止画线到空白区域，用户如果没连接到有效目标，连线就不会生成，避免了一堆半成品线条。
• allowLoop: false禁止连线指向自己，防止出现无效的自环连接。
• allowNode: false表示不能把线的终点直接放到节点上，而必须放到端口上。如果你定义了规范端口，这条建议打开；如果节点没有端口，则需要保留默认值true。
• highlight: true在连线拖拽经过端口时高亮显示该端口，用户能清楚看到可连的位置。

还有一个小技巧是给整条边上的交互行为一个视觉反馈。比如连线成功后，通过事件把边高亮一下：

graph.on('edge:connected', ({ edge }) => { edge.attr({ line: { stroke: '#52c41a', strokeWidth: 3, targetMarker: 'block', }, }) })

这里edge:connected事件会在边成功建立连接后触发，我用它来改变边的颜色和线宽，让用户心理上明确“连接成功”。

4.3 历史记录、快捷键与撤销恢复

撤销重做是编辑器类产品不可少的功能。X6 在 2.x 中把历史记录作为独立插件提供，使用方式如下：

import { History } from '@antv/x6-plugin-history' graph.use(new History({ enabled: true }))

这里有个非常重要的顺序问题：必须先graph.use插件，然后才能调用graph.history.canUndo()等接口。我在初期就踩过这个坑，直接调graph.undo()结果报错，后来才发现是因为插件还没注册。

配合快捷键插件，可以实现 Ctrl+Z 撤销、Ctrl+Shift+Z 重做的标准操作：

import { Keyboard } from '@antv/x6-plugin-keyboard' graph.use(new Keyboard({ enabled: true })) graph.bindKey('ctrl+z', () => { if (graph.history.canUndo()) { graph.history.undo() } }) graph.bindKey('ctrl+shift+z', () => { if (graph.history.canRedo()) { graph.history.redo() } })

在实际项目中，我还会给删除操作绑定 Delete 键、给复制粘贴绑定 Ctrl+C / Ctrl+V。X6 的剪贴板插件用法和 history 类似：

import { Clipboard } from '@antv/x6-plugin-clipboard' graph.use(new Clipboard({ enabled: true })) graph.bindKey('ctrl+c', () => { const cells = graph.getSelectedCells() if (cells.length) { graph.copy(cells) } }) graph.bindKey('ctrl+v', () => { if (!graph.clipboard.isEmpty()) { graph.paste({ offset: 32 }) } })

注意这里paste返回的新节点会自动偏移动一定偏移，避免粘贴后完全覆盖在原节点上。我认为这个默认偏移量的设计非常实用，自己实现的时候也建议保留类似逻辑。

4.4 选中有感：框选、高亮、Resize 手柄

编辑器里“选择”的交互反馈决定了产品的精致程度。X6 的 selection 插件可以做得很细，我用过的配置如下：

import { Selection } from '@antv/x6-plugin-selection' graph.use( new Selection({ enabled: true, multiple: true, rubberband: true, movable: true, showNodeSelectionBox: true, }), )

• multiple: true支持多选，配合 Ctrl 点击可以选中多个节点。
• rubberband: true开启框选，用户可以在空白区域拖出一个选框，批量圈中多个节点。
• movable: true允许通过选中框拖动整组节点。
• showNodeSelectionBox: true会在选中节点周围显示虚线边框，视觉反馈更明显。

选中后我通常还会配合 Transform 插件提供自由缩放手柄，让用户能直接拖拽调整节点尺寸：

import { Transform } from '@antv/x6-plugin-transform' graph.use( new Transform({ resizing: { enabled: true, minWidth: 60, minHeight: 40, }, }), )

这几个插件组合起来，基本就是“拖过来就能编辑”的成熟编辑器手感了。实际项目里我还会监听selection:changed事件，把选中的节点列表同步到右侧属性面板里，这就是典型的“选中即编辑”的需求场景。

5. 让节点变成真正的 Vue 组件：数据流与事件联动

5.1 注册 Vue 组件节点

图编辑器到了业务复杂阶段，节点里不只是一行文字，通常会有封面图、状态标签、操作按钮、缩略信息这类内容。如果还靠着 attrs 一层层写 SVG，维护成本会很高。X6 生态里可以通过 Vue 组件渲染节点，节点内部的 DOM 结构完全由 Vue 组件负责。

前提是安装对应的适配包：

npm install @antv/x6-vue-shape

然后在代码里注册：

import { register } from '@antv/x6-vue-shape' import TaskNode from './components/TaskNode.vue' register({ shape: 'task-node', width: 200, height: 88, component: TaskNode, })

注册完成后，addNode 时指定shape: 'task-node'，引擎就会用这个 Vue 组件来渲染节点内容。组件的 props 会被注入node、graph等对象，让组件能拿到当前节点实例、所属画布实例，从而实现内部状态的自如展示。

5.2 组件内拿到节点数据，业务侧拿到组件事件

TaskNode 组件的内部实现大概长这样：

<script setup lang="ts"> import { computed } from 'vue' interface TaskNodeProps { node: any graph: any } const props = defineProps<TaskNodeProps>() const taskData = computed(() => props.node.getProp('taskData') || {}) const statusColor = computed(() => { const map: Record<string, string> = { pending: '#faad14', running: '#1890ff', success: '#52c41a', failed: '#f5222d', } return map[taskData.value.status] || '#999' }) </script> <template> <div class="task-node" :style="{ borderColor: statusColor }"> <div class="task-name">{{ taskData.name || '未命名任务' }}</div> <div class="task-status">{{ taskData.status || 'pending' }}</div> </div> </template>

这里有一个容易被绕晕的细节：为什么用node.getProp('taskData')，而不是直接用响应式变量？因为 X6 的节点数据是由引擎统一管理的，Vue 组件只是渲染器。当你在外部通过graph.getCellById(id).setProp('taskData', newData)更新节点数据后，组件内部并不能自动感知到 Vue 的响应式变化，需要通过监听节点的change:*事件来同步。

所以当业务侧要把新数据推给节点时，我建议这样操作：

const cell = graph.getCellById(nodeId) cell.setProp('taskData', { name: '新的任务名', status: 'running' })

而在组件内部，如果想要拿到最新数据驱动重新渲染，需要在onMounted里监听节点变化：

<script setup lang="ts"> import { onMounted, onBeforeUnmount, ref } from 'vue' const props = defineProps<{ node: any }>() const taskData = ref({}) const updateFromNode = () => { taskData.value = props.node.getProp('taskData') || {} } onMounted(() => { updateFromNode() props.node.on('change:taskData', updateFromNode) }) onBeforeUnmount(() => { props.node.off('change:taskData', updateFromNode) }) </script>

这种“图数据驱动 + 响应式渲染”的机制刚开始用会觉得绕，但它的优点很明显：节点数据始终只有一个来源，组件渲染是纯展示，不会出现一个节点数据被多处维护导致的不一致问题。

5.3 事件回传：节点按钮点击怎么冒泡到页面

节点组件内部发生了点击、拖拽、输入等行为，最终还是要让外层页面知道。常见的做法是 Vue 组件里 emit 事件，但 X6 节点渲染机制里，组件的事件并不能天然地冒泡到页面的 Vue 组件里。我的处理方式是用一个全局事件总线或直接调用画布实例的方法来间接通信。

比较直接的做法是事件抛到 node 上，再由外层监听 node 事件：

function handleButtonClick() { // 在节点对象上触发自定义事件 props.node.trigger('task-node:action', { moduleName: 'detail' }) }

外层页面统一监听：

graph.on('task-node:action', ({ node, args }) => { console.log('来自节点的操作:', args) })

这种方式的好处是让所有节点事件都汇到 Graph 这一层，页面里只需注册一次监听，不会因为组件挂载卸载导致监听残留。另一个方案是用提供注入的graph对象直接调用外部注册的回调，但那样会让节点组件和业务逻辑耦合得比较紧，我一般不用。

6. 真实项目里踩过的坑与调试方案

6.1 画布白屏或大小异常：先查容器，再查时机

白屏是 X6 初学者遇到最多的现象。排查链路我建议按这个顺序：

• 容器 div 是否有明确的宽高。最常见的原因是父元素高度塌陷，.graph-container设置了 600px 高度但父级没有高度，容器自身被压缩成 0。我给容器的建议是固定高度，或者给父层设置一个能满足业务的 min-height。
• Graph 初始化时机是否在 DOM 挂载之后。在 Vue3 里，onMounted里初始化是安全的，不能在setup顶层同步初始化，因为那时候容器元素还不存在。
• SPA 中侧边栏折叠或弹窗打开导致容器尺寸变化。如果没开autoResize: true，画布尺寸不会自动跟随。弹窗场景还有一个经典问题，就是弹窗初始化时容器尺寸可能是隐藏状态下的 0，等弹窗动画结束后才能拿到真实尺寸。

针对最后一个问题，我的建议是在弹窗完全打开后再初始化 Graph。如果框架弹窗的动画不好监听，就在初始化前先用一个 timeout 等待：

setTimeout(() => { graph = new Graph({ container: containerRef.value!, // ... }) }, 200)

这只是一种补救方案，更好的做法是给容器一个确定的宽高，避免依赖动画后的计算布局。

6.2 节点更新不刷新视图：先分清数据属性和视图属性

开发时很容易遇到一个问题：我调用了cell.setProp()改数据，但画布上的节点没有变化。排查的时候要分清楚改的是节点的基础位置尺寸（x、y、width、height），还是业务自定义数据（taskData 这类）。

如果改的是 x、y、width、height，组件节点默认不会自动更新组件内部的内容，因为组件内容由自定义数据决定，基础几何属性变化不会触发组件重新渲染。如果改的是自定义数据，需要在节点上触发对应事件，让组件监听后主动更新。

调试技巧：在控制台打印cell.getProp()看当前节点的完整数据，如果数据已经更新但视图没变，那就是渲染层监听的问题；如果数据本身没更新，那就是调用时机和节点 ID 的问题。

6.3 大数据量下的卡顿与局部刷新策略

图数据达到几百上千个节点时，任何操作都可能出现肉眼可见的卡顿。我在实践中靠三招缓解：

• 不要一次性渲染所有节点。先用局部数据渲染视口范围内的节点，通过滚动或缩放事件动态增删节点。X6 事件里可以通过graph.getArea()拿到当前视口区域，配合节点坐标做筛选。
• 使用graph.model的批量操作。连续 addNode 时用graph.model.addNodes(nodes)一次批量添加，而不是循环单个添加，避免每次添加都触发一次完整渲染。
• 关闭非必要的辅助能力。编辑过程中可以临时把snapline、highlight这类高开销功能关掉，完成节点布局后再恢复。

还有一个在业务中很实用的功能是graph.freeze()与graph.unfreeze()。freeze 后引擎会暂停自动重绘，适合在节点数据大规模批量导入时先用冻结模式把节点都塞进来，最后统一解冻一次性渲染。这样用户体验上不是慢慢一颗颗冒出来，而是整图一次成型，视觉上反而更加平滑。

6.4 离开页面时的清理：不能只靠 Vue 卸载

Vue 组件卸载时，X6 实例并不会自动销毁。如果不手动graph.dispose()，画布的事件监听和 DOM 可能仍然存在，单页应用里切路由再切回来，会出现两张画布重叠、事件错乱、内存泄漏这类问题。

我的固定写法是在onBeforeUnmount里处理：

onBeforeUnmount(() => { graph.dispose() })

同时，如果有用到graph.on()注册的全局事件，在销毁前可以不清除，dispose会一并清理。但如果监听是在 Graph 之外的全局对象上绑定的，比如window.addEventListener，那还是需要手动移除。

另外一个细节是，如果同一个页面里存在多个 Graph，比如几个卡片内同时渲染多个小图，那么每个容器和 Graph 实例都要一一对应。不要把同一个容器传给两个 Graph 实例，X6 会直接报错并挂掉。

6.5 调试利器：利用事件系统观察操作轨迹

X6 事件系统非常丰富，调试时我特别喜欢把关键操作打出来，看看自己到底触发了什么事件、事件参数里带了什么：

const debugEvents = [ 'node:moved', 'edge:connected', 'node:added', 'node:removed', 'selection:changed', 'history:change', ] debugEvents.forEach((eventName) => { graph.on(eventName, (args) => { console.log(`[${eventName}]`, args) }) })

在排查“为什么某个交互没反应”时，我通常先看对应的原生事件有没有触发。如果事件没触发，说明交互底层就有问题；如果事件触发了但页面没反应，那就是业务处理层的问题。这套二分法能节省大量排查时间。

最后再分享一点个人的使用体会

整套项目做下来，我最大的感受是：图编辑引擎这类工具，真正决定项目成败的往往不是“能不能画出图”，而是“交互细节和数据流的组织能不能撑住业务复杂度”。X6 把节点、边、端口、事件、插件这些基础能力都准备好了，我们要做的不是重复造轮子，而是把业务数据和引擎的数据模型对齐。

如果第一次接触，我给你的建议是先别急着接插件、写复杂节点，花一个下午把 Graph、addNode、addEdge、Port 这四个基本概念亲手跑一遍，再按需求把 selection、history、snapline 这些插件逐个加上。每加一个插件就实际拖拽操作五分钟，比对着文档看十遍效率高得多。等你把整条链路跑通了，再回头用 Vue 组件封装业务节点，整个项目的节奏会很顺，也不会再出现被我开头说的那三件事困住两周的情况。