流程图连接线:端点吸附 + 智能路由 + 箭头绘制——让连线跟着节点跑
本文基于矢量图形编辑器项目,拆解流程图连接线系统的完整实现:ConnectionEndpoint 端点模型、PathRouter 正交路由、FlowShape 连接桩、箭头绘制、连线命中测试。全文约 400 行,配 3 张架构图。
引言
流程图编辑器的核心体验是"拖个节点,连线自动跟上"。
听起来理所当然——但背后涉及三个问题:连线的两端到底连在哪(端点模型)、中间的路径怎么走(路由算法)、节点移动后连线怎么更新(动态跟随)。
本文拆解的就是这套系统。ConnectionEndpoint 定义"连在哪"——可以是节点的连接桩,也可以是一个自由点。PathRouter 计算"怎么走"——正交路由产生阶梯状路径。ConnectionShape 负责"画出来"——三种样式(直线/正交/平滑)+ 箭头 + 标签。
全部逻辑加起来不到 500 行 TypeScript,却能支撑一个完整的流程图编辑器。

一、ConnectionEndpoint:端点的两种身份
连线的每一端可以是两种东西:
- 连接桩(softLink):绑定到某个 FlowShape 的某个桩位,节点移动时连线自动跟随
- 自由点(freePoint):固定在世界坐标的某个位置,不随任何节点移动
class ConnectionEndpoint {
shapeId: string = ''; // 绑定的图形 ID(空 = 自由点)
portIndex: number = -1; // 绑定的桩位索引
freePoint: Point | null = null; // 自由点坐标
static toShape(shapeId: string, portIndex: number): ConnectionEndpoint { ... }
static toFree(p: Point): ConnectionEndpoint { ... }
}
大多数流程图连线两端都是 softLink——用户从 A 节点拖到 B 节点,连线自动绑定 A 的某个桩和 B 的某个桩。自由点主要用于"连线到空白处"的场景。
绑定关系通过 shapeId 查找——渲染时遍历 Document 找到对应 Shape,再取其世界坐标。如果节点被删除,shapeId 找不到对应 Shape,连线会退化为使用 freePoint。
二、FlowShape 连接桩:4 个吸附点
每个 FlowShape 有 4 个连接桩——上、右、下、左,位于边的中点:
getLocalConnectionPorts(): Point[] {
return [
new Point(this.width / 2, 0), // 上
new Point(this.width, this.height / 2), // 右
new Point(this.width / 2, this.height), // 下
new Point(0, this.height / 2), // 左
];
}
世界坐标版本通过 transform 转换:
getWorldConnectionPorts(): Point[] {
return this.getLocalConnectionPorts().map(p => this.transform.applyPoint(p));
}
4 个桩位覆盖了流程图最常见的连线方向。用户不需要精确点击桩位——引擎会自动找最近的桩。
三、端点吸附:最近桩位匹配
连线工具的交互分两步:按下(选择起点桩)和松开(选择终点桩)。
两步用的是同一套逻辑——找最近的桩:
const ports = flowShape.getWorldConnectionPorts();
let bestIdx = 0, bestDistSq = Number.MAX_VALUE;
for (let i = 0; i < ports.length; i++) {
const d = ports[i].distanceSquared(world);
if (d < bestDistSq) { bestDistSq = d; bestIdx = i; }
}
distanceSquared 避免了开方运算——只需要比较大小,不需要精确距离值。
起点桩的方向决定了路由的出射方向——上桩向下出、右桩向右出,以此类推。
四、PathRouter:正交路由算法
正交路由(Orthogonal)产生阶梯状路径——水平和垂直交替,像曼哈顿的街道。
核心思路:从起点沿出射方向偏移一段距离,从终点沿入射方向偏移一段距离,中间用最少的折线连接。
static orthogonal(from, fromDir, to, toDir): Point[] {
const offset = 18; // 节点边缘外延量
const start = offsetPoint(from, fromDir, offset);
const end = offsetPoint(to, toDir, offset);
const pts = [from, start];
if (isHorizontal(fromDir)) {
pts.push(new Point(end.x, start.y)); // 先水平再垂直
} else {
pts.push(new Point(start.x, end.y)); // 先垂直再水平
}
pts.push(end, to);
return simplifyPath(pts); // 去除共线点
}
OFFSET = 18 是关键参数——太小会贴着节点边缘,太大会占用太多画布空间。18 像素在大多数流程图布局下效果最好。
simplifyPath 去除连续共线的点——如果三个点在同一条直线上,中间的点是多余的:
static simplifyPath(pts): Point[] {
const out = [pts[0]];
for (let i = 1; i < pts.length - 1; i++) {
const a = out[out.length - 1], b = pts[i], c = pts[i + 1];
const horizAB = Math.abs(a.y - b.y) < 0.5;
const horizBC = Math.abs(b.y - c.y) < 0.5;
if (!((horizAB && horizBC) || (vertAB && vertBC))) {
out.push(b);
}
}
out.push(pts[pts.length - 1]);
return out;
}
0.5 像素的容差用于处理浮点精度问题——坐标差 < 0.5 视为共线。
五、自动方向选择
autoOrthogonal 根据起点和终点的相对位置自动选择最佳方向:
static autoOrthogonal(from, to): Point[] {
const dx = to.x - from.x, dy = to.y - from.y;
if (Math.abs(dx) >= Math.abs(dy)) {
// 水平距离更大:从右出/左入 或 从左出/右入
return orthogonal(from, dx >= 0 ? 'right' : 'left', to, dx >= 0 ? 'left' : 'right');
} else {
// 垂直距离更大:从下出/上入 或 从上出/下入
return orthogonal(from, dy >= 0 ? 'down' : 'up', to, dy >= 0 ? 'up' : 'down');
}
}
选择规则:沿主轴方向出/入。水平距离大就水平出,垂直距离大就垂直出。这保证了路径最短、折线最少。

