★ FEATURED ARTICLE 先说句实在话翻过不少项目文档真正让人一眼就能看懂的图表比例真心不高。大部分图要么线头乱飞、颜色扎眼要么信息堆到一起完全分不清主次。所以当手头那个项目需要沉淀一套统一的图表设计能力时我把它命名为“diagram-design”——名字看着宽泛实际上要解决的事情非常具体把从视觉规范到实现组件的整套约定固化下来让任何人画出来的架构图、流程图、时序图都保持同一水准的清晰度与专业感。这篇文章就围绕这套东西展开讲讲图表设计背后真正值得投入的心思以及踩过哪些坑之后才明白的道理。1. 内容整体设计与思路拆解1.1 先想清楚“图表设计”到底在解决什么问题很多人把画图当成“把框框连起来”这是第一层误解。图表本质上是一种空间化的信息压缩把一堆文字描述不清的关系映射到二维空间的上下左右里让大脑通过位置、大小、颜色、连线的方向直接建立直觉。所以图表设计的第一性问题不是“好看”而是“在我没有讲解的情况下读者能否凭视觉推断出节点之间的关系、层次、流向和边界”。diagram-design 这个项目要解决的就是三件具体的事一是统一视觉语言同一个语义的节点在每张图里都长一个样二是统一关系表达连线、箭头、线型都有明确含义三是统一实现方式避免每次画图都从零堆砌代码。这三件事解决了图表才能从“我个人觉得没问题”变成“团队里谁来看都没问题”。在实际搭建的时候我给自己定了一条原则宁可少做酷炫功能也要保证底子干净。底子就是指节点、连线、画布三种基础抽象以及围绕它们建立的坐标、布局和交互逻辑。后来的事实证明这条原则大大降低了后期维护成本。1.2 方案选型为什么选数据驱动加 SVG当时摆在面前的选择无非是三类直接套用现成的绘图工具、基于 Canvas 自绘、基于 SVG 自建。现成工具能快速出图但定制能力和嵌入自有系统的自由度不够尤其不适合做成一套可编程的图表组件。Canvas 性能上限高但对 DOM 事件、无障碍和样式继承支持弱写起来也不够直观。最终选了 SVG理由很实在SVG 节点天然就是 DOM 元素CSS 可以直接控制样式调试和审查非常方便。每个节点可以独立绑定事件拖拽、点击、悬浮不费劲。文档结构即数据结构输出给 markdown 或者导出成独立文件都很干净。大多数项目场景的节点数量在几十到几百SVG 完全扛得住犯不着为极端场景牺牲开发效率。数据驱动是另一个关键决定。图表里所有内容都来自一份纯数据描述节点列表和连线列表。渲染层只负责把数据映射成 SVG 元素。这个决策带来一个很大好处数据结构清晰了布局算法、过滤、搜索、联动都能独立实现不被渲染细节捆住手脚。1.3 把设计系统拆成三个分层我把整个 diagram-design 的设计拆成三层每一层只关心自己的职责第一层是语义层规定“图里能出现什么”。比如节点类型有哪些服务、存储、外部实体、判断分支连线类型有哪些调用、数据流、依赖、消息。语义层不涉及具体颜色和坐标只定义抽象概念。第二层是视觉层把语义翻译成视觉参数。服务用什么形状、什么颜色调用线用什么线型、什么箭头间距多大、角标怎么放。视觉层是用户可以感知的那部分也是审美的主要发力点。第三层是实现层把视觉参数落成可运行的代码。包括节点渲染组件、连线路径生成算法、画布缩放平移、网格吸附、自动布局等。分层最大的价值在可替换性如果你想换一套视觉风格只需要替换第二层语义和实现都不用动如果发现连线算法性能不够只需要替换实现层的路径生成部分。三层各司其职后面扩展就不容易越改越乱。2. 核心视觉细节与实操要点2.1 用颜色之前先定义语义图表里颜色是最容易翻车的地方。常见问题是一张图用上十几种颜色每种颜色都代表一个具体服务乍一看五彩斑斓细看根本记不住谁是谁。我在 diagram-design 里把颜色使用收得很紧核心思路是“颜色只表语义不用来区分具体个体”。具体做法是定义一组语义色板每个颜色对应一种节点类型而不是对应一个具体服务名中性色用于普通处理节点、通用容器主色调用于核心服务节点警示色用于故障节点、异常流程强调色用于当前聚焦节点、高亮路径外部色用于第三方或外部依赖这样一来看图的人不需要去记“蓝色是 A 服务、绿色是 B 服务”只需要知道“蓝色系的节点都是同类角色”。如果要区分具体实例用文字标签不要只靠颜色。另外有个容易被忽略的问题颜色对比度。我踩过一回在投影仪上分享图表浅灰底纹配浅蓝文字后排直接看不清。后来加了道自查工序所有文字与背景的对比度至少达到 WCAG AA 级别背景色与节点的对比也尽量保持 3:1 以上。具体数值不需要背用在线对比度检查工具测一下低了对不上就加深色号。2.2 形状、字体、间距图表里的排版学形状不比颜色少讲究。节点形状应该能辅助语义识别而不是当装饰品。我常用的对应关系是矩形通用处理节点、后端服务圆角矩形前端界面、用户交互入口菱形判断分支圆柱体数据存储云形外部依赖、第三方系统这样设计的好处是即使把颜色去掉你依然能通过形状猜出节点的角色。对色弱用户、黑白打印场景来说这种冗余表达特别重要。实际实现时圆柱和云形需要一点自定义 path但如果用标准 SVG 语法写也不算复杂。字体方面建议只用系统字体栈不要为了一张图引入 web font。图表里字号不宜太小,正文节点至少 14px标签与注释 12px 是底线。同一张图里不要出现三种以上字号否则层级会乱。等宽字体适合用来标记端口号、接口路径、服务名之类的代码型文本但不要大面积使用。间距是我早期最不在意、后来最受益的一项。所有距离都建立在 8px 网格上节点内边距 16px、节点间距 32px、连线和节点之间的最小间隙 24px、容器内边距 24px。用网格约束以后随便谁拖出来的节点位置都自带秩序感不需要设计师手动微调。节点大小也不要随意定至少容纳四到六个字尽量保持宽度一致长短文本另作处理。2.3 连接线的走向比样式更重要连线是图表里信息密度最高的部分也是最容易失控的部分。我在 diagram-design 里对连线做了一条硬性约定默认使用正交折线只有关系极简单时才允许用直线或曲线。为什么默认折线因为在表达架构关系时正交折线更贴近建筑图、电路图的阅读习惯方向感明确层次感强。曲线适合表达流动感比如时序消息、事件流转但用在复杂架构里容易缠成一团。直线只能表达最朴素的相邻关系超过两个节点层次就难以维持。箭头方向也必须统一调用方向总是从调用方指向被调用方数据流方向总是从数据源指向消费方依赖方向从依赖方指向被依赖方。这一点不统一图就废了大半。最容易犯错的是把“数据流”和“调用流”混画在同一条线上建议在连线中带上一个小语义标签比如“HTTP”“DB”“MQ”用简短文字替代颜色区分可靠性高得多。连线的避让又是一个硬约束线不能穿过节点内部不能穿过文字区域交叉尽量少于三个。实现时我基于 A* 寻路做正交避让效果不错。如果读者里有人不想写寻路算法可以先做两步简化一是定好端口连线只从节点右侧或下侧出避免从任意边缘乱接二是布局时让节点之间的坐标差大于最小安全距离从源头上减少穿行。2.4 布局组织从“画得出”到“看得懂”图表不只是“把节点摆开”而是要有明确的阅读主序。我常用的组织策略有四种自上而下的层次布局适合表达调用链顶层是入口逐层向下是依赖的后端服务和数据源。每一层水平对齐同层节点间距一致层与层之间留出足够空隙放连线。自左向右的流程布局适合表达时序或流水线左边起点右边终点分支用菱形节点引出多条路径。分组容器用来表达逻辑边界一个微服务内部的模块、一个系统内部的子域用虚线圆角矩形框起来框内的小节点表示内部模块。容器本身只表达逻辑归属不表达技术隔离。泳道布局则适合跨角色协作流程横向或纵向划分区域代表不同角色节点落在对应角色的泳道里。泳道比较适合处理多参与方的流程画得好能极大降低理解成本。摆放时有个小技巧把频繁连通的节点放得近一些减少连线长度把同层节点纵向对齐产生视觉节奏。如果节点太多手动摆不现实就接入自动布局算法至少提供网格对齐和力导向布局的兜底选项。3. 实操流程从需求到一套可复用图表组件3.1 先把图画在纸上再谈代码很多人上来就写代码或开软件我会先做一步用纸笔把核心关系画一遍。这一步不追求美观只梳理节点数量、连线方向、层次关系。草图阶段能暴露出很多后面难改的问题比如某两个节点之间关系重复、分支过多、职责边界模糊。我当时做模拟项目 X 的模块关系图草图画到第三版才发现有个模块同时属于两个分组分组边界一直绕不清后来靠调整分组定义才解决。草图阶段花二十分钟后面能省两个小时的调整。草图里还要标清楚谁是起点、谁是终点、谁是被依赖方、谁是外部系统。起点和终点决定图的主序被依赖方决定层次的高低外部系统需要特殊视觉标记。这些在草图里定死不犹豫后面所有代码都围绕这份草稿来。3.2 数据模型先行节点与连线是两张表diagram-design 的核心数据结构可以看作两张表节点表和连线表。节点表里每个节点有一个唯一 id再加上类型、标签、坐标、宽度高度、分组归属连线表里每条边有源节点 id、目标节点 id、类型、标签以及可选的路径点。const graph { nodes: [ { id: gateway, type: service, label: API 网关, x: 32, y: 32, w: 160, h: 56 }, { id: user, type: external, label: 用户端, x: 320, y: 320, w: 140, h: 56 }, { id: order, type: service, label: 订单服务, x: 320, y: 32, w: 160, h: 56 } ], edges: [ { id: e1, source: user, target: gateway, type: call, label: HTTPS }, { id: e2, source: gateway, target: order, type: call, label: RPC } ] };这里最容易被省略的是坐标和尺寸但建议一开始就存进数据里。后面做拖拽保存、多人协作、布局调整时有坐标数据才能落盘和还原。node 和 edge 分离还能带来另一个便利任意节点发生变化只需要重绘受影响的部分不用全部刷新。3.3 用 SVG 实现图表画布核心拿到数据之后渲染层只需要做一件事把节点和连线映射成 SVG。节点可以直接用g包裹rect和text连线的正交折线需要一点点路径计算。这里给出节点渲染的基础结构svg width800 height600 xmlnshttp://www.w3.org/2000/svg g transformtranslate(32, 32) rect width160 height56 rx6 classnode-service / text x80 y34 text-anchormiddle classnode-label订单服务/text /g /svg连线的正交折线路径我一般实现一个简单的函数给定起点和终点坐标加上端口方向返回折线路径。起点在右、终点在左时路径通常是“先水平向右、再垂直、再水平向左”的三段结构function orthogonalPath(x1, y1, x2, y2) { const midX (x1 x2) / 2; return M ${x1} ${y1} L ${midX} ${y1} L ${midX} ${y2} L ${x2} ${y2}; }拐角要不要圆角化看整体视觉效果。如果节点很多、线很密建议不加圆角锐利的直角更接近电路图风格如果追求柔和可以在每个拐点用二次贝塞尔曲线替代。但要注意圆角会让寻路复杂度上升建议默认保持直角。画布本身建议用一个最外层svg加内层g做平移缩放。平移缩放通过修改g的 transform 实现比改每个节点的坐标高效得多。3.4 把交互补上拖拽、选中、缩放图表设计器没有交互就不是“设计器”至少得有拖拽节点、选中高亮、画布缩放三个基础能力。拖拽的核心思路是在鼠标按下时记录偏移量移动时更新节点坐标并重新渲染let dragState null; svg.addEventListener(pointerdown, (e) { const node e.target.closest(.node); if (!node) return; dragState { id: node.dataset.id, dx: e.clientX - nodeData.x, dy: e.clientY - nodeData.y }; }); svg.addEventListener(pointermove, (e) { if (!dragState) return; const node findNode(dragState.id); node.x e.clientX - dragState.dx; node.y e.clientY - dragState.dy; render(); });注意坐标必须换算到画布坐标系不是直接使用视口坐标。如果画布做过 transform要用 getScreenCTM().inverse() 换算否则拖拽轨迹会跟鼠标脱节。这是我当时改了三遍才彻底理清的点。选中高亮建议用事件委托实现不要把 listener 绑到每个节点上。选中节点后加一个描边类比如.node-selected { stroke: #3b82f6; stroke-width: 2; }简洁又不影响其他节点。缩放建议用滚轮加 Ctrl 键控制最小值 0.2 倍、最大 3 倍。缩放时围绕鼠标所在点缩放这个计算稍微绕一些先算鼠标点在画布坐标中的位置再根据新旧 scale 调整平移量。公式并不复杂网上也有很多现成片段但一定要亲手推导一遍否则边界情况会现出原形。3.5 导出与嵌入文档图表做完总要给人看。我提供两条导出路径SVG 内联嵌入和 PNG 导出。SVG 内联直接用序列化后的 SVG 字符串放进 HTML优点是可缩放、可选中、可搜索PNG 则用 canvas 绘制 SVG 再转图片输出注意导出画布区域要设为白色背景避免透明底在某些文档背景上显示异常。嵌入文档的话我习惯把 SVG 和图表数据同时保存。数据保留可编辑性SVG 保留展示效果。下次要改图直接加载数据重新渲染而不是拿图片硬啃。4. 常见问题与排查技巧实录4.1 连线乱飞问题往往不是出在线本身一发现连线乱绝大多数人第一反应是优化路径算法但我在实践中发现乱象的根源通常是节点布局失控。节点叠在一起、层次不清再好的避让算法也救不回来。排查时先做三件事第一检查节点是否都吸附到了网格上。网格吸附能避免大量“差一点点对齐”的脏位置这一步能消除不少无意义拐弯。第二检查同层节点是否纵向或横向对齐。两个节点只要 y 坐标差 2px连线就会多一个折角。第三检查连线端口是否规范。随机从任意边缘出线是连线乱的大头统一“从右侧出、从左侧入”后哪怕节点多一倍图面也能保持整洁。如果这三步做完连线还乱再考虑优化避让算法。我有个经验数据80% 的连线问题靠改善布局就能解决只有 20% 才真正需要优化算法。4.2 图越画越大画布怎么扛得住节点超过两三百个SVG 的 DOM 节点数会明显影响交互流畅度。我的处理思路按优先级排加视口裁剪只渲染可视区域内的节点视口外的不挂到 DOM 上。对隐藏分组做折叠折叠后组内节点不渲染只保留一组占位节点。连线路径尽量合并公共线段减少重复节点。如果数据量长期保持千级建议考虑把连线单独放一层 Canvas节点留 SVG各有分工。但对于绝大多数团队场景先把前三条做好就够了。过度优化反而是负担毕竟图的使命是沟通不是大数据可视化。4.3 团队协作时规范怎么防止“堕落”规范执行难不是人懒而是缺少反馈机制。我在项目里加了两道自动检查一是渲染时自动校验节点数据发现连线起点终点相同、节点坐标重叠、连线交叉数过多就给出警告二是 git 提交前跑一次 lint检查连线方向是否与节点类型匹配比如外部节点只能作为起点、存储节点只能作为终点。自动校验能把规则变成默认行为而不是靠人自觉。另外文档里要附一张“速查卡”把节点类型、颜色、连线样式浓缩成一张表。新人看一眼就能上手不需要从头读完整规范。4.4 可访问性图表不能只服务视力正常的人图表本质是视觉表达但对色弱、低视力用户很不友好。我的最低标准是做到“信息不只靠颜色传递”每个颜色符号都搭配形状或文字标签连线不只靠线型区分还要有方向箭头或文字标签文本与背景对比度达标。更进一步可以考虑给 SVG 加上 roleimg 和 aria-label 描述图表内容至少让读屏软件能读出图表主题。你精心画了一张架构图结果团队成员里有人是色弱看着一片灰绿分不出节点归属这就很遗憾。花三十分钟把颜色方案调成“色盲安全色板”后面的沟通成本能降一大截。最后分享几个我实际培养出来的习惯图表设计的回报周期特别长短期看不出差别但坚持一年以后再看团队产出的文档质量差异非常明显。我个人最大的感受是看一张新图如果三秒内找不到起始节点五秒内找不到主链路这张图就算是白画了。所以我现在画图之前先自问一句“假如我对这个系统一无所知能看明白吗”答不上来绝不碰代码。另外一个很实用的习惯图表数据永远和图表一起保存。代码会变、服务会迁移但关系图沉淀的是结构逻辑。没有数据只有图片的图表半年前画的图拿到今天基本只能重画有数据时拖动几个节点就能复用。diagram-design 做到后期基本上就是两种文件一份 JSON 数据、一份渲染视图前者是可编辑的真身后者只是它的一张快照。这个方向还能继续扩展的方向还很多比如自动布局算法更智能、多人实时编辑、图数据与监控指标联动。但无论加什么新能力底线始终没变任何图表都要让一个零背景的人在第一眼就看懂它想说什么。守住这条底线比堆任何花哨功能都重要。
阅读完成 · 觉得有帮助？
