文档开发者中心
我的

4个连接桩的局部到世界坐标转换实现

浏览2967发布于2026-06-30 15:45河南
本文章最后由 在人间耕耘 于 2026-07-02 05:18 编辑

流程图连接线:端点吸附 + 智能路由 + 箭头绘制——让连线跟着节点跑

本文基于矢量图形编辑器项目,拆解流程图连接线系统的完整实现:ConnectionEndpoint 端点模型、PathRouter 正交路由、FlowShape 连接桩、箭头绘制、连线命中测试。全文约 400 行,配 3 张架构图。

引言

流程图编辑器的核心体验是"拖个节点,连线自动跟上"。

听起来理所当然——但背后涉及三个问题:连线的两端到底连在哪(端点模型)、中间的路径怎么走(路由算法)、节点移动后连线怎么更新(动态跟随)。

本文拆解的就是这套系统。ConnectionEndpoint 定义"连在哪"——可以是节点的连接桩,也可以是一个自由点。PathRouter 计算"怎么走"——正交路由产生阶梯状路径。ConnectionShape 负责"画出来"——三种样式(直线/正交/平滑)+ 箭头 + 标签。

全部逻辑加起来不到 500 行 TypeScript,却能支撑一个完整的流程图编辑器。

流程图连接线系统:端点吸附 + 智能路由 + 箭头绘制

一、ConnectionEndpoint:端点的两种身份

连线的每一端可以是两种东西:

  1. 连接桩(softLink):绑定到某个 FlowShape 的某个桩位,节点移动时连线自动跟随
  2. 自由点(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 种 流程图节点变体
收藏
0
回复
0
分享
全部评论
暂无评论
暂无评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
流程图连接线:端点吸附 + 智能路由 + 箭头绘制——让连线跟着节点跑
引言
一、ConnectionEndpoint:端点的两种身份
二、FlowShape 连接桩:4 个吸附点
三、端点吸附:最近桩位匹配
四、PathRouter:正交路由算法
五、自动方向选择
六、ConnectionShape:三种连线样式
七、箭头绘制
八、连线标签
九、连线命中测试
十、ConnectionTheming:深色主题适配
十一、动态跟随:节点移动后连线自动更新
十二、踩坑记录
十三、算法参数一览
十四、总结
十五、连线的 SVG 导出
十六、连线的克隆与序列化
十七、踩坑记录补充
十八、总结补充
十九、完整参数汇总
了解社区公约,与您携手共创和谐专业的开发者社区。