六、ConnectionShape:三种连线样式
ConnectionShape 支持三种渲染样式:
enum ConnectionStyle {
Straight = 'straight', // 直线
Orthogonal = 'orthogonal', // 正交(阶梯状)
Smooth = 'smooth', // 平滑曲线
}
渲染逻辑在 drawSelf 中——Straight 和 Orthogonal 都用 lineTo,Smooth 用 bezierCurveTo:
drawSelf(ctx) {
ctx.beginPath();
if (this.connectionStyle === ConnectionStyle.Smooth) {
ctx.moveTo(pts[0].x, pts[0].y);
for (let i = 1; i < pts.length; i++) {
const prev = pts[i-1], cur = pts[i];
const cpx = (prev.x + cur.x) / 2;
ctx.bezierCurveTo(cpx, prev.y, cpx, cur.y, cur.x, cur.y);
}
} else {
ctx.moveTo(pts[0].x, pts[0].y);
for (let i = 1; i < pts.length; i++) {
ctx.lineTo(pts[i].x, pts[i].y);
}
}
ctx.stroke();
}
Smooth 样式的贝塞尔控制点取水平中点——cpx = (prev.x + cur.x) / 2,产生 S 形平滑过渡。
Straight 和 Orthogonal 的区别不在渲染——而在路由。Straight 直接连首尾,Orthogonal 走 PathRouter 的阶梯路径。两者最终都用 lineTo 画折线。
七、箭头绘制
箭头是一个三角形,从最后一个路径点指向前一个点的方向:
drawArrow(ctx, from, to) {
const angle = Math.atan2(to.y - from.y, to.x - from.x);
const size = 10;
ctx.beginPath();
ctx.moveTo(to.x, to.y);
ctx.lineTo(to.x - size * Math.cos(angle - Math.PI/6), to.y - size * Math.sin(angle - Math.PI/6));
ctx.lineTo(to.x - size * Math.cos(angle + Math.PI/6), to.y - size * Math.sin(angle + Math.PI/6));
ctx.closePath();
ctx.fillStyle = this.style.stroke;
ctx.fill();
}
三角形的两个底角在 ±30°(π/6)——产生一个尖锐的等腰三角形。大小固定 10 像素,与 strokeWidth 无关。
箭头方向由 atan2 计算——返回从正 x 轴到连线方向的弧度。两个底角点在这个方向上偏移 ±30°。
八、连线标签
连线中间可以显示文字标签(如"是"/"否"),标签有白色背景保证可读性:
if (this.label.length > 0) {
const mid = this.midpoint();
// 绘制白色背景矩形
ctx.fillStyle = this.style.connectionLabelBg;
ctx.fillRect(mid.x - tw/2, mid.y - fs/2 - 4, tw, fs + 8);
// 绘制文字
ctx.fillStyle = this.style.fontColor;
ctx.fillText(this.label, mid.x, mid.y);
}
midpoint 取路径中间两个点的中点——保证标签在连线的视觉中心。背景矩形比文字大 4px 上下 padding,保证文字不贴边。
字号有下限 22px 和上限 32px——保证在任何缩放级别下都可读。
九、连线命中测试
连线的命中测试不同于普通图形——它检测"点到折线段的距离":
hitTest(worldPoint) {
const tolerance = Math.max(8, this.style.strokeWidth * 2.5);
const tol2 = tolerance * tolerance;
for (let i = 0; i < pts.length - 1; i++) {
// 点到线段的投影距离
const dx = b.x - a.x, dy = b.y - a.y;
const t = clamp(((wx-ax)*dx + (wy-ay)*dy) / (dx*dx+dy*dy), 0, 1);
const px = a.x + t * dx, py = a.y + t * dy;
const d2 = (wx-px)*(wx-px) + (wy-py)*(wy-py);
if (d2 <= tol2) return true;
}
return false;
}
容差取 max(8, strokeWidth * 2.5)——细线也有 8 像素的点击区域,粗线按比例放大。
投影参数 t 被 clamp 到 [0,1]——保证投影点在线段上,而不是延长线上。用 distanceSquared 而不是 distance 避免开方。

