简介这是一套面向中高级前端开发者与流程平台建设者的Vue3流程设计器实战源码专为内控类业务系统审批流程定制开发解决传统流程引擎前端可视化能力弱、配置灵活性不足等痛点。资源共81个文件含43个JavaScript核心逻辑文件、21个Vue组件实现交互界面、6个PNG图标资源及3个JSON配置文件辅以Vite构建配置、ESLint规范、Git忽略规则等标准化工程文件整体压缩包仅648KB轻量易集成。已有500人学习下载适合希望快速落地可配置审批流程的团队参考。读者可直接复用完整的流程图编辑器架构掌握AntV X6 2.0节点拖拽、边条件表达式解析、职能带布局、岗位/角色/审批人策略绑定等关键能力并基于清晰的src/modules/workflow、src/components/FlowEditor等模块结构进行二次开发。1. 用 Vue3 AntV X6 2.0 搭建可落地的流程设计器不是拼组件而是控节点生命周期与图谱状态流你可能已经试过用 Element Plus 拖拽生成流程图也写过基于 SVG 手动绘制连线的“伪设计器”——但真正上线的 BPM 系统、低代码平台或审批引擎需要的不是静态图形而是具备节点校验、连接合法性约束、多层级嵌套子图、实时拓扑分析、历史版本快照回溯能力的交互式图谱。Vue3 提供的响应式系统与组合式 API恰好能承接 X6 2.0 的底层图元抽象而 X6 2.0 不再是单纯渲染引擎它把「图Graph」定义为可监听、可序列化、可干预的运行时状态容器。本文不讲“如何引入 X6”而是聚焦于如何让 Vue3 的 reactive state 与 X6 的 graph 实例形成双向可信绑定避免手动同步引发的脏数据、重复渲染和事件丢失。适合正在开发 OA 审批流、运维编排面板、AI 工作流配置页的前端工程师尤其当你发现graph.toJSON()输出和 Vue data 不一致、连线拖拽后节点位置错乱、或撤销/重做失效时本方案提供可复现的底层锚点。2. 构建 Vue3 与 X6 2.0 的可信状态桥接层从 setup() 到 Graph 实例的生命周期对齐X6 2.0 的核心对象Graph是一个独立于框架的图谱运行时它内部维护着 cell节点/边、view视图、model数据模型三层结构。Vue3 的响应式系统若直接包裹graph实例会因 Proxy 代理与 X6 内部Object.defineProperty或Map操作冲突导致响应失效或内存泄漏。常见错误做法是const graph reactive(new Graph(...))—— 这会导致graph的cells、edges等属性无法被 Vue 正确追踪。正确路径是Vue 负责管理图谱的“元数据”如当前选中节点 ID、缩放比例、是否只读X6 负责管理图谱的“实体数据”cell 实例、连接关系、坐标二者通过显式事件通道通信。2.1 初始化 Graph 实例并注入 Vue 上下文在setup()中创建 Graph 时必须禁用 X6 自动渲染改由 Vue 控制挂载时机并将图实例暴露为ref以便后续操作// composables/useX6Graph.ts import { ref, onMounted, onUnmounted, watch } from vue import { Graph, Node, Edge } from antv/x6 export function useX6Graph(containerRef: RefHTMLElement | null) { const graphRef refGraph | null(null) const initGraph () { if (!containerRef.value) return // 关键禁用自动渲染交由 Vue 控制 DOM 生命周期 const graph new Graph({ container: containerRef.value, background: { color: #F5F5F5, }, grid: { type: dot, size: 10, }, interacting: { // 全局禁用默认拖拽由 Vue 逻辑接管 nodeMovable: false, edgeMovable: false, }, // 启用 undo/redo 栈但需与 Vue 的 history state 同步 history: true, keyboard: true, }) // 绑定到 ref避免被 reactive 包裹 graphRef.value graph // 注册全局事件监听器非 Vue 响应式 graph.on(cell:added, (args) { console.log(新节点加入:, args.cell.id) // 触发自定义事件供 Vue 侧处理业务逻辑 emit(cell-added, args.cell) }) graph.on(cell:removed, (args) { emit(cell-removed, args.cell) }) } onMounted(() { initGraph() }) onUnmounted(() { if (graphRef.value) { graphRef.value.dispose() // 必须调用 dispose 释放事件监听与 canvas graphRef.value null } }) return { graphRef, } }提示graph.dispose()是 X6 2.0 的强制清理接口未调用会导致内存泄漏。Vue 组件卸载时必须执行且不能依赖beforeUnmount因graph可能早于组件销毁。2.2 设计 Vue 状态与 X6 图谱的双向同步协议X6 的graph.toJSON()返回的是纯 JSON 数据但其cell实例包含大量不可序列化的函数与引用如view、model。因此同步必须分层进行同步方向数据类型同步时机Vue 侧处理方式X6 → Vuecell.id,cell.getData(),graph.getCells()cell:added/cell:changed事件更新refMapstring, CellData触发 computed 衍生Vue → X6nodeId,newData,edgeSourceTarget用户操作如表单提交、连线确认调用graph.getCellById(id)?.setData(newData)定义可序列化的CellData类型// types/x6.d.ts export interface CellData { id: string type: node | edge shape: string // rect, circle, custom-task x: number y: number width?: number height?: number label?: string // 业务字段由 getData() 返回 business?: { taskType?: string timeout?: number required?: boolean } } // 在 setup 中声明状态 const cellMap refMapstring, CellData(new Map()) const selectedCellId refstring | null(null) // 监听 X6 事件更新 map watch( () graphRef.value, (graph) { if (!graph) return graph.on(cell:added, (args) { const cell args.cell const data: CellData { id: cell.id, type: cell.isNode() ? node : edge, shape: cell.shape, x: cell.position.x, y: cell.position.y, ...cell.getData(), // 仅取业务数据 } cellMap.value.set(cell.id, data) if (cell.isNode()) { // 节点添加后自动选中可选 selectedCellId.value cell.id } }) }, { immediate: true } )2.2.1 节点拖拽的 Vue 层控制逻辑X6 默认允许拖拽但若需与 Vue 表单联动如拖拽后弹出属性面板应关闭 X6 原生拖拽改用 Vue 指令接管!-- components/X6Canvas.vue -- template div refcontainerRef classx6-canvas mousedownhandleCanvasMousedown / /template script setup langts import { ref, onMounted } from vue import { useX6Graph } from /composables/useX6Graph const containerRef refHTMLElement | null(null) const { graphRef } useX6Graph(containerRef) // 禁用 X6 原生拖拽 onMounted(() { if (graphRef.value) { graphRef.value.setInteracting({ nodeMovable: false }) } }) const handleCanvasMousedown (e: MouseEvent) { // 判断是否点击空白处非 cell const target e.target as HTMLElement if (target.classList.contains(x6-cell)) return // 清除当前选中 if (graphRef.value graphRef.value.getSelectedCells().length 0) { graphRef.value.clearSelection() } } /script注意X6 的clearSelection()不会触发selection:changed事件需手动广播状态变更。此处selectedCellId.value null应在clearSelection()后同步设置。3. 实现可复用的流程节点组件体系基于 X6 自定义节点与 Vue3 插槽的深度集成AntV X6 2.0 支持通过Graph.registerNode()注册自定义节点但若直接在registerNode中写 Vue 组件会破坏 SSR 兼容性且无法响应 props。正确做法是X6 负责渲染节点骨架SVG/HTMLVue 负责注入动态内容与交互逻辑二者通过cell.view的update方法桥接。3.1 注册支持 Vue 插槽的通用节点容器X6 节点的view是一个类继承自NodeView。我们创建VueNodeView在render()中创建一个空div作为 Vue 挂载点在update()中触发 Vue 组件重渲染// views/VueNodeView.ts import { NodeView, Node } from antv/x6 import { createApp, h, Teleport, defineComponent } from vue export class VueNodeView extends NodeView { private app: ReturnTypetypeof createApp | null null private mountPoint: HTMLDivElement | null null render() { // 创建挂载容器 this.mountPoint document.createElement(div) this.mountPoint.className vue-node-container this.container.appendChild(this.mountPoint) // 创建 Vue App const Component defineComponent({ props: [cell, graph], setup(props) { return () h(div, { class: node-content }, [ // 通过插槽注入 Vue 组件 h(slot, { name: content }, { cell: props.cell, graph: props.graph, }), ]) }, }) this.app createApp(Component, { cell: this.cell, graph: this.graph, }) // 挂载到 mountPoint this.app.mount(this.mountPoint) return this.container } update() { // 当 cell 数据变更时更新 Vue props if (this.app this.mountPoint) { // 强制更新 propsX6 2.0 中 cell.setData 后会触发此方法 this.app.config.props { cell: this.cell, graph: this.graph, } // 触发重新渲染 this.app._instance?.update() } } remove() { if (this.app) { this.app.unmount() this.app null } if (this.mountPoint) { this.mountPoint.remove() this.mountPoint null } } }3.2 创建业务节点组件审批节点、条件分支、人工任务基于VueNodeView注册具体节点类型// nodes/ApprovalNode.ts import { Node } from antv/x6 import { VueNodeView } from /views/VueNodeView // 注册节点形状 Node.registry.register(approval-node, { view: VueNodeView, width: 120, height: 60, attrs: { body: { fill: #409EFF, stroke: #409EFF, strokeWidth: 1, }, }, }) // 在 Vue 组件中使用 // components/ApprovalNode.vue template div classapproval-node div classicon/div div classlabel{{ cell.getData().label || 审批节点 }}/div div classbadge v-ifcell.getData().required必填/div /div /template script setup langts import { inject } from vue const props defineProps{ cell: any graph: any }() // 可在此处监听 cell.data 变更触发局部更新 /script style scoped .approval-node { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 8px; font-size: 12px; color: white; } .icon { font-size: 16px; } .badge { margin-top: 4px; font-size: 10px; background: #f56c6c; color: white; padding: 2px 6px; border-radius: 10px; } /style3.3 连线逻辑的合法性校验与动态样式X6 的Edge默认允许任意连接但真实流程中需限制审批节点不能直连条件分支人工任务后必须接通知节点。校验逻辑应在edge:connecting事件中实现// 在 useX6Graph 中添加 graph.on(edge:connecting, (args) { const { sourceCell, targetCell } args if (!sourceCell || !targetCell) return const sourceType sourceCell.getData()?.type const targetType targetCell.getData()?.type // 定义连接规则 const rules: Recordstring, string[] { approval-node: [condition-node, notify-node], condition-node: [approval-node, end-node], notify-node: [end-node], } const allowed rules[sourceType] || [] if (!allowed.includes(targetType)) { args.preventDefault() // 阻止非法连接 console.warn(禁止连接${sourceType} → ${targetType}) } }) // 动态连线样式根据 target 类型改变颜色 graph.on(edge:connected, (args) { const edge args.edge const target edge.getTargetCell() if (target target.getData()?.type end-node) { edge.attr(line/stroke, #67C23A) } })提示edge:connecting发生在鼠标松开前edge:connected发生在连接确认后。前者用于拦截后者用于视觉反馈。4. 流程图序列化与反序列化JSON Schema 兼容的持久化方案X6 的graph.toJSON()输出格式不稳定版本间有差异且包含大量调试字段如__type__、__id__。生产环境需定义精简、可验证、向前兼容的流程图 Schema并实现双向转换。4.1 定义流程图 JSON Schema符合 OpenAPI 3.0// schemas/process-diagram.json { $schema: https://json-schema.org/draft/2020-12/schema, type: object, properties: { version: { type: string, pattern: ^\\d\\.\\d\\.\\d$ }, nodes: { type: array, items: { type: object, properties: { id: { type: string }, type: { enum: [approval-node, condition-node, notify-node, end-node] }, position: { type: object, properties: { x: { type: number }, y: { type: number } } }, data: { type: object, additionalProperties: true } } } }, edges: { type: array, items: { type: object, properties: { id: { type: string }, source: { type: string }, target: { type: string }, data: { type: object, additionalProperties: true } } } } } }4.2 实现 toProcessJSON() 与 fromProcessJSON() 工具函数// utils/x6-serializer.ts import { Graph, Cell } from antv/x6 export interface ProcessDiagram { version: string nodes: Array{ id: string type: string position: { x: number; y: number } data: Recordstring, any } edges: Array{ id: string source: string target: string data: Recordstring, any } } export function toProcessJSON(graph: Graph): ProcessDiagram { const cells graph.getCells() const nodes: ProcessDiagram[nodes] [] const edges: ProcessDiagram[edges] [] cells.forEach((cell) { if (cell.isNode()) { nodes.push({ id: cell.id, type: cell.shape, position: cell.position, data: cell.getData(), }) } else if (cell.isEdge()) { edges.push({ id: cell.id, source: (cell.getSourceCell() as Cell)?.id || , target: (cell.getTargetCell() as Cell)?.id || , data: cell.getData(), }) } }) return { version: 2.0.0, nodes, edges, } } export function fromProcessJSON(graph: Graph, json: ProcessDiagram) { // 清空现有图 graph.resetCells() // 重建节点 json.nodes.forEach((node) { graph.addNode({ id: node.id, shape: node.type, x: node.position.x, y: node.position.y, data: node.data, }) }) // 重建连线 json.edges.forEach((edge) { graph.addEdge({ id: edge.id, source: edge.source, target: edge.target, data: edge.data, }) }) }4.3 在 Vue 组件中集成保存/加载逻辑!-- components/ProcessDesigner.vue -- template div classdesigner div classtoolbar button clickhandleSave 保存流程/button button clickhandleLoad 加载流程/button input typefile changeonFileChange accept.json reffileInput classhidden / /div div refcanvasRef classcanvas / /div /template script setup langts import { ref, onMounted } from vue import { useX6Graph } from /composables/useX6Graph import { toProcessJSON, fromProcessJSON } from /utils/x6-serializer import { saveAs } from file-saver const canvasRef refHTMLElement | null(null) const fileInput refHTMLInputElement | null(null) const { graphRef } useX6Graph(canvasRef) const handleSave () { if (!graphRef.value) return const json toProcessJSON(graphRef.value) const blob new Blob([JSON.stringify(json, null, 2)], { type: application/json, }) saveAs(blob, process-${Date.now()}.json) } const handleLoad () { fileInput.value?.click() } const onFileChange (e: Event) { const input e.target as HTMLInputElement const file input.files?.[0] if (!file) return const reader new FileReader() reader.onload (ev) { try { const json JSON.parse(ev.target?.result as string) as any if (graphRef.value) { fromProcessJSON(graphRef.value, json) } } catch (err) { console.error(加载失败:, err) alert(JSON 格式错误请检查文件内容) } } reader.readAsText(file) } /script注意fromProcessJSON中调用graph.resetCells()会清空所有 cell包括事件监听器。若需保留cell:added等监听应在resetCells()前缓存事件重置后再重新绑定。5. 调试与性能优化定位 X6 渲染卡顿、Vue 响应式失效与图谱状态漂移当流程图节点超过 200 个或频繁触发graph.autoResize()时页面可能出现明显卡顿。这不是 Vue 的问题而是 X6 的view渲染与 Vue 的patch过程存在竞争。根本解法是分离渲染关注点X6 负责像素级绘制Vue 负责逻辑状态二者通过 requestIdleCallback 协同调度。5.1 使用 requestIdleCallback 批量同步节点状态避免在cell:changed事件中直接更新cellMap.value.set()改用空闲时间批量处理// composables/useX6Graph.ts续 import { ref, onMounted, onUnmounted, watch } from vue import { Graph } from antv/x6 export function useX6Graph(containerRef: RefHTMLElement | null) { // ... 前面代码保持不变 // 批量更新队列 const pendingUpdates ref{ id: string; data: any }[]([]) let idleHandle: number | null null const flushPendingUpdates () { if (pendingUpdates.value.length 0) return // 批量更新 map pendingUpdates.value.forEach(({ id, data }) { cellMap.value.set(id, data) }) pendingUpdates.value [] } const scheduleFlush () { if (idleHandle ! null) return idleHandle requestIdleCallback(() { flushPendingUpdates() idleHandle null }, { timeout: 1000 }) } // 在 cell:changed 中入队 graph.on(cell:changed, (args) { const cell args.cell pendingUpdates.value.push({ id: cell.id, data: { id: cell.id, type: cell.isNode() ? node : edge, ...cell.getData(), }, }) scheduleFlush() }) onUnmounted(() { if (idleHandle ! null) { cancelIdleCallback(idleHandle) idleHandle null } }) return { graphRef, cellMap, } }5.2 排查 Vue 响应式失效的三个关键检查点现象常见原因验证命令解决方案cellMap.value.get(id)返回undefined但graph.getCellById(id)存在cell:added事件未触发或监听未注册console.log(graph.events)查看事件列表确保graph.on(cell:added, ...)在graph实例创建后立即调用节点位置拖拽后cell.position更新但 Vue 中x/y未变cell.position是 getter/setter直接赋值无效cell.setPosition({ x: 100, y: 200 })使用 X6 提供的 setter 方法而非cell.position.x 100graph.toJSON()输出含__x6__字段JSON Schema 校验失败X6 2.0 默认输出调试字段graph.toJSON({ skipObjects: true })传入{ skipObjects: true }参数过滤不可序列化字段5.3 图谱状态漂移的终极验证diff 两版 JSON 输出当用户抱怨“保存后打开样式变了”大概率是graph.toJSON()与toProcessJSON()输出不一致。编写快速 diff 工具# 将当前图导出为 current.json加载旧版为 old.json npx json-diff -u old.json current.json重点关注nodes[].position是否被四舍五入X6 默认保留小数点后 2 位而 Vue 输入框可能截断edges[].source/target是否为空字符串getCellById()返回null时未做空值保护nodes[].data中日期字段是否被转为字符串new Date()→toISOString()修正示例在toProcessJSON中// utils/x6-serializer.ts修正版 function sanitizeData(data: Recordstring, any): Recordstring, any { const result: Recordstring, any {} Object.keys(data).forEach((key) { const value data[key] if (value instanceof Date) { result[key] value.toISOString() } else if (typeof value object value ! null !Array.isArray(value)) { result[key] sanitizeData(value) } else { result[key] value } }) return result }X6 2.0 的cell.getData()返回原始对象不做类型归一化。生产环境必须对data字段做白名单清洗而非无脑透传。本文还有配套的精品资源点击获取 Vue3与AntV X6 2.0状态桥接实战：构建可信流程图谱
简介这是一套面向中高级前端开发者与流程平台建设者的Vue3流程设计器实战源码专为内控类业务系统审批流程定制开发解决传统流程引擎前端可视化能力弱、配置灵活性不足等痛点。资源共81个文件含43个JavaScript核心逻辑文件、21个Vue组件实现交互界面、6个PNG图标资源及3个JSON配置文件辅以Vite构建配置、ESLint规范、Git忽略规则等标准化工程文件整体压缩包仅648KB轻量易集成。已有500人学习下载适合希望快速落地可配置审批流程的团队参考。读者可直接复用完整的流程图编辑器架构掌握AntV X6 2.0节点拖拽、边条件表达式解析、职能带布局、岗位/角色/审批人策略绑定等关键能力并基于清晰的src/modules/workflow、src/components/FlowEditor等模块结构进行二次开发。1. 用 Vue3 AntV X6 2.0 搭建可落地的流程设计器不是拼组件而是控节点生命周期与图谱状态流你可能已经试过用 Element Plus 拖拽生成流程图也写过基于 SVG 手动绘制连线的“伪设计器”——但真正上线的 BPM 系统、低代码平台或审批引擎需要的不是静态图形而是具备节点校验、连接合法性约束、多层级嵌套子图、实时拓扑分析、历史版本快照回溯能力的交互式图谱。Vue3 提供的响应式系统与组合式 API恰好能承接 X6 2.0 的底层图元抽象而 X6 2.0 不再是单纯渲染引擎它把「图Graph」定义为可监听、可序列化、可干预的运行时状态容器。本文不讲“如何引入 X6”而是聚焦于如何让 Vue3 的 reactive state 与 X6 的 graph 实例形成双向可信绑定避免手动同步引发的脏数据、重复渲染和事件丢失。适合正在开发 OA 审批流、运维编排面板、AI 工作流配置页的前端工程师尤其当你发现graph.toJSON()输出和 Vue data 不一致、连线拖拽后节点位置错乱、或撤销/重做失效时本方案提供可复现的底层锚点。2. 构建 Vue3 与 X6 2.0 的可信状态桥接层从 setup() 到 Graph 实例的生命周期对齐X6 2.0 的核心对象Graph是一个独立于框架的图谱运行时它内部维护着 cell节点/边、view视图、model数据模型三层结构。Vue3 的响应式系统若直接包裹graph实例会因 Proxy 代理与 X6 内部Object.defineProperty或Map操作冲突导致响应失效或内存泄漏。常见错误做法是const graph reactive(new Graph(...))—— 这会导致graph的cells、edges等属性无法被 Vue 正确追踪。正确路径是Vue 负责管理图谱的“元数据”如当前选中节点 ID、缩放比例、是否只读X6 负责管理图谱的“实体数据”cell 实例、连接关系、坐标二者通过显式事件通道通信。2.1 初始化 Graph 实例并注入 Vue 上下文在setup()中创建 Graph 时必须禁用 X6 自动渲染改由 Vue 控制挂载时机并将图实例暴露为ref以便后续操作// composables/useX6Graph.ts import { ref, onMounted, onUnmounted, watch } from vue import { Graph, Node, Edge } from antv/x6 export function useX6Graph(containerRef: RefHTMLElement | null) { const graphRef refGraph | null(null) const initGraph () { if (!containerRef.value) return // 关键禁用自动渲染交由 Vue 控制 DOM 生命周期 const graph new Graph({ container: containerRef.value, background: { color: #F5F5F5, }, grid: { type: dot, size: 10, }, interacting: { // 全局禁用默认拖拽由 Vue 逻辑接管 nodeMovable: false, edgeMovable: false, }, // 启用 undo/redo 栈但需与 Vue 的 history state 同步 history: true, keyboard: true, }) // 绑定到 ref避免被 reactive 包裹 graphRef.value graph // 注册全局事件监听器非 Vue 响应式 graph.on(cell:added, (args) { console.log(新节点加入:, args.cell.id) // 触发自定义事件供 Vue 侧处理业务逻辑 emit(cell-added, args.cell) }) graph.on(cell:removed, (args) { emit(cell-removed, args.cell) }) } onMounted(() { initGraph() }) onUnmounted(() { if (graphRef.value) { graphRef.value.dispose() // 必须调用 dispose 释放事件监听与 canvas graphRef.value null } }) return { graphRef, } }提示graph.dispose()是 X6 2.0 的强制清理接口未调用会导致内存泄漏。Vue 组件卸载时必须执行且不能依赖beforeUnmount因graph可能早于组件销毁。2.2 设计 Vue 状态与 X6 图谱的双向同步协议X6 的graph.toJSON()返回的是纯 JSON 数据但其cell实例包含大量不可序列化的函数与引用如view、model。因此同步必须分层进行同步方向数据类型同步时机Vue 侧处理方式X6 → Vuecell.id,cell.getData(),graph.getCells()cell:added/cell:changed事件更新refMapstring, CellData触发 computed 衍生Vue → X6nodeId,newData,edgeSourceTarget用户操作如表单提交、连线确认调用graph.getCellById(id)?.setData(newData)定义可序列化的CellData类型// types/x6.d.ts export interface CellData { id: string type: node | edge shape: string // rect, circle, custom-task x: number y: number width?: number height?: number label?: string // 业务字段由 getData() 返回 business?: { taskType?: string timeout?: number required?: boolean } } // 在 setup 中声明状态 const cellMap refMapstring, CellData(new Map()) const selectedCellId refstring | null(null) // 监听 X6 事件更新 map watch( () graphRef.value, (graph) { if (!graph) return graph.on(cell:added, (args) { const cell args.cell const data: CellData { id: cell.id, type: cell.isNode() ? node : edge, shape: cell.shape, x: cell.position.x, y: cell.position.y, ...cell.getData(), // 仅取业务数据 } cellMap.value.set(cell.id, data) if (cell.isNode()) { // 节点添加后自动选中可选 selectedCellId.value cell.id } }) }, { immediate: true } )2.2.1 节点拖拽的 Vue 层控制逻辑X6 默认允许拖拽但若需与 Vue 表单联动如拖拽后弹出属性面板应关闭 X6 原生拖拽改用 Vue 指令接管!-- components/X6Canvas.vue -- template div refcontainerRef classx6-canvas mousedownhandleCanvasMousedown / /template script setup langts import { ref, onMounted } from vue import { useX6Graph } from /composables/useX6Graph const containerRef refHTMLElement | null(null) const { graphRef } useX6Graph(containerRef) // 禁用 X6 原生拖拽 onMounted(() { if (graphRef.value) { graphRef.value.setInteracting({ nodeMovable: false }) } }) const handleCanvasMousedown (e: MouseEvent) { // 判断是否点击空白处非 cell const target e.target as HTMLElement if (target.classList.contains(x6-cell)) return // 清除当前选中 if (graphRef.value graphRef.value.getSelectedCells().length 0) { graphRef.value.clearSelection() } } /script注意X6 的clearSelection()不会触发selection:changed事件需手动广播状态变更。此处selectedCellId.value null应在clearSelection()后同步设置。3. 实现可复用的流程节点组件体系基于 X6 自定义节点与 Vue3 插槽的深度集成AntV X6 2.0 支持通过Graph.registerNode()注册自定义节点但若直接在registerNode中写 Vue 组件会破坏 SSR 兼容性且无法响应 props。正确做法是X6 负责渲染节点骨架SVG/HTMLVue 负责注入动态内容与交互逻辑二者通过cell.view的update方法桥接。3.1 注册支持 Vue 插槽的通用节点容器X6 节点的view是一个类继承自NodeView。我们创建VueNodeView在render()中创建一个空div作为 Vue 挂载点在update()中触发 Vue 组件重渲染// views/VueNodeView.ts import { NodeView, Node } from antv/x6 import { createApp, h, Teleport, defineComponent } from vue export class VueNodeView extends NodeView { private app: ReturnTypetypeof createApp | null null private mountPoint: HTMLDivElement | null null render() { // 创建挂载容器 this.mountPoint document.createElement(div) this.mountPoint.className vue-node-container this.container.appendChild(this.mountPoint) // 创建 Vue App const Component defineComponent({ props: [cell, graph], setup(props) { return () h(div, { class: node-content }, [ // 通过插槽注入 Vue 组件 h(slot, { name: content }, { cell: props.cell, graph: props.graph, }), ]) }, }) this.app createApp(Component, { cell: this.cell, graph: this.graph, }) // 挂载到 mountPoint this.app.mount(this.mountPoint) return this.container } update() { // 当 cell 数据变更时更新 Vue props if (this.app this.mountPoint) { // 强制更新 propsX6 2.0 中 cell.setData 后会触发此方法 this.app.config.props { cell: this.cell, graph: this.graph, } // 触发重新渲染 this.app._instance?.update() } } remove() { if (this.app) { this.app.unmount() this.app null } if (this.mountPoint) { this.mountPoint.remove() this.mountPoint null } } }3.2 创建业务节点组件审批节点、条件分支、人工任务基于VueNodeView注册具体节点类型// nodes/ApprovalNode.ts import { Node } from antv/x6 import { VueNodeView } from /views/VueNodeView // 注册节点形状 Node.registry.register(approval-node, { view: VueNodeView, width: 120, height: 60, attrs: { body: { fill: #409EFF, stroke: #409EFF, strokeWidth: 1, }, }, }) // 在 Vue 组件中使用 // components/ApprovalNode.vue template div classapproval-node div classicon/div div classlabel{{ cell.getData().label || 审批节点 }}/div div classbadge v-ifcell.getData().required必填/div /div /template script setup langts import { inject } from vue const props defineProps{ cell: any graph: any }() // 可在此处监听 cell.data 变更触发局部更新 /script style scoped .approval-node { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 8px; font-size: 12px; color: white; } .icon { font-size: 16px; } .badge { margin-top: 4px; font-size: 10px; background: #f56c6c; color: white; padding: 2px 6px; border-radius: 10px; } /style3.3 连线逻辑的合法性校验与动态样式X6 的Edge默认允许任意连接但真实流程中需限制审批节点不能直连条件分支人工任务后必须接通知节点。校验逻辑应在edge:connecting事件中实现// 在 useX6Graph 中添加 graph.on(edge:connecting, (args) { const { sourceCell, targetCell } args if (!sourceCell || !targetCell) return const sourceType sourceCell.getData()?.type const targetType targetCell.getData()?.type // 定义连接规则 const rules: Recordstring, string[] { approval-node: [condition-node, notify-node], condition-node: [approval-node, end-node], notify-node: [end-node], } const allowed rules[sourceType] || [] if (!allowed.includes(targetType)) { args.preventDefault() // 阻止非法连接 console.warn(禁止连接${sourceType} → ${targetType}) } }) // 动态连线样式根据 target 类型改变颜色 graph.on(edge:connected, (args) { const edge args.edge const target edge.getTargetCell() if (target target.getData()?.type end-node) { edge.attr(line/stroke, #67C23A) } })提示edge:connecting发生在鼠标松开前edge:connected发生在连接确认后。前者用于拦截后者用于视觉反馈。4. 流程图序列化与反序列化JSON Schema 兼容的持久化方案X6 的graph.toJSON()输出格式不稳定版本间有差异且包含大量调试字段如__type__、__id__。生产环境需定义精简、可验证、向前兼容的流程图 Schema并实现双向转换。4.1 定义流程图 JSON Schema符合 OpenAPI 3.0// schemas/process-diagram.json { $schema: https://json-schema.org/draft/2020-12/schema, type: object, properties: { version: { type: string, pattern: ^\\d\\.\\d\\.\\d$ }, nodes: { type: array, items: { type: object, properties: { id: { type: string }, type: { enum: [approval-node, condition-node, notify-node, end-node] }, position: { type: object, properties: { x: { type: number }, y: { type: number } } }, data: { type: object, additionalProperties: true } } } }, edges: { type: array, items: { type: object, properties: { id: { type: string }, source: { type: string }, target: { type: string }, data: { type: object, additionalProperties: true } } } } } }4.2 实现 toProcessJSON() 与 fromProcessJSON() 工具函数// utils/x6-serializer.ts import { Graph, Cell } from antv/x6 export interface ProcessDiagram { version: string nodes: Array{ id: string type: string position: { x: number; y: number } data: Recordstring, any } edges: Array{ id: string source: string target: string data: Recordstring, any } } export function toProcessJSON(graph: Graph): ProcessDiagram { const cells graph.getCells() const nodes: ProcessDiagram[nodes] [] const edges: ProcessDiagram[edges] [] cells.forEach((cell) { if (cell.isNode()) { nodes.push({ id: cell.id, type: cell.shape, position: cell.position, data: cell.getData(), }) } else if (cell.isEdge()) { edges.push({ id: cell.id, source: (cell.getSourceCell() as Cell)?.id || , target: (cell.getTargetCell() as Cell)?.id || , data: cell.getData(), }) } }) return { version: 2.0.0, nodes, edges, } } export function fromProcessJSON(graph: Graph, json: ProcessDiagram) { // 清空现有图 graph.resetCells() // 重建节点 json.nodes.forEach((node) { graph.addNode({ id: node.id, shape: node.type, x: node.position.x, y: node.position.y, data: node.data, }) }) // 重建连线 json.edges.forEach((edge) { graph.addEdge({ id: edge.id, source: edge.source, target: edge.target, data: edge.data, }) }) }4.3 在 Vue 组件中集成保存/加载逻辑!-- components/ProcessDesigner.vue -- template div classdesigner div classtoolbar button clickhandleSave 保存流程/button button clickhandleLoad 加载流程/button input typefile changeonFileChange accept.json reffileInput classhidden / /div div refcanvasRef classcanvas / /div /template script setup langts import { ref, onMounted } from vue import { useX6Graph } from /composables/useX6Graph import { toProcessJSON, fromProcessJSON } from /utils/x6-serializer import { saveAs } from file-saver const canvasRef refHTMLElement | null(null) const fileInput refHTMLInputElement | null(null) const { graphRef } useX6Graph(canvasRef) const handleSave () { if (!graphRef.value) return const json toProcessJSON(graphRef.value) const blob new Blob([JSON.stringify(json, null, 2)], { type: application/json, }) saveAs(blob, process-${Date.now()}.json) } const handleLoad () { fileInput.value?.click() } const onFileChange (e: Event) { const input e.target as HTMLInputElement const file input.files?.[0] if (!file) return const reader new FileReader() reader.onload (ev) { try { const json JSON.parse(ev.target?.result as string) as any if (graphRef.value) { fromProcessJSON(graphRef.value, json) } } catch (err) { console.error(加载失败:, err) alert(JSON 格式错误请检查文件内容) } } reader.readAsText(file) } /script注意fromProcessJSON中调用graph.resetCells()会清空所有 cell包括事件监听器。若需保留cell:added等监听应在resetCells()前缓存事件重置后再重新绑定。5. 调试与性能优化定位 X6 渲染卡顿、Vue 响应式失效与图谱状态漂移当流程图节点超过 200 个或频繁触发graph.autoResize()时页面可能出现明显卡顿。这不是 Vue 的问题而是 X6 的view渲染与 Vue 的patch过程存在竞争。根本解法是分离渲染关注点X6 负责像素级绘制Vue 负责逻辑状态二者通过 requestIdleCallback 协同调度。5.1 使用 requestIdleCallback 批量同步节点状态避免在cell:changed事件中直接更新cellMap.value.set()改用空闲时间批量处理// composables/useX6Graph.ts续 import { ref, onMounted, onUnmounted, watch } from vue import { Graph } from antv/x6 export function useX6Graph(containerRef: RefHTMLElement | null) { // ... 前面代码保持不变 // 批量更新队列 const pendingUpdates ref{ id: string; data: any }[]([]) let idleHandle: number | null null const flushPendingUpdates () { if (pendingUpdates.value.length 0) return // 批量更新 map pendingUpdates.value.forEach(({ id, data }) { cellMap.value.set(id, data) }) pendingUpdates.value [] } const scheduleFlush () { if (idleHandle ! null) return idleHandle requestIdleCallback(() { flushPendingUpdates() idleHandle null }, { timeout: 1000 }) } // 在 cell:changed 中入队 graph.on(cell:changed, (args) { const cell args.cell pendingUpdates.value.push({ id: cell.id, data: { id: cell.id, type: cell.isNode() ? node : edge, ...cell.getData(), }, }) scheduleFlush() }) onUnmounted(() { if (idleHandle ! null) { cancelIdleCallback(idleHandle) idleHandle null } }) return { graphRef, cellMap, } }5.2 排查 Vue 响应式失效的三个关键检查点现象常见原因验证命令解决方案cellMap.value.get(id)返回undefined但graph.getCellById(id)存在cell:added事件未触发或监听未注册console.log(graph.events)查看事件列表确保graph.on(cell:added, ...)在graph实例创建后立即调用节点位置拖拽后cell.position更新但 Vue 中x/y未变cell.position是 getter/setter直接赋值无效cell.setPosition({ x: 100, y: 200 })使用 X6 提供的 setter 方法而非cell.position.x 100graph.toJSON()输出含__x6__字段JSON Schema 校验失败X6 2.0 默认输出调试字段graph.toJSON({ skipObjects: true })传入{ skipObjects: true }参数过滤不可序列化字段5.3 图谱状态漂移的终极验证diff 两版 JSON 输出当用户抱怨“保存后打开样式变了”大概率是graph.toJSON()与toProcessJSON()输出不一致。编写快速 diff 工具# 将当前图导出为 current.json加载旧版为 old.json npx json-diff -u old.json current.json重点关注nodes[].position是否被四舍五入X6 默认保留小数点后 2 位而 Vue 输入框可能截断edges[].source/target是否为空字符串getCellById()返回null时未做空值保护nodes[].data中日期字段是否被转为字符串new Date()→toISOString()修正示例在toProcessJSON中// utils/x6-serializer.ts修正版 function sanitizeData(data: Recordstring, any): Recordstring, any { const result: Recordstring, any {} Object.keys(data).forEach((key) { const value data[key] if (value instanceof Date) { result[key] value.toISOString() } else if (typeof value object value ! null !Array.isArray(value)) { result[key] sanitizeData(value) } else { result[key] value } }) return result }X6 2.0 的cell.getData()返回原始对象不做类型归一化。生产环境必须对data字段做白名单清洗而非无脑透传。本文还有配套的精品资源点击获取