TypeScript中如何定义支持甘特图任务行高的自适应调整计算数据类型

甘特图的任务行高如果只用一个固定像素值或简单的数字常量维护，后期一定会遇到各种边界问题：任务名称过长自动换行时行高不够，里程碑图标和依赖线加进来后内容重叠，缩进层级改变时文字被裁剪。要解决这类问题，不是靠不断加判断分支，而是把行高从静态配置升级为可计算的数据类型。通过TypeScript的类型系统，我们可以把影响行高的变量、计算策略和计算结果统一建模，让组件只依赖明确的输入输出类型。

一、拆解影响任务行高的变量

先看一个常见的场景：甘特图左侧任务面板里，每个任务占用一行，行高通常被写死为32像素。当任务名称超过显示宽度时，如果启用了自动换行，第二行文本就会溢出到下一行，与下面的任务条重叠。即使没有换行，里程碑任务的菱形标记也需要额外垂直空间。再考虑父子任务的缩进，缩进层级越深，可用文本宽度越小，换行概率越高。与此同时，字体大小、行高系数、是否显示依赖箭头、是否带进度条内嵌文本，都会影响真正需要的行高。

这些变量如果散落在不同组件中判断，类型就会变成一堆零散的number值，维护成本很高。更好的做法是先定义一个输入类型，把所有影响行高的因素聚合起来。下面这个接口描述了计算单行高度所需的原始数据：

interface TaskRowInput {
  taskName: string;
  fontSize: number;
  lineHeight: number;
  availableWidth: number;
  indentLevel: number;
  hasMilestone: boolean;
  hasDependencyMarker: boolean;
  showProgressText: boolean;
}

这个接口的作用是把“我需要哪些数据才能算出高度”这件事显式化。后续任何计算函数都只接收这个类型，而不是零散的参数。值得注意的是，availableWidth 已经扣除了缩进和图标占位，这样文本换行计算就能直接使用，避免在计算逻辑里再次处理缩进。

二、用联合类型表达自适应策略

行高计算并不是只有一种模式。有些甘特图希望最小行高兜底，有些要求严格按照内容高度，有些则需要根据自定义元素尺寸动态返回。如果只定义一个数字返回值，就无法区分这些策略。TypeScript的可辨识联合类型很适合表达这种情况：

type RowHeightStrategy =
  | { kind: 'fixed'; height: number }
  | { kind: 'auto'; minHeight: number; maxHeight: number; lineHeight: number }
  | { kind: 'content'; paddingTop: number; paddingBottom: number };

这里每个分支都有一个kind字段作为判别依据。固定策略直接给出高度，自动策略通过最小高度、最大高度和行高计算，内容策略则基于额外内边距和实际内容尺寸决定。使用联合类型的好处是，调用方可以通过switch对kind做穷尽检查，漏掉某个分支时TypeScript会给出编译错误。

为了让类型更加完整，还可以定义一个结果类型，把计算后得到的行高、实际行数以及是否需要截断等信息一并返回。这样调用渲染层时不用重复计算行数：

interface RowHeightResult {
  height: number;
  lineCount: number;
  actualStrategy: RowHeightStrategy['kind'];
  needsTruncation: boolean;
}

将策略和结果分开，能避免计算函数内部出现大量条件判断。调用方先传入TaskRowInput和一个RowHeightStrategy，函数根据策略分支输出统一结构的RowHeightResult。后续如果新增策略，只需要扩展联合类型和对应的计算分支。

三、实现行高计算纯函数与边界控制

有了类型定义，下一步是写出计算函数。纯函数的好处是：同样的输入永远返回同样的输出，不依赖外部状态，便于单元测试和性能缓存。计算的核心是根据可用宽度估算文本所需的行数。这里用平均字符宽度做估算，生产环境可以换成Canvas测量或其他精确度量：

function estimateLineCount(text: string, fontSize: number, availableWidth: number): number {
  if (text.length === 0) return 1;
  const avgCharWidth = fontSize * 0.6;
  const charsPerLine = Math.max(1, Math.floor(availableWidth / avgCharWidth));
  return Math.ceil(text.length / charsPerLine);
}

