meta2d.js 工具函数库 @meta2d/utils 实战指南:直线/折线相交自动绕行(弯曲避让)原理与接入

原创2026-10-14 18:29:161,649 阅读
文章标签:前端数据可视化

meta2d.js 工具函数库 @meta2d/utils 实战指南:直线/折线相交自动绕行(弯曲避让)原理与接入

导读

@meta2d/utils 是 meta2d.js 2D 组态引擎官方提供的工具函数包,当前仓库中它聚焦于一个非常实用的交互能力:连线相交自动避让。在 Web SCADA、物联网拓扑、数字孪生等场景中,节点之间往往存在大量连线,多条直线或折线交叉时,人眼很难判断"哪条线是通的、哪条线只是路过"。本指南以 packages/utils/README.md 为线索,结合 lineCross.ts 与 newLineCross.ts 两份源码,完整讲解相交线自动弯曲的实现原理、两代 API 的差异、接入步骤与可调参数,读完你可以在自己的 meta2d 应用中启用"相交自动绕行"并理解其底层几何算法。

一、utils 包是什么:定位与包结构

按 packages/utils/README.CN.md 的说明,"utils 是基于 le5le meta2d 而开发的工具函数库"。包名注册为 @meta2d/utils,版本 1.0.3,依赖 @meta2d/core(见 package.json)。

包的对外入口是 packages/utils/index.ts,它只做一件事:统一导出两个源码模块:

export * from './src/lineCross';
export * from './src/newLineCross';

也就是说,这个包目前的全部能力都围绕"相交线弯曲(line cross)"这一主题展开。构建脚本为 tsc && npm run copy(见 package.build.json),发布产物会拷贝到 dist/utils/ 目录下。

二、解决什么问题:连线相交的视觉歧义

在画布上绘制多条连线时,如果两条线交叉,常规画法下二者在交叉点会互相"压住"对方,观感上像是发生了电气连接。utils 包要解决的是:当 2 条或多条线交叉时,让其中一条(最上层的那条)在交叉点处弯曲绕行,表明这些线之间并不存在连接关系。

对应源码 lineCross.ts 头部注释:

直线连线交叉问题,在画布上,当2条或多条线交叉时,其中一条线会弯曲显示,表明这2条或多条线之间,不存在交叉。

