JointJS DWDM 网络拓扑 Demo 解析:用 SVG 图编辑器搭建密集波分复用监控系统
JointJS DWDM 网络拓扑 Demo 解析:用 SVG 图编辑器搭建密集波分复用监控系统
导读
本篇文章基于开源仓库 joint(JointJS)中的 examples/dwdm 示例,深入解析一个基于 SVG 的密集波分复用(Dense Wavelength-Division Multiplexing,DWDM)网络拓扑监控界面是如何用 JointJS 搭建出来的。该 Demo 以"数据驱动的配置 + 自定义形状 + 折叠容器 + 实时告警"为主线,展示了如何在一个可伸缩的容器节点内组织复用器(MUX)、解复用器(DMUX)、ROADM、放大器、光纤保护单元与光功率监测板卡,并通过端口级连线描述波长通道。读完本文,你将掌握该 Demo 的完整运行方式、数据模型结构、自绘形状与端口系统的实现思路,以及将其改造为真实 DWDM 网管界面的可行路径。
说明:仓库为只读镜像,本文只介绍查看、安装、运行与配置方式,不涉及对仓库的修改。
一、Demo 是什么
DWDM 是光通信网络中提升单根光纤传输容量的核心技术:将多个不同波长的光信号复用进同一根光纤传输,在接收端再解复用还原。因此一张 DWDM 网络拓扑图通常包含两类核心元素:
- 网元节点(Node):代表一台物理设备,内部嵌有多块功能板卡(Card);
- 板卡(Card):代表设备内的功能模块,如 Multiplexer(复用器)、Demultiplexer(解复用器)、ROADM(可重构光分插复用器)、放大器(Amplifier)、光纤保护单元(FPU)与光功率监测单元(OPM),板卡上的端口用于承载波长级连纤。
JointJS 的 examples/dwdm 正是把上述领域模型映射到图编辑器中,形成"容器节点(Node)→ 内嵌板卡(Card)→ 端口(Port)→ 链路(Link)"的四级可视化结构,并附带折叠节点与端口/链路告警等交互能力。
二、运行环境与准备工作
2.1 技术栈与目录结构
该 Demo 基于 TypeScript 编写,入口为 examples/dwdm/src/index.ts,构建工具使用 Webpack 5,并依赖同一 monorepo 下的 @joint/core(工作区版本):
src/index.ts:入口,负责创建dia.Graph/dia.Paper、加载数据、绑定折叠交互与滚动逻辑、启动告警监控;src/shapes/:自定义形状库,分为cards/(板卡)、links/(链路)、nodes/(容器节点),外加端口锚点anchors.ts、高亮器highlighters.ts与工具函数utils.ts;src/data.ts与src/examples/example1.ts:数据模型接口与一份包含 3 个网元、22 个板卡实例的示例数据;src/layout.ts:拓扑横向自动布局算法;src/Monitor.ts:模拟告警监视器;src/theme.ts:集中管理颜色、尺寸等设计变量。
2.2 安装与启动(严格按 README 流程)
README 明确指出该 Demo 使用 Yarn 运行,且必须先构建整个 JointJS 仓库(因为 demo 依赖工作区内的 @joint/core 源码)。步骤分两步:
第一步:在仓库根目录安装依赖并构建 JointJS
yarn install
yarn run build
根目录的 package.json 以 Yarn workspaces 组织仓库(./packages/* 与 ./examples/*),yarn run build 会通过 yarn workspaces foreach --all -tvv run build 对所有工作区包执行构建,其中就包括 packages/joint-core。
第二步:进入 Demo 目录启动开发服务器
cd examples/dwdm
yarn start
yarn start 实际执行的是 webpack-dev-server(见 examples/dwdm/package.json),编译完成后浏览器访问由 webpack-dev-server 提供的页面(默认 8080 端口)即可看到拓扑图。
关于版本前提:package.json 的 volta 字段声明了 Node.js 22.14.0、npm 11.2.0 与 Yarn 4.18.0,Demo 自身的 volta 亦一致(Node 22.14.0 / Yarn 4.18.0);packageManager 固定为 yarn@4.18.0。若本机环境与上述版本差距过大,建议先通过 Volta 或同等工具对齐版本再执行安装。
三、数据驱动:把拓扑描述翻译成图模型
3.1 数据模型接口
examples/dwdm/src/data.ts 定义了整张拓扑图的"声明式描述":
INode:一个网元节点,包含坐标x/y、名称name、IP 地址ip、占位图片image以及内部的板卡数组cards;ICard:一块板卡,包含构造函数ctor(决定渲染成哪种形状)、坐标、端口数组ports与以"源端口 ID → 目标链接数组"组织的links;ILink:一条链路声明,含ctor、目标板卡id与目标端口port;IExternalLink:扩展了描述文案description的外部链路(用于标注波长,如1470nm);- 顶层
IData = { nodes: INode[]; links: IExternalLink[] }。
3.2 加载过程:load() 的调用链
入口 examples/dwdm/src/index.ts 中调用 load(graph, data) 把 JSON 形态的数据灌入 dia.Graph,其实现位于 examples/dwdm/src/data.ts,主要分四步:
- 创建 Node 容器:为每个网元
new Node({ position, name, ip, image, z: 1 }),随后调用nodeModel.setName(name)/nodeModel.setIp(ip)(见 Node.ts)为头部标签写入文本并加富文本 annotation 高亮值部分; - 创建板卡并嵌入容器:遍历
cards,以ctor.createPort(id, group)生成端口,cardModel.addTo(graph)后调用nodeModel.embed(cardModel)将板卡作为 Node 的子元素嵌入(这是后续"折叠容器"能力的基础); - 建立板卡间链路:通过
linksMap以源板卡:源端口:目标板卡:目标端口的哈希去重,若检测到一条反向链路已存在且当前为单向NodeLink,则调用link.toBidirectional()将其升级为双向箭头,否则新建链路; - 归位外部链路:
graph.addCells(linkModels)后对所有内部链路执行linkModel.reparent()(按嵌入层级自动归属容器),data.links中的ExternalLink则直接添加并设置波长描述。
示例数据 examples/dwdm/src/examples/example1.ts 给出了完整写照:Node-1 内嵌 MUX-1、ROADM-2、FPU-3、AMP-4/5/8/9,Node-2 内嵌 AMP-6/7/10/11、FPU-12、ROADM-13/14、AMP-15/16,Node-3 内嵌 AMP-17/18、OPM-21/22、ROADM-19、DMUX-20;links 段则声明了 MUX-1 左侧 4 个端口与 DMUX-20 右侧 4 个端口分别对应的 1470nm/1490nm/1510nm/1530nm 波长外部链路。
四、自定义形状:从 Node 容器到六类板卡
4.1 容器节点 Node
examples/dwdm/src/shapes/nodes/Node.ts 继承 dia.Element,通过 preinitialize 用 util.svg 模板声明 markup:
body:主区域矩形,y: HEADER_HEIGHT,宽高用calc(w)/calc(h - HEADER_HEIGHT)动态跟随元素尺寸;header:40px 高的头部矩形(HEADER_HEIGHT = 40);labelNodeName/labelNodeIp:头部的名称与 IP 文本,x分别取BORDER_OFFSET与calc(0.3 * w + 50),并用textWrap.ellipsis做单行省略。
关键交互属性是 collapsed(默认 false),配套方法 isCollapsed() / toggleCollapse() 负责状态读写,Node.isNode(cell) 通过 type === 'ngv.Node' 做类型守卫。
4.2 板卡基类 Card 与端口系统
examples/dwdm/src/shapes/cards/Card.ts 是所有板卡的抽象基类,贡献了两项通用能力:
- 四方向端口组:默认
ports.groups定义left/right/top/bottom四组,位置分别交给 JointJS 内置的left/right/top/bottom布局函数; Card.createPort(id, group):静态工厂方法生成端口对象,关键细节包括:magnetSelector: 'portBody'——只允许连线吸附到圆形端口本体,而不是标签文本;magnet: 'passive'——端口只接受连接、不允许作为拖拽起点;- 端口 label 按
left/top或right/bottom分组自动偏向对侧布局。
CardView 还覆写了 getMagnetFromLinkEnd:当板卡被隐藏(所属 Node 折叠)时,把连线的磁铁锚点重定向到父节点视图,这是"折叠后连线自动收拢到容器"的实现关键。
4.3 六种板卡形状速览
所有板卡均继承 Card,在 defaults() 里定义 type、默认尺寸与 attrs,用 util.svg 模板声明自身 markup,可对照源码查阅:
| 板卡类 | type | 尺寸 (w×h) | 外形 | 源码 |
|---|---|---|---|---|
| Multiplexer | ngv.Multiplexer |
75×200 | 左窄右宽的梯形(向右收束的合波器) | Multiplexer.ts |
| Demultiplexer | ngv.Multiplexer |
75×200 | 与 MUX 镜像的梯形(向左展开的分波器) | Demultiplexer.ts |
| ROADMultiplexer | ngv.ROADMultiplexer |
75×200 | 矩形(可重构光分插复用器) | ROADMultiplexer.ts |
| OpticalPowerMonitoring | ngv.OpticalPowerMonitoring |
60×60 | 圆角方形(光功率监测) | OpticalPowerMonitoring.ts |
| FiberProtectionUnit | ngv.FiberProtectionUnit |
80×80 | 圆形(光纤保护单元) | FiberProtectionUnit.ts |
| LeftAmplifier | ngv.LeftAmplifier |
40×40 | 指向右的三角形(左侧放大器) | LeftAmplifier.ts |
| RightAmplifier | ngv.RightAmplifier |
40×40 | 指向左的三角形(右侧放大器) | RightAmplifier.ts |
值得注意的复用技巧:板卡整体共用 CARD_BG_COLOR 的对角斜纹 pattern 填充(定义于 theme.ts,12×12 重复单元 + 对角 path),视觉上自然区分于普通矩形元素;同时所有板卡的填充/描边/标签色都收敛在 theme.ts 的 CARD_COLOR / CARD_BG_COLOR / CARD_LABEL_COLOR 等常量中,改主题只需改一处。
4.4 自定义形状注册:cellNamespace
examples/dwdm/src/shapes/index.ts 把全部形状与视图导出为 cellNamespace,结构为 { ...shapes, ngv: { Node, Multiplexer, MultiplexerView: CardView, ... } }。入口创建图与画布时显式传入:
new dia.Graph({}, { cellNamespace })paper的cellViewNamespace: cellNamespace
这样 @joint/core 才能按 type 字符串(如 ngv.ROADMultiplexer)反查并实例化对应的元素/视图类。
五、链路体系:NodeLink、FiberLink 与 ExternalLink
链路抽象基类 Link.ts 定义抽象方法 isBidirectional() 与静态守卫 Link.isLink()。三个具体子类共享同一套 markup 思路——一条 wrapper 宽透明描边路径(strokeWidth: 10,用于扩大鼠标命中区、cursor: pointer)叠加一条 line 可见路径(pointer-events: none):
| 链路类 | type | 外观特征 | 双向性 | 源码 |
|---|---|---|---|---|
| NodeLink | ngv.NodeLink |
实线 + 目标端箭头 | 默认单向,可 toBidirectional() 升级为双箭头 |
NodeLink.ts |
| FiberLink | ngv.FiberLink |
实线 + 双椭圆标签(示意光纤截面)+ 目标端箭头 | 恒为单向 | FiberLink.ts |
| ExternalLink | ngv.ExternalLink |
虚线 + 双端箭头(默认 bidirectional: true),中央挂波长文本标签 |
恒为双向 | ExternalLink.ts |
ExternalLink.setDescription() 在链路 50% 距离处添加一个带 description 选择器的文本标签并设置 offset: 10,示例数据中即用它显示 1470nm 等波长。箭头 marker 由内联 SVG 路径 M 8 -3 -1 0 8 3 z 提供(NodeLink.ts)。
5.1 端口多链路锚点偏移
examples/dwdm/src/shapes/anchors.ts 实现了自定义锚点函数 multiLinkAnchor,逻辑如下:
- 若端点对应的元素处于隐藏态(容器已折叠),把锚点拉回父容器包围盒中心/左侧,保证连线始终指向折叠节点;
- 否则取该端口上的连接数,超过 2 条时按端口所在组(
top/bottom/left/right)做 ±3px 的垂直/水平偏移,避免同端口多链路视觉重叠。
入口 paper 通过 defaultAnchor: multiLinkAnchor 全局启用(index.ts)。
六、折叠容器:收拢子板卡并重连所有链路
折叠交互是 DWDM 拓扑常用的"概览/细节"切换手段,本 Demo 的实现可分为三层:
1. 状态与触发:Node.toggleCollapse() 翻转 collapsed 属性;入口监听自定义事件 node:collapse(由高亮器 ExpandButton 发出),折叠时遍历 node.getEmbeddedCells() 调用 setCellVisibility(child, !collapsed) 设置每个子单元的 hidden 属性(utils.ts),随后重跑布局。
2. 视觉呈现:highlighters.ts 中的 NodePlaceholder 在折叠时把节点包围盒渲染为网元占位图(href 取自数据中的 image,对应 assets/node1.svg 等)并叠加节点名;ExpandButton 则固定在头部右侧,根据 collapsed 状态在"−"与"+"之间切换 icon 路径,并带 event: 'node:collapse' 事件属性以触发折叠。
3. 连线重连:CardView.getMagnetFromLinkEnd()(Card.ts)在 hidden 时把连线磁铁替换为父 Node 视图;入口还自定义了 defaultRouter(index.ts)——当源或目标被隐藏时直接返回空顶点数组(画直线),否则使用 routers.rightAngle 以 margin: 10 走直角折线。二者配合使折叠后所有内部连线自动"收拢"到容器节点上。
七、布局与画布自适应
examples/dwdm/src/layout.ts 提供 layout(graph) 纯函数,返回总宽度:
- 将节点在画布上横向排布,间距为
NODE_MARGIN_HORIZONTAL(60px),起点同样留 60px; - 展开时用
node.fitToChildren({ expandOnly: true, padding: {...} })让容器包裹全部板卡,再固定高度为NODE_HEIGHT(420) + HEADER_HEIGHT(40);折叠时直接缩到NODE_COLLAPSED_WIDTH(100); layoutExternalLink把外部链路的源点水平推到容器外侧NODE_MARGIN_HORIZONTAL/5*4处、并保持与目标端口垂直对齐(仅处理左右端口组)。
入口的 resizePaper()(index.ts)随后依据布局总宽计算画布尺寸,并用 paper.transformToFitContent({ verticalAlign: 'middle', ... }) 把内容垂直居中;水平方向则交给页面自身的横向滚动(body { overflow-x: scroll },见 style.css)。
八、告警监视:模拟 DWDM 网管告警联动
8.1 Monitor 的订阅机制
examples/dwdm/src/Monitor.ts 用一个简单的发布/订阅模拟告警源:subscribe(callback) 每 500ms 触发一次,按 maxAlerts(5) 随机产生"新告警"或"告警恢复"事件,回调收到 { cell, port, resolved };返回的闭包用于取消订阅(clearInterval)。其组件清单由 getGraphComponents() 动态生成——每个 Card 的每个端口、以及除 ExternalLink 外的每条链路,都会成为潜在的告警载体。
8.2 告警高亮:端口、链路与容器三级联动
入口将 Monitor 事件桥接到 toggleCellAlert(cellView, { port }, !resolved)(highlighters.ts),实现三级高亮:
- 链路告警:
LinkAlert(继承内置highlighters.stroke)沿链路画红色粗虚线(stroke-dasharray: 1, 30); - 端口告警:
PortAlert以红色粗描边圈住portBody,并把相邻的端口 label 文本同步染红; - 容器告警:父 Node 上挂
NodeAlert(assets/alert.svg图标),当子级告警全部恢复时才移除,并在 style.css 的blink关键帧动画下闪烁提示。
九、从 Demo 到真实 DWDM 网管:可落地的扩展方向
该 Demo 作为"模板"(index.html 的 meta 描述即为 "serves as a template to help bring your idea to life in no time"),扩展为真实系统时可关注以下几点:
- 数据源替换:
load(graph, data)的输入即IData,可改为由后端 REST/WebSocket 推送,仅需保持nodes/links字段结构; - 告警源替换:将
Monitor的随机事件换成 SNMP/NETCONF 北向告警流,subscribe回调签名不变,前端无需改动; - 板卡扩展:新板卡只需继承
Card、覆写defaults()中的type/size/attrs并注册进cellNamespace.ngv; - 交互开放:当前
paper设置为interactive: false(只读展示),如需编辑可放开并按magnet: 'passive'等端口约束调整; - 主题定制:所有颜色、尺寸集中在 theme.ts,替换即可完成换肤。
十、许可证
JointJS 库本身采用 Mozilla Public License 2.0(仓库根目录同时提供 SECURITY.md 安全说明),Copyright © 2013-2026 client IO;本 Demo 作为示例代码随仓库一并分发。