TypeScript中如何定义支持流程图节点连线正交路由的拐点最小间距类型

在流程图编辑器的正交连线模式中，连线由一系列水平和垂直线段拼接而成，相邻线段相交处就是拐点。拐点最小间距用于约束两个拐点之间必须保留的像素或网格距离，避免折线过于密集。TypeScript里如果没有把这个参数定义清楚，布局算法、配置面板和序列化数据很容易各自为政，导致同一个配置在不同模块中出现不一致。因此，我们应当用类型系统把拐点最小间距固化成可复用、可校验的类型。

正交路由的核心问题是路径生成。从一个节点的输出端口到另一个节点的输入端口，算法往往先沿固定方向引出，再在空白区域转向，最终接入目标。每转向九十度就产生一个拐点。若两个拐点之间的线段长度小于最小间距，比如只相隔4像素，在100%缩放下还能勉强看出折角，但缩放到75%或更小时，两个拐点就会在视觉上合并成一个不规则的节点。更重要的是，当用户尝试拖动线段时，命中检测会变得非常不稳定。

一、拐点最小间距对正交路由的实际影响

最小间距参数并不是一个孤立的视觉偏好，它直接参与布局算法。很多正交布线算法会先计算一条最短的曼哈顿路径，再通过绕障和修形来满足美观约束。如果最小间距设置得过大，而两个节点之间的空间有限，算法就必须增加折返或者绕到更远的通道，这可能导致连线穿过其他节点。反之，如果间距过小，拐点会挤在一起，连线看起来像锯齿，并且后续编辑时很难选中目标线段。

从交互角度看，流程图编辑器通常提供拖拽整条连线、拖拽拐点、拖拽线段三种操作。拖拽线段时，需要判断用户点击的是水平段还是垂直段。如果没有最小间距约束，一条线上可能出现多个相距仅数像素的拐点，鼠标稍微偏一点就选中了另一段，操作体验很差。因此，把这个参数作为配置类型的一部分，不仅能让布局引擎输出更稳定的路径，也能让UI层在做命中检测时使用同一个阈值。

在最简单的实现里，大家可能会用一个宽泛的数值类型来表示它：

type CornerGap = number; // 单位：像素

interface OrthogonalRouteOptions {
  cornerGap?: CornerGap;
}

这个定义确实能表达“存在一个拐点间距”，但它没有说明单位、是否允许负值、是否支持自动计算。调用方可以传入100，也可以传入-3，甚至传入Infinity。编译期完全无法拦截这些不合理输入。当项目逐渐变大，这种模糊类型会在不同模块之间造成隐性约定，最后只能靠运行时报错来兜底。

二、从基本接口到可校验类型的演进

要让拐点最小间距经得起实际使用，首先需要明确它可能出现的形态。一个比较实用的设计是允许三种输入：纯数字表示像素，字符串表示带单位的数值，字符串auto表示由布局引擎自动计算。单位可以限定为px和cell，后者常用于基于网格的流程图编辑器。这样类型就可以写成：

type LengthUnit = "px" | "cell";

type CornerGapValue =
  | number
  | `${number}${LengthUnit}`
  | "auto";

interface OrthogonalRoutingConfig {
  minCornerGap?: CornerGapValue;
  cornerRadius?: number;
  minSegmentLength?: number;
}

这里的模板字面量类型是TypeScript 4.1之后提供的写法，它能把字符串约束成数字加指定单位的形式。例如传入12px和2cell都能通过检查，而传入12em会在编译期报错。相比纯number，这个定义已经能过滤掉大部分单位错误。

但仅靠联合类型还是无法阻止正数约束被绕过，因为number本身包含负数、NaN和Infinity。更严格的方案是引入品牌类型。品牌类型不改变运行时表现，但通过交叉一个唯一的属性，让普通number不能直接赋值给该类型：

type PositiveNumber<T extends number> = number & { readonly __positive: T };

type MinCornerGap = PositiveNumber<number>;

使用MinCornerGap后，调用方必须显式经过一个构造或校验函数才能生成合法值。这样可以在类型层面表达“必须是经过确认的正数”。不过品牌类型会带来一定样板代码，没有必要在早期就加。更实际的做法是保留接口的灵活性，在运行时做统一校验。

一个更完整的配置接口还可以包含拐角半径和最小线段长度。拐角半径影响圆角程度，最小线段长度则控制连线引出后至少要走多长再转向。这两个参数和拐点最小间距一起，构成了正交路由的可读性约束。把它们放进同一个接口，能让设置面板一次性收集所有几何参数。

三、接入布局引擎与运行时校验

类型系统只在编译期有效，用户配置往往来自JSON文件、后端接口或本地存储，这些数据在整个应用生命周期中可能会有任意结构。因此，除了声明类型，还需要运行时类型守卫。下面这个函数可以把外部输入解析成合法的像素值：

function isFiniteGap(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && value >= 0;
}

