TypeScript中如何定义支持思维导图节点拖拽的惯性滑动与摩擦系数类型

思维导图类应用对节点拖拽的流畅度要求很高，用户松开鼠标之后，如果节点瞬间停下会显得非常生硬，而一段平滑衰减的惯性滑动会让整个交互显得高级许多。要把这种物理效果做扎实，第一步其实是把类型定义清楚。很多团队在做这类功能时习惯直接用几个裸的number变量表示速度和摩擦力，结果参数越加越多，最后连自己都分不清哪个是摩擦系数、哪个是阻尼倍率。本文就来聊一聊如何在TypeScript中设计一套严谨且可扩展的类型，专门服务于思维导图节点的惯性滑动。

先理解惯性滑动的物理模型

惯性滑动的本质是速度衰减。用户拖拽节点时，我们会持续记录鼠标的位移和间隔时间，松手的瞬间得到一个瞬时速度向量，之后每一帧让速度乘以一个小于1的摩擦系数，再把节点按当前速度移动一小段距离。当速度衰减到某个阈值以下时，惯性结束，节点停稳。

这个模型里至少涉及四个量：初始速度、摩擦系数、时间步长和停止阈值。其中摩擦系数最容易踩坑。有的框架把它定义成每秒衰减比例，比如0.05表示每秒速度变为原来的95%；有的则定义成每帧衰减比例，0.95表示每帧保留95%。两者在60帧每秒下的实际效果差异巨大，所以在类型层面把这个语义标注清楚非常有必要。

另外，思维导图节点是二维平面上的对象，速度需要拆成vx和vy两个分量，或者用向量的模加角度表示。分量式更常见，也方便和屏幕坐标系直接对应。理解了这些，我们就可以开始设计类型了。

核心类型定义：摩擦系数与惯性状态

首先定义摩擦系数配置。为了避免语义混淆，我们用字面量联合类型标明衰减模式，让调用方必须显式声明自己是按帧衰减还是按秒衰减，这样即使半年后回看代码也不会猜错含义。

// 摩擦系数的衰减模式
type FrictionMode = 'perFrame' | 'perSecond';

// 摩擦系数配置
interface FrictionConfig {
  /** 摩擦系数，取值范围 0 到 1 之间（不含端点） */
  value: number;
  /** 衰减模式：按帧或按秒 */
  mode: FrictionMode;
}

// 带校验的构造函数，防止传入非法系数
function createFriction(value: number, mode: FrictionMode = 'perFrame'): FrictionConfig {
  if (value <= 0 || value >= 1) {
    throw new RangeError(`摩擦系数必须在 (0, 1) 区间内，当前传入: ${value}`);
  }
  return { value, mode };
}

接着定义惯性状态。这个类型描述的是松手之后每一帧参与计算的数据快照，包含速度分量、当前时间戳以及是否已经结束。把状态和配置分开是刻意的：配置由外部传入且相对固定，状态则由动画循环不断更新，两者职责不同就不应该混在一个接口里。

// 二维速度向量
interface Velocity2D {
  vx: number; // 像素/秒
  vy: number; // 像素/秒
}

// 惯性滑动状态快照
interface InertiaState {
  velocity: Velocity2D;
  position: { x: number; y: number };
  startTime: number;
  active: boolean;
}

// 停止阈值配置
interface InertiaThresholds {
  /** 速度模长低于该值时停止，单位 像素/秒 */
  stopSpeed: number;
  /** 最大持续时间，防止极低摩擦导致永不停止，单位毫秒 */
  maxDuration: number;
}

用泛型与联合类型约束拖拽参数

有了基础类型，下一步是把它们组装成完整的拖拽惯性配置。这里建议用一个顶层接口统一管理，并通过泛型参数区分不同坐标系下的实现，比如屏幕坐标和画布局部坐标。思维导图通常支持缩放，缩放后鼠标的屏幕位移要除以缩放比才能得到节点在画布中的真实位移，所以类型上直接区分这两种坐标系能避免大量隐式换算错误。

// 坐标系种类
type CoordinateSpace = 'screen' | 'canvas';

// 完整的节点拖拽惯性配置
interface NodeDragInertiaOptions<S extends CoordinateSpace = 'screen'> {
  friction: FrictionConfig;
  thresholds: InertiaThresholds;
  coordinateSpace: S;
  /** 松手瞬间的速度采样窗口，单位毫秒，默认 100 */
  velocitySampleWindow?: number;
  /** 速度上限，防止甩动过猛，单位 像素/秒 */
  maxSpeed?: number;
}

// 类型别名：屏幕坐标配置
type ScreenInertiaOptions = NodeDragInertiaOptions<'screen'>;
// 类型别名：画布坐标配置
type CanvasInertiaOptions = NodeDragInertiaOptions<'canvas'>;

值得注意的是velocitySampleWindow这个可选属性。松手瞬间的速度如果只取最后一帧的位移来算，会因为帧抖动产生很大的误差，业界通行的做法是取最近约100毫秒内的平均速度。把这个窗口暴露成可配置项，可以让不同设备上的手感得到微调。maxSpeed同样重要，没有它的话，用户在触摸板上猛甩一下，节点可能飞出可视区域好几个屏幕。

落地：类型驱动的惯性计算函数

类型定义好之后，计算函数的签名会变得非常清晰，参数就是配置加状态，返回新的状态。函数内部根据friction的mode做分支处理：perFrame模式直接乘系数，perSecond模式则要按帧间隔换算，公式为value的deltaTime/1000次方。

function stepInertia(
  state: InertiaState,
  options: CanvasInertiaOptions,
  deltaTime: number // 毫秒
): InertiaState {
  const { friction, thresholds } = options;
  const seconds = deltaTime / 1000;

  // 根据衰减模式计算本帧的保留比例
  const retention =
    friction.mode === 'perFrame'
      ? friction.value
      : Math.pow(friction.value, seconds);

  let vx = state.velocity.vx * retention;
  let vy = state.velocity.vy * retention;

  const elapsed = performance.now() - state.startTime;
  const speed = Math.hypot(vx, vy);

  const active = speed > thresholds.stopSpeed && elapsed < thresholds.maxDuration;

  return {
    velocity: { vx, vy },
    position: {
      x: state.position.x + vx * seconds,
      y: state.position.y + vy * seconds,
    },
    startTime: state.startTime,
    active,
  };
}

这个函数是纯函数，输入状态输出新状态，不修改任何外部变量，配合前端框架的响应式系统或者直接塞进requestAnimationFrame循环都很方便。当active变为false时，外层循环停止调用即可。如果你想在惯性结束前让节点吸附到最近的网格或者父节点边缘，只需要在stepInertia返回之前对position做一次修正，类型结构完全不用动。

最后补充一个实践建议：给FrictionConfig的value加上运行时校验的同时，也可以借助TypeScript的模板字面量类型或品牌类型进一步收窄，但对摩擦系数这种取值连续的浮点数来说，运行时校验的性价比远高于复杂的类型体操。类型系统负责让参数各就各位、语义清晰，运行时校验负责兜住数值范围的底，两者配合就足以支撑一套健壮的思维导图节点拖拽惯性体验了。

TypeScript惯性滑动摩擦系数修改时间：2026-09-08 23:35:07