maxGraph 纯前端图表库上手指南：从第一行代码到工作流应用的完整教程

maxGraph 纯前端图表库上手指南：从第一行代码到工作流应用的完整教程

【免费下载链接】maxGraphmaxGraph is a fully client side JavaScript diagramming library项目地址: https://gitcode.com/gh_mirrors/ma/maxGraph

从"画图需求"到"甩手掌柜"：你需要这样一款图表库

做后台系统的朋友应该都有过这种经历：产品经理甩来一张流程图需求，说"加个拖拽编辑功能，节点能连、能保存、能回显"，你翻遍各种方案，要么是只能展示不能交互的死图，要么是重得离谱的付费框架，要么文档稀烂、遇到问题全靠玄学。

其实你需要的，是一个能纯前端搞定"建模 + 渲染 + 交互 + 持久化"闭环的图表库。maxGraph 正是这样一款 TypeScript 编写、零第三方依赖、基于 SVG 渲染的纯客户端 JavaScript 图表库。它继承了 mxGraph 的优秀基因并持续维护更新，从简单的"矩形连圆形"，到带泳道的复杂工作流，再到图论分析，都能在浏览器里一气呵成。

这篇文章不打算堆砌特性清单，而是想当一次你的"带路朋友"：从装包开始，一步步带你跑通第一个可交互示例，再用真实业务场景讲清楚它解决什么问题，最后给出避坑清单。看完你可以直接照着抄。

十分钟跑通第一个可交互图表示例

安装依赖

maxGraph 的核心包发布在 npm 上，一个命令搞定：

npm install @maxgraph/core

装完之后，你的项目里需要准备一个承载图表的容器元素。假设你的页面里有一个<div id="graph-container">，我们就可以开工了。

三段式代码：初始化、建节点、连边

下面这段代码完整复刻了 maxGraph 官方文档的入门示例，注释里写了每一行在做什么：

import { Graph, InternalEvent } from '@maxgraph/core'; // 1. 拿到容器元素，并屏蔽浏览器的默认右键菜单 const container = document.getElementById('graph-container'); InternalEvent.disableContextMenu(container); // 2. 创建图表实例，开启右键拖拽平移画布 const graph = new Graph(container); graph.setPanning(true); // 3. 在同一个事务里批量插入两个节点和一条连线 graph.batchUpdate(() => { const vertex01 = graph.insertVertex({ position: [10, 10], // 距离画布左上角的偏移 size: [100, 100], // 节点宽高 value: '矩形节点', // 节点上显示的文字 }); const vertex02 = graph.insertVertex({ position: [350, 90], size: [50, 50], style: { fillColor: 'orange', // 填充色 shape: 'ellipse', // 圆形 }, value: '圆形节点', }); graph.insertEdge({ source: vertex01, // 起点 target: vertex02, // 终点 value: '连接线', style: { edgeStyle: 'orthogonalEdgeStyle', // 直角折线 rounded: true, }, }); });

你可能会好奇：这段代码为什么能"画出来"？关键在new Graph(container)这一步——maxGraph 的 Graph 类会自动注册全部默认能力（内置形状、样式、交互插件），你不需要手动注册任何东西。而batchUpdate把多个模型改动放进同一个事务，界面只重绘一次，性能更好，这也是它推荐的写法。

跑起来之后，你会发现这已经是一个"活的"图了：节点可以拖拽移动、框选、双击改文字。这些交互不是我们写的，是库自带的。

三个真实业务场景，看懂它值在哪

场景一：工作流与泳道图，让跨部门流程一眼看懂

做 BPM、OA 审批这类系统时，最大的痛点是流程涉及多个角色（客服、仓库、供应商），靠干巴巴的文字描述根本说不清协作关系。maxGraph 用泳道（Swimlane）把不同角色的节点分区摆放，配合带箭头的连线表达流转方向，效果一目了然：

这张图能解决的问题是"沟通成本"：业务方不再需要读长篇文档，鼠标移到节点上就能看到交互反馈，评审会上直接拖拽调整流程节点，改完立刻导出。这样的图，代码里其实就是一个一个的 vertex（节点）加 edge（连线），泳道本身也是一个容器型 vertex。

场景二：自动布局，让杂乱无章的节点各归其位