function resolveMinCornerGap(
  raw: OrthogonalRoutingConfig["minCornerGap"]
): number {
  if (raw === undefined || raw === "auto") {
    return DEFAULT_MIN_CORNER_GAP;
  }
  if (typeof raw === "number") {
    return isFiniteGap(raw) ? raw : DEFAULT_MIN_CORNER_GAP;
  }
  const match = /^(\d+(?:\.\d+)?)(px|cell)$/.exec(raw);
  if (!match) return DEFAULT_MIN_CORNER_GAP;
  const value = Number(match[1]);
  if (!isFiniteGap(value)) return DEFAULT_MIN_CORNER_GAP;
  return match[2] === "cell" ? value * CELL_SIZE : value;
}

这个函数首先处理缺省和自动模式，然后处理纯数字，最后用正则把带单位字符串拆成数值和单位。所有无法解析或非法的情况都回退到默认值。通过这样的运行时守卫，即使外界传入了一个空字符串或负数，布局引擎拿到的也一定是一个安全的正数像素值。

在实际工程中，我们还可以进一步把解析结果包成Result类型，明确区分成功和失败，而不是静默回退。对于必须反馈给用户的配置错误，比如用户把最小间距设成了-20像素，应该弹出一个表单校验提示，而不是默默改回默认值。类型守卫函数可以返回布尔值，也可以返回带错误信息的判别联合：

type ParseResult =
  | { ok: true; value: number }
  | { ok: false; reason: string };

function parseMinCornerGap(raw: unknown): ParseResult {
  if (raw === undefined || raw === "auto") {
    return { ok: true, value: DEFAULT_MIN_CORNER_GAP };
  }
  if (typeof raw === "number" && isFiniteGap(raw)) {
    return { ok: true, value: raw };
  }
  const match = typeof raw === "string"
    ? /^(\d+(?:\.\d+)?)(px|cell)$/.exec(raw)
    : null;
  if (match) {
    const value = Number(match[1]);
    if (isFiniteGap(value)) {
      return match[2] === "cell"
        ? { ok: true, value: value * CELL_SIZE }
        : { ok: true, value };
    }
  }
  return { ok: false, reason: "minCornerGap必须是正数、px/cell单位或auto" };
}

这里用了判别联合，调用方可以通过检查ok字段来收窄类型。成功后拿到的value是经过归一化的像素数，可以直接参与布局计算；失败时reason可以展示在设置面板上。这种设计比简单返回默认值更透明，也更适合编辑器类应用。

四、用泛型和工具类型提升可维护性

当流程图支持多种画布单位时，上面的配置类型会与具体单位强绑定。可以把单位作为泛型参数，让同一套接口在像素模式和网格模式下复用：

interface OrthogonalRoutingConfig<TUnit extends string = "px" | "cell"> {
  minCornerGap?: number | `${number}${TUnit}` | "auto";
  cornerRadius?: number;
  minSegmentLength?: number;
}

type PixelRoutingConfig = OrthogonalRoutingConfig<"px">;
type GridRoutingConfig = OrthogonalRoutingConfig<"cell">;

这个泛型设计让PixelRoutingConfig只接受不带单位或带px的字符串，GridRoutingConfig只接受不带单位或带cell的字符串。对于不同画布类型，可以分别生成对应的设置面板类型，同时复用底层的解析函数。泛型参数默认值还能兼容既有的调用方，不需要修改全部代码。

在内部布局引擎中，我们通常不希望外部直接修改配置对象。可以用Readonly和Required工具类型来生成内部归一化配置类型：

type OrthogonalRoutingInput = Partial<OrthogonalRoutingConfig>;

type OrthogonalRoutingResolved = Readonly<
  Required<OrthogonalRoutingConfig>
>;

function resolveRoutingConfig(
  input: OrthogonalRoutingInput
): OrthogonalRoutingResolved {
  return Object.freeze({
    minCornerGap: resolveMinCornerGap(input.minCornerGap),
    cornerRadius: input.cornerRadius ?? DEFAULT_CORNER_RADIUS,
    minSegmentLength: input.minSegmentLength ?? DEFAULT_MIN_SEGMENT_LENGTH,
  });
}

上面的OrthogonalRoutingResolved确保所有字段都存在且只读，Object.freeze则在运行时阻止修改。内部分发到布局引擎、碰撞检测模块或渲染模块时，大家都拿到同一个不可变配置对象，避免某个模块在运行中临时改掉最小间距而影响后续计算。输入和输出类型分开，也让函数职责更清晰。

当然，类型设计并不是越复杂越好。如果项目中的流程图只在固定像素画布上运行，完全可以把minCornerGap定义成一个简单的number，并搭配一个默认常量。当出现跨端缩放、网格对齐或用户自定义单位的需求时，再逐步引入联合类型和泛型。这样既不会让早期开发被复杂类型拖累，也能在复杂度上升时保护代码不被魔法数字侵蚀。

TypeScript正交路由拐点最小间距修改时间：2026-10-03 20:59:14