JointJS DWDM 网络拓扑 Demo 解析:用 SVG 图编辑器搭建密集波分复用监控系统

原创2026-10-05 20:25:371,861 阅读
文章标签:前端图表库UI组件图形学

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,主要分四步:

  1. 创建 Node 容器:为每个网元 new Node({ position, name, ip, image, z: 1 }),随后调用 nodeModel.setName(name) / nodeModel.setIp(ip)(见 Node.ts)为头部标签写入文本并加富文本 annotation 高亮值部分;
  2. 创建板卡并嵌入容器:遍历 cards,以 ctor.createPort(id, group) 生成端口,cardModel.addTo(graph) 后调用 nodeModel.embed(cardModel) 将板卡作为 Node 的子元素嵌入(这是后续"折叠容器"能力的基础);
  3. 建立板卡间链路:通过 linksMap 以 源板卡:源端口:目标板卡:目标端口 的哈希去重,若检测到一条反向链路已存在且当前为单向 NodeLink,则调用 link.toBidirectional() 将其升级为双向箭头,否则新建链路;
  4. 归位外部链路: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"),扩展为真实系统时可关注以下几点:

  1. 数据源替换:load(graph, data) 的输入即 IData,可改为由后端 REST/WebSocket 推送,仅需保持 nodes/links 字段结构;
  2. 告警源替换:将 Monitor 的随机事件换成 SNMP/NETCONF 北向告警流,subscribe 回调签名不变,前端无需改动;
  3. 板卡扩展:新板卡只需继承 Card、覆写 defaults() 中的 type/size/attrs 并注册进 cellNamespace.ngv;
  4. 交互开放:当前 paper 设置为 interactive: false(只读展示),如需编辑可放开并按 magnet: 'passive' 等端口约束调整;
  5. 主题定制:所有颜色、尺寸集中在 theme.ts,替换即可完成换肤。

十、许可证

JointJS 库本身采用 Mozilla Public License 2.0(仓库根目录同时提供 SECURITY.md 安全说明),Copyright © 2013-2026 client IO;本 Demo 作为示例代码随仓库一并分发。

登录后查看全文
joint