十、ConnectionTheming:深色主题适配
默认连线颜色 #1F2933 在深色画布上对比度不足。ConnectionTheming 在绘制前临时套用主题色,绘制后恢复:
static applyThemedDefaultsIfNeeded(conn, theme, backup) {
if (!isDefaultConnectionStroke(conn.style.stroke)) return false;
// 备份原始样式
backup.stroke = conn.style.stroke;
backup.fontColor = conn.style.fontColor;
// 套用主题色
conn.style.stroke = theme.diagramConnection;
conn.style.fontColor = theme.diagramConnectionLabelText;
return true; // 调用方须在绘制后 restore
}
这个模式保证了:用户自定义颜色的连线不受影响,只有使用默认色的连线才会被主题覆盖。
十一、动态跟随:节点移动后连线自动更新
连线的 draw 方法不使用自己的 transform——它直接用 routedPoints 的世界坐标绘制:
draw(ctx) {
if (!this.visible || this.routedPoints.length < 2) return;
ctx.save();
this.style.apply(ctx);
this.drawSelf(ctx); // 直接用 routedPoints
ctx.restore();
}
routedPoints 由控制器在每帧渲染前重新计算——基于当前节点位置调用 PathRouter,刷新路径点。这意味着:节点移动后,下一帧连线就会自动重路由。
这个设计的好处是:ConnectionShape 不需要知道节点的位置变化,只需要在渲染时拿到最新的 routedPoints。路由逻辑集中在控制器中,ConnectionShape 只负责绘制。
十二、踩坑记录
坑 1:连线不能连自己
finishConnectionAt 中有检查:hit.id === startState.fromShape.id 时放弃连线。如果不做这个检查,用户可能误操作创建自环连线,导致 PathRouter 死循环或渲染异常。
坑 2:正交路由的 OFFSET 太小
最初 OFFSET 设为 8——连线紧贴节点边缘,视觉上很难分辨"这是连线还是边框"。改成 18 后效果明显改善。但不能太大(> 30),否则在紧凑布局中连线会绕很远。
坑 3:Smooth 样式的控制点选择
Smooth 用水平中点作为贝塞尔控制点——cpx = (prev.x + cur.x) / 2。这在水平连线中效果很好,但在纯垂直连线中会产生"鼓包"。更精确的做法是用垂直中点,但当前实现为了简单统一用了水平中点。
坑 4:连线标签的遮挡
标签背景是白色矩形——在深色画布上很醒目,但如果两条连线交叉,标签可能互相遮挡。当前实现没有做标签避让——对于 MVP 来说够用,但生产环境需要考虑。
十三、算法参数一览
| 参数 | 值 | 说明 |
|---|---|---|
| 连接桩数量 | 4 | 上/右/下/左 |
| 正交路由 OFFSET | 18 px | 节点边缘外延量 |
| 箭头大小 | 10 px | 等腰三角形边长 |
| 箭头角度 | ±30° | 尖锐等腰三角形 |
| 命中容差 | max(8, sw×2.5) px | 细线也有 8px 点击区 |
| 共线判断阈值 | 0.5 px | 坐标差 < 0.5 视为共线 |
| 标签字号下限 | 22 px | 保证可读性 |
| 标签字号上限 | 32 px | 防止过大 |
| ConnectionStyle 数量 | 3 | Straight/Orthogonal/Smooth |
十四、总结
流程图连接线系统的核心是三个层次的协作:
端点层:ConnectionEndpoint 定义"连在哪"——softLink 绑定节点桩位,freePoint 固定世界坐标。绑定关系通过 shapeId 查找,节点移动时自动更新。
路由层:PathRouter 计算"怎么走"——正交路由产生阶梯状路径,OFFSET 保证连线不贴边,simplifyPath 去除共线点。自动方向选择根据相对位置选最短路径。
渲染层:ConnectionShape 负责"画出来"——三种样式(直线/正交/平滑)用不同的 Canvas API 绘制,箭头用 atan2 计算方向,标签用 midpoint 定位。
三者通过 routedPoints 连接:控制器每帧重新路由得到最新路径点,ConnectionShape 用这些点直接绘制。节点移动 → 路由重算 → 路径点更新 → 连线自动跟随——整个过程对用户完全透明。
整套系统不到 500 行 TypeScript,却能实现"拖节点、连线自动跟上"的完整体验。核心设计——桩位吸附、正交路由、动态跟随——是流程图编辑器的通用模式。
十五、连线的 SVG 导出
ConnectionShape 的 SVG 导出需要额外处理箭头标记——SVG 用 <marker> 定义箭头,连线通过 marker-end 属性引用:
toSvg(): string {
const parts = [`M${pts[0].x},${pts[0].y}`];
for (let i = 1; i < pts.length; i++) {
parts.push(`L${pts[i].x},${pts[i].y}`);
}
const arrowMarker = this.hasArrow ? ' marker-end="url(#arrow)"' : '';
let out = `<path d="${parts.join(' ')}" ${this.style.toSvgAttrs()}${arrowMarker}/>`;
if (this.label.length > 0) {
// 标签用 <rect> + <text> 组合
out += `<rect .../><text ...>${label}</text>`;
}
return out;
}
箭头标记 #arrow 在 SVG 文件头定义一次,所有连线共用。这比每条连线单独画三角形更高效——SVG 渲染器可以复用标记。
标签的背景矩形和文字分开导出——Canvas 中用 fillRect + fillText,SVG 中用 <rect> + <text>。两者的视觉效果一致。
十六、连线的克隆与序列化
克隆连线需要复制所有关键属性——端点引用、路由样式、箭头开关、标签文字、路径点缓存:
clone(): Shape {
const c = new ConnectionShape();
this.applyCloneIdentity(c); // 复制 id, name, visible, locked
c.from = this.from.clone();
c.to = this.to.clone();
c.connectionStyle = this.connectionStyle;
c.hasArrow = this.hasArrow;
c.label = this.label;
c.style = this.style.clone();
c.setRoutedPoints(this.routedPoints); // 路径点也要复制
return c;
}
applyCloneIdentity 是 Shape 基类的方法——它复制 id、name、visible、locked,但不复制 transform 和 style(子类各自处理)。连线的 transform 是单位矩阵(连线不用变换),所以基类的默认值就够了。
序列化(快照)时,ConnectionShape 需要保存 from/to 的 shapeId 和 portIndex——恢复时通过 shapeId 重新绑定到节点。routedPoints 不需要保存——恢复后会重新路由。
十七、踩坑记录补充
坑 5:连线的 z-order
连线画在节点上面——这是因为连线后添加到 shapes 数组中,渲染时后画的在上面。如果需要连线在节点下面,需要调整渲染顺序。
当前实现没有显式的 z-order 管理——所有 Shape 按数组顺序渲染。对于流程图来说,连线在上面是合理的——用户更容易选中和操作连线。
坑 6:多条连线的起点重叠
当多条连线从同一个桩出发时,它们的起点完全重叠——视觉上很难区分。更高级的实现会把起点沿桩的法线方向偏移,避免重叠。当前实现没有做这个——对于 MVP 来说够用。
十八、总结补充
流程图连接线系统的另一个设计亮点是"路由与渲染分离"——PathRouter 只负责计算路径点,ConnectionShape 只负责绘制。这意味着:
- 可以独立替换路由算法(比如换成 A* 搜索避障),不需要改 ConnectionShape
- 可以独立替换渲染样式(比如加阴影、加发光),不需要改 PathRouter
- 可以在同一连线上混合使用不同路由(比如起点正交、终点平滑),虽然当前不支持
这种分离是"单一职责原则"的体现——每个模块只做一件事,通过接口(routedPoints 数组)连接。
十九、完整参数汇总
| 参数 | 值 | 说明 |
|---|---|---|
| 连接桩数量 | 4 | 上/右/下/左 |
| 桩位位置 | 边中点 | (w/2,0), (w,h/2), (w/2,h), (0,h/2) |
| 正交路由 OFFSET | 18 px | 节点边缘外延量 |
| 共线判断阈值 | 0.5 px | 坐标差 < 0.5 视为共线 |
| 箭头大小 | 10 px | 等腰三角形边长 |
| 箭头角度 | ±30° (π/6) | 尖锐等腰三角形 |
| Smooth 控制点 | 水平中点 | cpx = (prev.x + cur.x) / 2 |
| 命中容差 | max(8, sw×2.5) px | 细线也有 8px 点击区 |
| 标签字号范围 | 22~32 px | 保证可读性 |
| 标签背景 padding | 4 px | 上下各 4px |
| 默认描边色 | #1F2933 | 深色画布上会被主题覆盖 |
| ConnectionStyle | 3 种 | Straight/Orthogonal/Smooth |
| FlowKind 子类型 | 8 种 | 流程图节点变体 |








































苏公安网备 32011402010933号