maxGraph图表库实战：几分钟上手，从零构建可交互的流程图应用

maxGraph图表库实战：几分钟上手，从零构建可交互的流程图应用

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

还在为产品里要嵌入流程图编辑器、但找不到合适的库而纠结吗？maxGraph 就是为你准备的答案。它是一款完全运行在浏览器端的 TypeScript 图表库，专门用来构建流程图、网络拓扑图、组织结构图这类"节点 + 连线"的交互式应用。读完这篇文章，你将掌握 maxGraph 的核心概念，写出第一个能运行、能拖拽、能缩放的图表，并避开新手最容易踩的坑。

这个库到底能干什么

简单说，maxGraph 就是一张"活"的画布：你能在上面放置顶点（就是各种形状的节点，比如矩形、椭圆），用边（就是连接线）把它们串起来，画完之后用户还能直接拖拽、缩放、编辑文字——体验和 draw.io 这类专业工具如出一辙。

它源于已经停更的 mxGraph，但用原生 TypeScript 重写，零第三方依赖，包体积更小，还提供了精确的类型提示。最特别的是，它把连接线、形状、插件都做成了"可插拔"的模块：想用哪个注册哪个，用不上的代码在打包时会被自动剔除。这就像一套乐高积木，基础件齐全，但你可以只挑自己需要的零件，拼出最适合的应用。

3步搭起你的第一个图表

在动手前先理解一个概念：图表模型。它就是图表的数据仓库，专门管理顶点、边和分组这三样东西。写代码时你只需关心"往模型里放什么"，至于怎么渲染到屏幕上，maxGraph 全包了。

下面这段代码创建一个 HTML 页面，页面里显示一个矩形和一个橙色圆形，中间用一条圆角连线串起来。先安装依赖，再把代码贴进你的入口文件：

npm install @maxgraph/core

import '@maxgraph/core/css/common.css'; import { Graph, InternalEvent } from '@maxgraph/core'; // 需要一个 id 为 graph-container 的 DOM 容器 const container = document.getElementById('graph-container')!; InternalEvent.disableContextMenu(container); // 屏蔽浏览器右键菜单 const graph = new Graph(container); graph.setPanning(true); // 按住鼠标右键拖动画布 // batchUpdate 相当于批量操作，一次事务内完成所有添加 graph.batchUpdate(() => { // 添加一个矩形顶点，position 是坐标，size 是宽高 const rect = graph.insertVertex({ position: [10, 10], size: [100, 100], value: '矩形节点', }); // 添加一个橙色圆形顶点，通过 style 定制外观 const circle = graph.insertVertex({ position: [350, 90], size: [50, 50], style: { fillColor: 'orange', shape: 'ellipse' }, value: '圆形节点', }); // 用一条正交折线把两个顶点连起来 graph.insertEdge({ source: rect, target: circle, value: '连接线', style: { edgeStyle: 'orthogonalEdgeStyle', rounded: true }, }); });

保存并刷新页面，一个矩形连一个圆形的图表就渲染出来了，而且可以直接拖拽移动节点。你还能通过graph.addListener(InternalEvent.CLICK, ...)监听点击事件，给每个节点挂上交互逻辑。

3个让开发效率翻倍的特性

自动布局：把"摆位置"交给算法。手动画流程图时最累的其实是排布坐标。maxGraph 内置了层级布局、树状布局、圆形布局等多种算法，你只需把节点丢进图里，调用一次布局函数，节点就会自动排列得整整齐齐。就像用洗衣机的甩干模式：衣服扔进去，转几圈拿出来就是平整的。

分组与折叠：用"文件夹"管理复杂图表。顶点可以作为父节点容纳其他顶点和边，形成子图。这很像电脑里的文件夹，你可以把一整套相关节点收进一个组里，一键折叠成一个小方块，需要时再展开。画大型系统架构图时，这个功能能把上千个节点的复杂度降一个量级。

SVG 渲染与零依赖：所见即所得，部署零负担。maxGraph 基于 SVG 渲染，画面在任何现代浏览器上都清晰锐利，缩放不模糊；并且它是纯前端库，不需要任何服务端配合，打包后丢到任何静态服务器上就能跑。

新手最常踩的3个坑

坑一：用默认的Graph就以为万事大吉。Graph为了开箱即用，会注册全部内置形状和插件，包体积偏大。如果你做的是面向用户的线上产品，建议改用BaseGraph——它不加载任何默认项，你按需注册形状、连线样式和插件，打包体积能小一大截。

坑二：增删节点时忘了包事务。每次修改模型都建议放进batchUpdate里。如果不这么做，不仅渲染性能变差，撤销/重做（undo/redo）的边界也会错乱，导致用户按 Ctrl+Z 时行为诡异。记住一条铁律：所有批量改动，永远包在batchUpdate(() => {...})里。

坑三：样式串到全局改不回来。getStylesheet().getDefaultVertexStyle()改的是全局默认样式，会影响之后创建的所有顶点。如果你只想改某一个节点，应该在insertVertex的style参数里单独指定，或者通过putCellStyle定义可复用的命名样式。

实战：用maxGraph做一个审批流看板

最后来点真格的：实现一个"订单审批流程"看板，涵盖"下单→库存检查→发货→延迟通知"的流转。关键代码只有三部分：创建流程泳道、插入流程节点、接入一个"点击节点高亮"的交互。

const graph = new Graph(container); graph.setPanning(true); graph.batchUpdate(() => { // 1. 创建两个泳道作为分组容器，节点放进对应泳道 const service = graph.insertVertex({ position: [20, 20], size: [560, 180], value: '客服组', style: { shape: 'swimlane' }, }); const warehouse = graph.insertVertex({ position: [20, 220], size: [560, 180], value: '仓库组', style: { shape: 'swimlane' }, }); // 2. 在泳道内添加流程节点 const enterOrder = graph.insertVertex({ parent: service, position: [40, 60], size: [120, 50], value: '录入订单', }); const receiveOrder = graph.insertVertex({ parent: warehouse, position: [40, 60], size: [120, 50], value: '接收订单', }); const checkStock = graph.insertVertex({ parent: warehouse, position: [200, 60], size: [120, 50], value: '库存检查', }); const ship = graph.insertVertex({ parent: warehouse, position: [360, 60], size: [120, 50], value: '安排发货', }); // 3. 用连线把流程串起来 graph.insertEdge({ source: enterOrder, target: receiveOrder, value: '' }); graph.insertEdge({ source: receiveOrder, target: checkStock, value: '' }); graph.insertEdge({ source: checkStock, target: ship, value: '有货' }); }); // 点击节点时，在控制台输出它的文本内容 graph.addListener(InternalEvent.CLICK, (_sender, evt) => { const cell = evt.getProperty('cell'); if (cell) console.log('你点击了:', cell.getValue()); });

注意看，insertVertex里的parent参数就是上面提到的分组能力，泳道就是这么"装"出来的。跑起来之后，你就能得到一个可以拖拽、点击反馈的迷你审批流系统。

到这里，你已经从"听说过"走到了"能上手"。maxGraph 的能力边界远不止这些——序列化到 XML、自定义形状、打印导出，官方文档都有配套示例和源码可参考。去把容器div换成你的业务场景，画一张属于你自己的图吧。你离"做出专业级图表应用"，只差一次npm install的距离。✨

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