手工摆放几十个节点是灾难，总有人把节点叠在一起。maxGraph 内置了一套自动布局算法，其中一个很常用的是层级布局HierarchicalLayout，适合流程图和组织架构图：

import { HierarchicalLayout } from '@maxgraph/core'; // 执行一次层级布局，让所有节点自动排成有层次的树状结构 const layout = new HierarchicalLayout(graph); graph.getDataModel().beginUpdate(); try { layout.execute(graph.getDefaultParent()); } finally { graph.getDataModel().endUpdate(); }

除了层级布局，maxGraph 还提供圆形布局、树形布局、力导向布局等。它的布局 API 设计得很"正交"：布局算法只负责计算坐标，和你的业务数据解耦，你可以对任意一组节点执行任意布局。

场景三：图论分析，最短路径这类专业需求也有基础支撑

如果你的图表不只是"画出来给人看"，还要做路径分析（比如网络拓扑里的故障链路定位），maxGraph 同样支持。它能从模型里提取图结构，配合图论操作计算最短路径等指标：

这类能力让 maxGraph 能服务偏专业的领域，而不只是画个示意图那么简单。

拆解两个核心机制，知其所以然

机制一：Graph Model 三元组——顶点、边、分组

maxGraph 的一切都围绕模型（Graph Data Model）展开。理解它只需记住三个概念：

• 顶点（Vertex）：图里的"点"，可以是矩形、圆形，甚至自定义形状，负责承载标签、数据和样式。
• 边（Edge）：图里的"线"，通常连接两个顶点，也可以一端悬空（比如还没画完的连线）。
• 分组（Group）：顶点嵌套顶点，形成父子结构，类似文件夹，支持整体折叠展开。

先记结论：不管你画什么图，都是在操作这三样东西。它们统称为 Cell，insertVertex和insertEdge返回的都是 Cell。

机制二：模型与视图分离——交互为什么这么顺滑

maxGraph 的架构里，数据模型负责"是什么"，视图负责"画成什么样"。你拖拽节点，改的是模型里的坐标；渲染层监听模型变化事件，自动更新 SVG。正因为所有交互都在浏览器本地完成，没有服务器往返，所以拖拽、缩放、连线都跟原生应用一样跟手。

新手避坑清单，帮你少走弯路

结合官方文档和社区反馈，我整理了几条高频坑：

1. 画出来是空白？先检查容器高度。graph-container必须有明确的尺寸，否则 SVG 画布高度为 0，什么都不会显示。
2. 序列化报"Maximum call stack size exceeded"？这是没注册 Codec。从 0.6.0 版本起，Codec 不再默认注册，使用序列化功能前要先调用对应的注册函数，比如registerModelCodecs()。这也是为了 tree-shaking 考虑——用多少注册多少。
3. 追求极致体积？别用 Graph，改用 BaseGraph。Graph会自动装载所有默认能力（方便），BaseGraph什么都不装（省包），需要哪些形状、样式、插件自己按需注册。
4. TypeScript 集成有版本门槛：需要 TypeScript 3.8 及以上，核心包同时提供 ESM 和 CommonJS 两种格式。
5. 想在项目中直接用@mxgraph/core？注意包名是@maxgraph/core，带 max 的才是正确的包。

下一步：动手吧

回到开头那个被流程图需求折磨的你：现在你知道了，一个纯前端的图表库可以同时解决"展示、交互、保存回显"三件事，不需要引一堆重型依赖，也不需要写几千行 DOM 操作。

建议你按这个节奏继续：

• 先跑通本文的示例，把节点样式改成虚线、圆角，体会getStylesheet()的全局样式能力；
• 再试试给连线加箭头、给节点加 tooltip，看看交互的完整度；
• 最后用 Codec 把图表导出成 XML，再 import 回来，打通"保存-回显"闭环。

接下来就看你的了：打开编辑器，安装@maxgraph/core，把第一个节点画出来，然后沿着你业务里最痛的那张图开始。遇到问题别慌，官方文档（packages/website/docs目录下的 getting-started、usage/graph、usage/codecs 等文档）就是最好的手边参考。图表的世界很大，但你的第一步，只需要一个矩形和一个圆形。

【免费下载链接】maxGraphmaxGraph is a fully client side JavaScript diagramming library项目地址: https://gitcode.com/gh_mirrors/ma/maxGraph