注意这里的适用范围:只处理直线(line)和折线(polyline),不处理曲线,源码中以 crossLines = <a href="https://link.gitcode.com/i/4a031d059972657885a5448e10808066" target="_blank">'line', 'polyline'] 常量限定(见 [lineCross.ts)。

三、核心机制:为什么"弯曲"能成立

弯曲效果的实现依赖 meta2d 连线的贝塞尔渲染能力。在核心包 packages/core/src/diagrams/line/line.ts 的 draw 函数中,两点之间是否画成贝塞尔曲线,取决于相邻锚点是否带有 next / prev 控制点:

  • 若 from.next 与 to.prev 同时存在 → 绘制三阶贝塞尔 bezierCurveTo;
  • 若只有其一 → 绘制二阶贝塞尔 quadraticCurveTo;
  • 若都没有 → 退化为普通直线 lineTo。

因此,utils 的做法是:检测到相交后,在相交点两侧插入一对特殊锚点,并给它们挂上 next / prev 控制点,使该段在渲染时呈现"绕开"的圆弧。这对锚点的数据结构定义在 packages/core/src/point/point.ts 中:Point 接口包含 prev?: Point、next?: Point、prevNextType?: PrevNextType,其中 PrevNextType 枚举为 Mirror / Bilateral / Free(见 point.ts)。utils 中插入的弯曲锚点一律使用 PrevNextType.Bilateral(双侧对称弯曲)。

四、第一代实现:lineCross(事件驱动 + 交互态)

lineCross.ts 是 2022 年提交的初版实现,特点是通过监听 meta2d 事件来"在用户交互后重新计算相交"。

4.1 初始化与销毁

import { lineCross, clearLineCross } from '@meta2d/utils';

// 启用,true 表示图纸打开(opened 事件)时自动对所有相交线做一次弯曲
lineCross(true);

// 不再需要时销毁订阅
clearLineCross();

lineCross(defaultCross: any) 内部会订阅 4 个引擎事件(见 lineCross.ts):

  • mousedown:标记一次拖拽动作开始(downToUpFlag = true);
  • mouseup:拖拽结束后执行相交检测与弯曲;
  • add:新增图形后重新计算;
  • active:激活图形后重新计算;
  • opened:图纸打开时,若 defaultCross 为 true,自动执行一次 handleLineCross(undefined)。

clearLineCross() 则通过 off 反注册上述全部事件并清空内部锚点数组(见 lineCross.ts)。

4.2 手工触发:handleLineCross

当不希望走事件驱动(例如在初始化完图纸后、或在某些自定义操作后)需要立即刷新相交弯曲时,可直接调用:

import { handleLineCross } from '@meta2d/utils';

// 传入 e:若传入事件对象则只处理当前活动(active)的图形;不传则处理画布全部图形
handleLineCross(undefined);

实现上 handleLineCross 等价于手动执行一次 mouseDown() 再执行 mouseUp(flag)(见 lineCross.ts),其中 mouseUp 才是真正执行相交检测与弯曲的入口。

4.3 处理流程(mouseUp 内部)

  1. 收集待处理连线:从活动图形及其 connectedLines、以及带 intersectLines 标记的被压线中,过滤出 type === Line 且 lineName 属于 line/polyline 的连线;处理顺序倒序,因为"弯曲的情况与 pen 的顺序有关"(见 lineCross.ts)。
  2. 清理旧效果:调用 clearIntersect 删除上一轮插入的弯曲锚点(有 next 或 prev 的锚点即判定为弯曲锚点),并重置各连线的 intersectLines(见 lineCross.ts)。
  3. 两两检测相交:对每对相邻锚点组成的线段调用 checkLineIntersection,当 onLine1 && onLine2 均为 true 时判定两线段真实相交(见 lineCross.ts)。
  4. 计算弯曲半径与控制点:以相交点为圆心、radius 为半径,通过 inteceptCircleLineSeg 求圆与线段交点,再以垂直相交线斜率求出控制点 p4/p5,生成一对"兄弟锚点" an1/an2(通过 brotherId 互相关联),打上 intersect: true、hidden: true、locked: 2 标记(见 lineCross.ts)。
  5. 去重与排序:对坐标接近(anchorOffsetXY = 0.000001)的锚点成对去重;再按参考锚点距离排序,保证插入顺序正确(见 lineCross.ts)。
  6. 插入锚点并刷新渲染:按 lastAnchorIndex 把弯曲锚点 splice 进 worldAnchors,随后调用 meta2d.canvas.updateLines(ls<a href="https://link.gitcode.com/i/b9de1416d97d355741de391c6d7bbe56" target="_blank">i]) 与 initLineRect(ls[i]) 更新连线的包围盒,最后 meta2d.render()(见 [lineCross.ts)。

4.4 半径的自适应计算

初版中弯曲半径不是固定值,而是根据线宽与画布缩放比动态计算(见 lineCross.ts):

radius = 3;
radius += (lines[j].lineWidth / ls[i].lineWidth) * ls[i].lineWidth; // 依被压线线宽增大
radius *= meta2d.store.data.scale;                                    // 乘以画布缩放

即:相交处圆弧大小随线宽与缩放自适应,缩放越大弯曲越明显,避免小比例下弯曲不可见。

五、第二代实现:newLineCross(批量处理 + 性能优化)

newLineCross.ts 是 2024 年重写的高性能版本,模块头注释明确列出其核心设计目标:

  1. 检测直线和折线的相交点
  2. 为相交点创建弯曲效果(只有最上层的线弯曲)
  3. 合并相近的相交点,创建更大的弯曲包含多个相交点
  4. 高性能实现,支持大量线条

它不依赖交互事件,提供三个导出函数,全部通过 (window as any).meta2d 直接操作引擎:

函数 作用
processLineIntersections() 扫描全部直线/折线,清除旧效果后重新计算并创建弯曲
clearAllIntersections() 通过 intersect === true 标记删除所有弯曲锚点并重新渲染
updateIntersectionBends() 先 clearAllIntersections() 再 processLineIntersections(),即"整图重算"

三个函数入口处都会做 meta2d 未初始化的防御性检查并输出 console.warn(见 newLineCross.ts)。

5.1 相比初版的关键改进

(1)只有最上层的线弯曲。 处理顺序从后往前遍历线条(数组靠后 = 图层靠上),每条当前线只与"索引小于它"(更靠下)的线做相交检测(见 newLineCross.ts 与 newLineCross.ts),天然保证交叉点只有上层线绕行、下层线保持直线。

(2)相交点合并成组。 当一条线与多条线相交且相邻交点距离小于 mergeDistanceThreshold * scale 时,这些交点会被合并为一组,以组中心为圆心、maxRadius + maxSpan/2 + 5 为半径生成一个"包含多个相交点的大弯曲"(见 newLineCross.ts),视觉效果上更接近真实电气图纸的"跨线弧"。

(3)多线交于同一点只处理一次。 通过 processedIntersections(Map<string, {x, y}>)按网格键记录已处理交点,并检查当前网格及相邻 8 个网格(网格大小 intersectionTolerance * scale)来避免重复创建(见 newLineCross.ts),容差常量 intersectionTolerance = 5。

(4)数据结构与查找优化。 全程使用 Set/Map 替代线性查找:crossLinesSet 判断线条类型、anchorMap 定位参考锚点、indexMap 定位插入位置、toRemove 集合批量删除重复锚点(见 newLineCross.ts 与 newLineCross.ts),避免了初版中大量 findIndex 的 O(n²) 开销,这是"支持大量线条"的直接保障。

5.2 常用接入示例

import {
  processLineIntersections,
  clearAllIntersections,
  updateIntersectionBends,
} from '@meta2d/utils';

// 1) 图纸加载完成后整图重算一次
updateIntersectionBends();

// 2) 或拆开使用:先清除再重建
clearAllIntersections();
processLineIntersections();

// 3) 某条线增删/拖拽后局部刷新(仍走整图重算,由引擎批量处理)
meta2d.on('updateLines', () => processLineIntersections());

六、可调参数速查表

两代实现中的核心常量与取值如下,可结合实际图纸密度调整:

常量 初版 lineCross 新版 newLineCross 含义
相交圆基础半径 radius = 3(随线宽/缩放累加) 3 + (otherLineWidth / currentLineWidth) * currentLineWidth,再乘 scale 弯曲圆弧半径
dotHitOffset 2 2 判断点是否在"粗线段"内的偏移阈值
anchorOffsetXY 0.000001 0.000001 坐标相近锚点去重阈值
intersectionTolerance — 5 判定多个交点是否同一点的容差(乘 scale)
mergeDistanceThreshold — 20 相交点合并为大弯曲的距离阈值(乘 scale),值越大越易合并
处理范围 ['line', 'polyline'] ['line', 'polyline'] 只处理直线与折线,曲线不受影响

新版的 mergeDistanceThreshold 是实际调参中最常用的旋钮:拓扑连线密集时调大,让多个交叉点归并为一条大弧;需要精细展示每个交叉点绕行时调小。源码注释同样提示"可以根据实际需要调整此值"(见 newLineCross.ts)。

七、与核心引擎的衔接点

utils 之所以能"只插锚点就实现弯曲",是因为核心渲染链路天然支持。建议结合以下源码理解:

  • 贝塞尔绘制分支:packages/core/src/diagrams/line/line.ts 的 draw() 依据 from.next / to.prev 选择 bezierCurveTo / quadraticCurveTo / lineTo;
  • 锚点数据结构:packages/core/src/point/point.ts 定义 Point 的 prev / next / prevNextType 字段及 PrevNextType 枚举;曲线编辑逻辑 curve.ts 中也使用 PrevNextType.Bilateral,说明该枚举是核心包为弯曲类锚点预留的通用机制;
  • 包围盒刷新:utils 插入锚点后调用 meta2d.canvas.updateLines() 与 meta2d.canvas.initLineRect(),其中 initLineRect 位于 packages/core/src/canvas/canvas.ts#L4548,负责根据新的 worldAnchors 重算连线矩形与路径(path2dMap),保证弯曲后的连线可正确命中、框选与导出。

从源码结构看,两代实现都以"修改 pen.calculative.worldAnchors + 重建渲染路径"为统一手段,区别只在相交检测的组织方式(事件驱动 vs 批量扫描)与性能优化策略上。

八、版本演进小结与选型建议

  • lineCross(事件驱动版):适合需要"拖拽/新增/激活时自动刷新"的交互场景,订阅引擎事件即可无缝工作;但其内部大量 findIndex 遍历,连线数量很大时开销偏高。
  • newLineCross(批量版):适合初始化完成后一次性整图重算、或连线数量多的复杂拓扑;API 语义更清晰(process / clear / update 三段式),并支持相交点合并与"仅最上层弯曲",表现更接近工程图纸规范。
  • 两版可以并存(入口 packages/utils/index.ts 同时导出二者),实际项目中可按需选择:追求交互实时性用前者,追求大规模静态图性能与视觉效果用后者;需要"打开图纸即自动弯曲"时,对应初版的 lineCross(true) 或在新版中自行在 opened 事件里调用 updateIntersectionBends()。

九、许可证与贡献

utils 包遵循 MIT 协议(© le5le.com,见 packages/utils/README.md),其 README 同时欢迎通过提交 Issue 或 Pull Request 的方式参与贡献。该包作为独立 workspace 包维护,发布名 @meta2d/utils、入口为 index.ts,构建产物输出到 dist/utils/。

登录后查看全文
meta2d.js