TypeScript中如何定义支持甘特图任务进度拖拽时的吸附网格与对齐线类型

在甘特图编辑器中，用户拖动任务进度条时往往希望自动贴合到固定的时间刻度上，或者与其他任务的开端、结束端保持视觉对齐。这种体验背后依赖两套机制：一是吸附网格，即把自由像素位置映射到离散的时间步长；二是对齐线，即在拖拽过程中动态计算出参考基准并显示辅助线。用TypeScript来建模这两类概念，可以让拖拽算法在编译期就获得正确性与可维护性保障。

吸附网格类型的底层建模

吸附网格的本质是一组离散的锚点序列，通常由起始时间、步长和总跨度推导而来。我们在TypeScript中不应只用数字表示，而应将其封装为带有语义的接口，从而把“时间转像素”和“像素转时间”的能力内聚在一起。这样，当甘特图需要切换日、周、月视图时，只需替换网格实例，拖拽逻辑无需改动。

下面给出一个基础网格类型定义。我们用GridStep描述最小吸附单位，用SnapGrid接口聚合计算方法。注意这里的pxPerMs表示每毫秒对应的像素值，是像素与时间互转的核心比例。

// 网格步长类型，支持时间轴常见单位
export type GridStep = 'hour' | 'day' | 'week' | 'month';

// 吸附网格接口
export interface SnapGrid {
  step: GridStep;
  pxPerMs: number;
  // 将像素x吸附到最近网格线对应的时间
  snapPixelToTime: (x: number) => number;
  // 将时间吸附到最近网格像素位置
  snapTimeToPixel: (time: number) => number;
}

// 以天为步长的网格实现示例
export function createDayGrid(pxPerMs: number): SnapGrid {
  const dayMs = 24 * 60 * 60 * 1000;
  return {
    step: 'day',
    pxPerMs,
    snapPixelToTime: (x: number) => {
      const rawTime = x / pxPerMs;
      return Math.round(rawTime / dayMs) * dayMs;
    },
    snapTimeToPixel: (time: number) => {
      return (Math.round(time / dayMs) * dayMs) * pxPerMs;
    }
  };
}

上述定义的优点在于把“步长”限定为字面量联合类型，调用方无法传入非法字符串。如果项目需要更细粒度，比如半小时，直接扩充GridStep即可，所有依赖该类型的地方都会获得编译器提示。相比使用普通number表示步长毫秒数，这种建模方式显著降低了魔法数字带来的隐患。

对齐线类型的分类与判别

对齐线出现在拖拽任务条时，当它的边缘接近其他任务的边缘或特殊标记时，界面会绘制一条参考线并强制吸附。从类型角度，对齐线可分为水平对齐线（基于时间轴横向坐标）与垂直对齐线（基于行轨道纵向坐标），以及一种智能对齐线，它同时参考多个任务并选择偏差最小者。我们需要明确区分它们，以便渲染层使用不同样式。

使用TypeScript的判别联合（discriminated union）可以优雅表达这种分类。我们引入kind字段作为判别属性，并为每种线附带专属元数据，例如水平线带time，垂直线带rowId。下面的代码展示了类型声明与类型守卫函数，后者能在拖拽事件处理中安全收窄类型。

// 对齐线判别联合类型
export type AlignLine =
  | { kind: 'horizontal'; time: number; offsetPx: number }
  | { kind: 'vertical'; rowId: string; offsetPx: number }
  | { kind: 'smart'; time: number; rowId: string; strength: number };

// 类型守卫：是否为水平线
export function isHorizontalLine(line: AlignLine): line is Extract<AlignLine, { kind: 'horizontal' }> {
  return line.kind === 'horizontal';
}

// 计算对齐偏差是否在阈值内
export function withinThreshold(line: AlignLine, dragPx: number, threshold: number): boolean {
  return Math.abs(line.offsetPx - dragPx) <= threshold;
}

在实践中，垂直线多用于跨行任务对齐，比如把任务A的起始拉到任务B所在行的起始；水平线则处理同一行内不同任务的时间贴合。智能线通常在对齐线过多时由算法筛选而出，其strength字段可表示优先级。借助类型守卫，渲染组件能用if (isHorizontalLine(line))直接访问time而不报错，避免了任意类型断言。

拖拽控制器中的类型组合运用

真正落地时，吸附网格与对齐线需要协同工作：先由网格提供基础时间刻度约束，再由对齐线在临界区做微调。我们可定义一个拖拽上下文类型，把两者作为字段组合，并附加当前拖拽任务标识。这样，从指针事件到位置提交的整个链路都跑在强类型之上。

以下示例给出一个简化的拖拽计算函数。它接收指针像素、网格与候选对齐线数组，依次尝试对齐线吸附，失败则回退到网格吸附。注意函数返回的是结构化结果，包含最终像素与时间，以及触发了哪类对齐，方便上层记录用户意图。

export interface DragContext {
  grid: SnapGrid;
  lines: AlignLine[];
  taskId: string;
  threshold: number;
}

export interface DragResult {
  px: number;
  time: number;
  snappedBy: 'grid' | 'line' | null;
}

export function resolveDragPosition(rawX: number, ctx: DragContext): DragResult {
  for (const line of ctx.lines) {
    if (withinThreshold(line, rawX, ctx.threshold)) {
      const time = line.kind === 'horizontal' || line.kind === 'smart'
        ? line.time
        : ctx.grid.snapPixelToTime(rawX);
      return {
        px: ctx.grid.snapTimeToPixel(time),
        time,
        snappedBy: 'line'
      };
    }
  }
  const time = ctx.grid.snapPixelToTime(rawX);
  return {
    px: ctx.grid.snapTimeToPixel(time),
    time,
    snappedBy: 'grid'
  };
}

这种组合方式让业务代码清晰表达“先线后格”的策略。如果未来要支持斜向对齐或依赖关键路径高亮，只需扩展AlignLine与DragContext，核心函数结构不变。相较早期用普通对象加注释说明字段含义的写法，当前方案在重构甘特图引擎时能将大部分错位bug消灭在编辑阶段。

从架构看，把吸附与对齐抽象为类型而非具体类，也方便在Web Worker中做离屏计算。由于类型本身不带运行时逻辑，主线程与Worker可共享同一份.d.ts声明，确保两端对拖拽参数的理解一致。这对大型项目管理工具尤为重要，因为时间轴可能包含上千任务，类型安全能降低协作成本。

TypeScript甘特图拖拽吸附对齐修改时间：2026-08-17 15:20:37