meta2d.js 工具函数库 @meta2d/utils 实战指南:直线/折线相交自动绕行(弯曲避让)原理与接入
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 内部)
- 收集待处理连线:从活动图形及其
connectedLines、以及带intersectLines标记的被压线中,过滤出type === Line且lineName属于line/polyline的连线;处理顺序倒序,因为"弯曲的情况与 pen 的顺序有关"(见 lineCross.ts)。 - 清理旧效果:调用
clearIntersect删除上一轮插入的弯曲锚点(有next或prev的锚点即判定为弯曲锚点),并重置各连线的intersectLines(见 lineCross.ts)。 - 两两检测相交:对每对相邻锚点组成的线段调用
checkLineIntersection,当onLine1 && onLine2均为 true 时判定两线段真实相交(见 lineCross.ts)。 - 计算弯曲半径与控制点:以相交点为圆心、
radius为半径,通过inteceptCircleLineSeg求圆与线段交点,再以垂直相交线斜率求出控制点p4/p5,生成一对"兄弟锚点"an1/an2(通过brotherId互相关联),打上intersect: true、hidden: true、locked: 2标记(见 lineCross.ts)。 - 去重与排序:对坐标接近(
anchorOffsetXY = 0.000001)的锚点成对去重;再按参考锚点距离排序,保证插入顺序正确(见 lineCross.ts)。 - 插入锚点并刷新渲染:按
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 年重写的高性能版本,模块头注释明确列出其核心设计目标:
- 检测直线和折线的相交点
- 为相交点创建弯曲效果(只有最上层的线弯曲)
- 合并相近的相交点,创建更大的弯曲包含多个相交点
- 高性能实现,支持大量线条
它不依赖交互事件,提供三个导出函数,全部通过 (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/。