TypeScript中如何定义支持思维导图节点拖拽时的惯性滑动与最大速度限制类型

思维导图组件的交互体验中，节点拖拽的惯性滑动是影响手感的关键细节。用户松手后节点不是立即停止，而是带着衰减的速度继续移动一段距离，这种物理反馈让界面显得自然流畅。要在TypeScript中实现这套逻辑，第一步不是写动画代码，而是把速度、衰减、阈值这些概念用类型准确地表达出来。类型定义得清晰，后续的物理计算和边界处理才不容易出错。

一、基础类型：速度向量与拖拽状态

惯性滑动的核心数据是速度向量。拖拽过程中，每帧记录指针位置和时间戳，松手时根据最近若干帧的位移计算初速度。首先要定义速度和位置的类型。二维坐标系下用Velocity2D表示，它包含x和y两个分量，单位通常是像素每毫秒。

// 二维速度向量，单位：px/ms
interface Velocity2D {
  x: number;
  y: number;
}

// 二维坐标点
interface Point2D {
  x: number;
  y: number;
}

// 速度采样记录：某一时刻的位置
interface VelocitySample {
  point: Point2D;
  timestamp: number; // performance.now() 的结果
}

有了这几个基础类型，拖拽过程中的状态机也需要类型化。思维导图节点的拖拽一般有三种状态：未拖拽、拖拽中、惯性滑动中。用字面量联合类型比枚举更轻量，且配合switch判断时能获得完备性检查。

type DragPhase = 'idle' | 'dragging' | 'inertial';

// 拖拽会话的完整状态
interface DragSession {
  phase: DragPhase;
  nodeId: string;          // 被拖拽的节点标识
  samples: VelocitySample[]; // 最近的速度采样队列
  origin: Point2D;         // 拖拽起始点
  current: Point2D;        // 当前指针位置
}

注意samples设计为队列结构，惯性初速度只取松手前最近100毫秒左右的采样，太旧的采样会让计算出的速度偏小，松手瞬间如果指针恰好停顿，速度会被严重低估。类型层面无法约束队列长度，但可以在注释中约定，或者在运行时用固定长度的环形缓冲封装。

二、惯性物理配置：衰减系数与最大速度限制

惯性滑动的物理模型常用指数衰减：每帧速度乘以一个小于1的衰减因子，直到速度低于停止阈值。最大速度限制则是为了防止用户快速甩动节点时，导图画布滚出十万八千里。这两个参数的类型定义需要体现取值范围语义。

interface InertiaConfig {
  /** 衰减因子，取值 (0, 1)，越接近1惯性持续越久 */
  friction: number;
  /** 最大速度，单位 px/ms，超过该值的速度分量会被钳制 */
  maxVelocity: number;
  /** 速度低于该值时惯性动画停止 */
  minStopVelocity: number;
  /** 采样窗口时长，仅统计松手前该毫秒数内的采样 */
  sampleWindowMs: number;
}

// 带默认值的预设配置，用 satisfies 保证字面量符合接口
const DEFAULT_INERTIA: InertiaConfig = {
  friction: 0.95,
  maxVelocity: 4,
  minStopVelocity: 0.02,
  sampleWindowMs: 100,
} satisfies InertiaConfig;

这里用satisfies而不是类型注解有两个好处：一是保留字面量类型信息，二是如果字段名拼写错误或类型不符，编译期立刻报错。比const x: InertiaConfig = {...}的写法更严格。

有些团队喜欢更严格的做法，用泛型和模板字面量类型把取值范围编码进类型系统，比如要求friction必须在0和1之间。TypeScript本身不支持数值范围类型，但可以通过品牌类型（branded type）配合运行时校验函数模拟：

// 品牌类型：标记一个数字已经通过了范围校验
type ValidFriction = number & { readonly __brand: 'ValidFriction' };

function createFriction(value: number): ValidFriction {
  if (value <= 0 || value >= 1) {
    throw new RangeError(`friction 必须在 (0,1) 区间，收到 ${value}`);
  }
  return value as ValidFriction;
}

interface StrictInertiaConfig {
  friction: ValidFriction;
  maxVelocity: number;
  minStopVelocity: number;
}

这种写法把运行时校验和编译期类型绑定在一起，只有在createFriction中校验过的值才能赋给friction字段。对于导图组件这种会被多处二次开发的库代码，这种防御性设计能避免外部传入非法配置导致动画死循环（比如friction等于1时速度永远不衰减）。

三、速度钳制与惯性动画的类型安全实现

定义好配置后，松手时的速度计算和钳制逻辑就可以写出完整签名。钳制函数要处理两种策略：整体限幅和分量限幅。整体限幅保留方向但限制合速度模长，分量限幅分别限制x和y。思维导图的画布一般是自由平移的，推荐整体限幅，因为甩动方向本身不应被改变。