function calculateTaskRowHeight(
  input: TaskRowInput,
  strategy: RowHeightStrategy
): RowHeightResult {
  if (strategy.kind === 'fixed') {
    return {
      height: strategy.height,
      lineCount: 1,
      actualStrategy: strategy.kind,
      needsTruncation: false,
    };
  }

  const textWidth = input.availableWidth - input.indentLevel * 12;
  let lineCount = estimateLineCount(input.taskName, input.fontSize, textWidth);
  if (input.hasMilestone) lineCount += 1;
  if (input.hasDependencyMarker) lineCount += 1;
  if (input.showProgressText) lineCount += 1;

  if (strategy.kind === 'auto') {
    const rawHeight = lineCount * strategy.lineHeight;
    const clampedHeight = Math.min(strategy.maxHeight, Math.max(strategy.minHeight, rawHeight));
    return {
      height: clampedHeight,
      lineCount,
      actualStrategy: strategy.kind,
      needsTruncation: rawHeight > strategy.maxHeight,
    };
  }

  const contentHeight = lineCount * input.lineHeight + strategy.paddingTop + strategy.paddingBottom;
  return {
    height: contentHeight,
    lineCount,
    actualStrategy: strategy.kind,
    needsTruncation: false,
  };
}

这个函数先处理固定策略，再处理需要行数计算的自动策略和内容策略。边界控制放在了自动策略里：Math.min和Math.max保证高度不会超过最大行高，也不会低于最小行高。如果原始高度超过最大值，needsTruncation会被标记为true，渲染层可以据此显示省略号或Tooltip。

需要特别注意一个边界：当availableWidth减去缩进后可能小于0，此时estimateLineCount中的charsPerLine会被Math.max限制为1，不会出现除零或负数问题。另一个边界是空任务名，函数直接返回1行，避免高度塌陷。

四、接入甘特图渲染与缓存优化

类型和计算函数就绪后，渲染层只需要在生成任务行时调用calculateTaskRowHeight。无论是用原生DOM、Canvas还是虚拟列表，都可以把返回的RowHeightResult作为行样式的一部分。例如在虚拟列表里，每一行的height不再来自固定配置，而是来自计算结果：

const tasks: TaskRowInput[] = getVisibleTasks();
const strategy: RowHeightStrategy = { kind: 'auto', minHeight: 32, maxHeight: 96, lineHeight: 18 };

const renderedRows = tasks.map(task => {
  const rowHeight = calculateTaskRowHeight(task, strategy);
  return {
    ...task,
    rowHeight: rowHeight.height,
    lineCount: rowHeight.lineCount,
    needsTruncation: rowHeight.needsTruncation,
  };
});

上面这段代码把计算结果合并到渲染数据中。对于大数据量甘特图，每次滚动或缩放都可能触发计算，如果每次都重新估算文本宽度和行数，性能会下降。此时可以引入缓存：用JSON.stringify或手动拼接输入字段作为缓存键，把结果存入Map。由于计算函数是纯函数，缓存不会产生副作用。

更优雅的方式是使用记忆化函数，例如通过一个简单的Map封装：

const rowHeightCache = new Map<string, RowHeightResult>();

function getCachedRowHeight(input: TaskRowInput, strategy: RowHeightStrategy): RowHeightResult {
  const key = `${input.taskName}|${input.fontSize}|${input.availableWidth}|${input.indentLevel}|${strategy.kind}`;
  const cached = rowHeightCache.get(key);
  if (cached) return cached;
  const result = calculateTaskRowHeight(input, strategy);
  rowHeightCache.set(key, result);
  return result;
}

缓存键需要覆盖所有会影响结果的字段，否则可能返回错误的高度。如果任务名称可能包含特殊字符，建议使用稳定序列化或哈希，避免键冲突。另外，当字体加载完成或容器宽度变化时，需要清除缓存并重新计算。

总结来说，用TypeScript定义支持甘特图任务行高自适应调整的数据类型，关键不在于某一个接口或函数，而在于把输入变量、计算策略和输出结果都纳入类型系统。这样行高逻辑就从散落在组件里的数字常量，变成可推导、可测试、可扩展的模块。

TypeScript甘特图行高自适应计算数据类型修改时间：2026-09-23 21:44:22