type ClampStrategy = 'magnitude' | 'component';

function clampVelocity(
  velocity: Velocity2D,
  maxVelocity: number,
  strategy: ClampStrategy = 'magnitude'
): Velocity2D {
  if (strategy === 'component') {
    // 分量限幅：x、y 各自独立限制
    const clamp = (v: number) => Math.max(-maxVelocity, Math.min(maxVelocity, v));
    return { x: clamp(velocity.x), y: clamp(velocity.y) };
  }
  // 整体限幅：限制速度向量的模长
  const magnitude = Math.hypot(velocity.x, velocity.y);
  if (magnitude <= maxVelocity || magnitude === 0) {
    return { ...velocity };
  }
  const scale = maxVelocity / magnitude;
  return { x: velocity.x * scale, y: velocity.y * scale };
}

惯性动画每一帧的推进函数也要类型化。输入当前速度和配置，输出新的速度和位移增量，同时用返回值区分动画是否结束：

interface InertiaStepResult {
  velocity: Velocity2D;
  delta: Point2D;    // 本帧位移增量
  shouldContinue: boolean;
}

function stepInertia(
  velocity: Velocity2D,
  config: InertiaConfig,
  deltaTime: number // 帧间隔，单位 ms
): InertiaStepResult {
  // 先做衰减
  const decayed: Velocity2D = {
    x: velocity.x * Math.pow(config.friction, deltaTime / 16.67),
    y: velocity.y * Math.pow(config.friction, deltaTime / 16.67),
  };
  // 再钳制最大速度
  const clamped = clampVelocity(decayed, config.maxVelocity);
  const magnitude = Math.hypot(clamped.x, clamped.y);
  return {
    velocity: clamped,
    delta: { x: clamped.x * deltaTime, y: clamped.y * deltaTime },
    shouldContinue: magnitude > config.minStopVelocity,
  };
}

衰减计算用Math.pow(friction, deltaTime / 16.67)做了帧率无关处理，16.67毫秒是60fps的单帧时长。这样无论浏览器跑在60Hz还是120Hz，惯性持续时间都一致。类型上InertiaStepResult把速度、位移、是否继续三个信息打包返回，调用方拿到的数据结构完整且明确，避免了多返回值散落导致的类型混乱。

四、边界回弹与事件回调的联合类型设计

思维导图画布通常有内容边界，惯性滑动到边界时要么停止要么回弹。回弹状态可以作为DragPhase的扩展，也可以用独立的联合类型描述动画状态，后者扩展性更好：

type MotionState =
  | { readonly kind: 'idle' }
  | { readonly kind: 'dragging'; nodeId: string }
  | { readonly kind: 'inertia'; velocity: Velocity2D }
  | { readonly kind: 'bounce'; axis: 'x' | 'y'; overshoot: number };

// 可辨识联合配合类型守卫
function isBouncing(state: MotionState): state is Extract<MotionState, { kind: 'bounce' }> {
  return state.kind === 'bounce';
}

这个可辨识联合的好处是，每个状态携带的数据各不相同：拖拽状态关心节点ID，惯性状态关心速度，回弹状态关心超出的轴向和距离。如果用一个扁平接口把所有字段塞进去，就会出现大量可能为undefined的字段，类型安全性大打折扣。配合Extract工具类型写类型守卫，判断分支内可以安全访问axis和overshoot。

最后是回调签名。导图组件通常会向外部暴露惯性动画的生命周期事件，签名定义要兼顾信息完整和向后兼容：

interface InertiaEvents {
  onInertiaStart: (payload: {
    nodeId: string;
    initialVelocity: Velocity2D; // 已钳制后的初速度
    clamped: boolean;             // 是否触发了最大速度限制
  }) => void;

  onInertiaFrame: (payload: {
    delta: Point2D;
    remainingVelocity: Velocity2D;
  }) => void;

  onInertiaEnd: (reason: 'velocity-decayed' | 'boundary-hit' | 'interrupted') => void;
}

其中clamped字段对调试非常有用，当用户反馈惯性太猛或太弱时，可以先确认是否频繁触发速度钳制。onInertiaEnd的参数用字面量联合描述结束原因，边界命中和用户中断是不同的情况，上层逻辑可能需要区别对待，比如中断时立即停止回弹动画。

总结一下，这类交互类型定义的要点在于：用基础接口表达物理量，用字面量联合表达状态机，用品牌类型加固取值范围约束，用可辨识联合管理复杂状态。把类型设计好之后，惯性滑动的实现代码基本就是类型签名的填空题，重构和排查问题的成本都会显著降低。

TypeScript类型定义惯性滑动节点拖拽修改时间：2026-08-31 10:19:17