TypeScript中如何定义支持甘特图任务条形图文本标签的旋转角度与锚点类型

甘特图是项目管理和排期系统中常见的可视化组件，任务条（Task Bar）上通常需要渲染文本标签来展示任务名称、负责人或进度信息。当任务条宽度有限而文字较长时，就需要支持标签的旋转（例如竖排 90 度或斜排 45 度）以及锚点位置的灵活配置。如果这些配置只用松散的 any 类型或普通对象来承载，很容易在运行时出现角度越界、锚点拼写错误等问题。本文将围绕 TypeScript 的类型系统，完整讲解如何定义一套既灵活又类型安全的标签样式配置。

一、为什么标签配置需要强类型约束

在实际的甘特图组件开发中，标签配置往往由使用者传入，例如一个 labelOptions 对象。如果没有类型约束，开发者可能会把旋转角度写成字符串 "90deg"，或者把锚点写成 center 与 middle 混用，这些问题在编译期无法暴露，只会在渲染阶段才被发现，排查成本很高。

用 TypeScript 定义这些配置的第一个好处是获得智能提示。使用者在 IDE 中输入锚点类型时，编辑器会自动列出所有合法选项；第二个好处是可以在类型层面做联合约束，例如限定旋转角度必须在 -180 到 180 之间（配合运行时校验），避免出现无意义的超界角度导致文字倒置错乱。

此外，强类型的配置对象还有一个隐性优势：当组件升级、新增锚点选项或废弃某些角度值时，类型定义的变更会直接体现在编译错误中，使用者可以第一时间感知并修改代码，这比依靠文档同步可靠得多。

二、旋转角度的类型定义与校验

旋转角度看起来只是一个数字，但在类型层面有多种定义方式，各有优劣。最直接的方式是用 number，但它无法表达取值范围的语义；更推荐的做法是结合字面量联合类型和工具函数运行时校验。

首先定义一个基础的角度类型，既支持任意数字角度，也支持几个常用的预设值：

// 预设的常用旋转角度
export type PresetAngle = 0 | 90 | -90 | 45 | -45;

// 任意角度，限定在 -360 到 360 之间由运行时校验兜底
export type CustomAngle = number;

// 甘特图标签旋转角度
export type LabelAngle = PresetAngle | CustomAngle;</code>

接着编写一个类型保护函数，在运行时验证角度是否合法，同时利用 is 谓词让 TypeScript 在分支中自动收窄类型：

export function isValidAngle(angle: unknown): angle is LabelAngle {
  if (typeof angle !== 'number' || Number.isNaN(angle)) {
    return false;
  }
  // 限定角度范围，避免出现无意义的超大角度
  return angle >= -360 && angle <= 360;
}

// 使用示例
const configAngle = 90;
if (isValidAngle(configAngle)) {
  console.log('角度合法，可以用于渲染');
}

还有一种进阶做法是使用品牌类型（Branded Type），把角度范围的信息编码进类型本身，使得即使两个都是 number 的值也不能随意混用：

declare const AngleBrand: unique symbol;

export type ValidatedAngle = number & {
  readonly [AngleBrand]: 'validated';
};

export function createAngle(value: number): ValidatedAngle {
  if (value < -360 || value > 360) {
    throw new RangeError(`角度 ${value} 超出允许范围`);
  }
  return value as ValidatedAngle;
}

这种写法的好处是，组件内部接受渲染的函数签名可以要求 ValidatedAngle，普通数字必须先经过 createAngle 校验，从源头上杜绝非法角度进入渲染流程。当然，对于一般业务场景，字面量联合加运行时校验已经足够，品牌类型更适合对安全性要求较高的通用图表库。

三、锚点类型的枚举建模与组合

锚点决定文本相对于任务条的位置。水平方向上有起点、中点、终点三种选择，垂直方向同理，二者组合出九种锚点位置。在 TypeScript 中，推荐用字符串字面量联合类型或 const 断言数组来定义，而不是传统的 enum，因为前者更容易与 JSON 序列化配置兼容。

// 水平锚点
export type HorizontalAnchor = 'start' | 'middle' | 'end';

// 垂直锚点
export type VerticalAnchor = 'top' | 'center' | 'bottom';

// 组合后的完整锚点类型
export type LabelAnchor = `${VerticalAnchor}-${HorizontalAnchor}`;

// TypeScript 会自动推导出九种合法组合：
// 'top-start' | 'top-middle' | 'top-end'
// 'center-start' | 'center-middle' | 'center-end'
// 'bottom-start' | 'bottom-middle' | 'bottom-end'

const anchor: LabelAnchor = 'top-start'; // 合法
// const bad: LabelAnchor = 'top-left';  // 编译错误

这里用到了模板字面量类型（Template Literal Types），这是 TypeScript 4.1 之后提供的强大能力，它让锚点的九种组合自动展开，使用者拼错任何一个单词都会得到明确的编译错误提示，无需手动维护九个枚举成员。

如果需要兼容旧版本 TypeScript，也可以退而求其次，直接列出所有组合：

export type LabelAnchor =
  | 'top-start' | 'top-middle' | 'top-end'
  | 'center-start' | 'center-middle' | 'center-end'
  | 'bottom-start' | 'bottom-middle' | 'bottom-end';

在渲染层面，不同锚点对应不同的对齐方式。以 SVG 渲染为例，水平锚点映射到 text-anchor 属性，垂直锚点映射到 dominant-baseline 属性。可以在类型定义旁边附上一份映射表，保证类型与渲染逻辑的一致性：

const anchorRenderMap: Record<LabelAnchor, {
  textAnchor: string;
  dominantBaseline: string;
}> = {
  'top-start': { textAnchor: 'start', dominantBaseline: 'hanging' },
  'top-middle': { textAnchor: 'middle', dominantBaseline: 'hanging' },
  'top-end': { textAnchor: 'end', dominantBaseline: 'hanging' },
  'center-start': { textAnchor: 'start', dominantBaseline: 'central' },
  'center-middle': { textAnchor: 'middle', dominantBaseline: 'central' },
  'center-end': { textAnchor: 'end', dominantBaseline: 'central' },
  'bottom-start': { textAnchor: 'start', dominantBaseline: 'auto' },
  'bottom-middle': { textAnchor: 'middle', dominantBaseline: 'auto' },
  'bottom-end': { textAnchor: 'end', dominantBaseline: 'auto' },
};

使用 Record<LabelAnchor, ...> 作为映射表的类型有一个额外好处：如果未来新增锚点组合而忘记补充映射，TypeScript 会在编译时立刻报错，这正是穷举检查的价值所在。

四、完整的标签配置接口与实战使用

把角度和锚点整合起来，再补充字体、颜色、偏移量等常用属性，就形成一份完整的甘特图标签配置接口：

export interface GanttLabelOptions {
  /** 是否显示标签 */
  visible: boolean;
  /** 标签内容格式化函数 */
  formatter?: (task: GanttTask) => string;
  /** 旋转角度，默认 0 */
  rotate?: LabelAngle;
  /** 锚点位置，默认 'center-middle' */
  anchor?: LabelAnchor;
  /** 相对锚点的水平偏移像素值 */
  offsetX?: number;
  /** 相对锚点的垂直偏移像素值 */
  offsetY?: number;
  /** 字号 */
  fontSize?: number;
  /** 文字颜色 */
  color?: string;
  /** 标签超出任务条边界时是否自动旋转 */
  autoRotateOverflow?: boolean;
}

export interface GanttTask {
  id: string;
  name: string;
  startDate: Date;
  endDate: Date;
  progress: number;
}

在组件中使用时，配合 Partial 工具类型可以让所有配置变为可选，并提供一份默认值对象做合并：

const DEFAULT_LABEL_OPTIONS: Required<GanttLabelOptions> = {
  visible: true,
  rotate: 0,
  anchor: 'center-middle',
  offsetX: 0,
  offsetY: 0,
  fontSize: 12,
  color: '#333333',
  autoRotateOverflow: true,
  formatter: (task) => task.name,
};

export function resolveLabelOptions(
  userOptions?: Partial<GanttLabelOptions>
): Required<GanttLabelOptions> {
  return { ...DEFAULT_LABEL_OPTIONS, ...userOptions };
}

// 调用示例
const options = resolveLabelOptions({
  rotate: -90,
  anchor: 'bottom-start',
  formatter: (task) => `${task.name} (${task.progress}%)`,
});

注意默认值对象的类型标注为 Required<GanttLabelOptions>，这会强制开发者补全每一个属性，避免默认配置不完整导致渲染时出现 undefined。这种技巧在图表库开发中非常实用，是保证配置完整性的最后一道防线。

最后再补充一个渲染环节的小细节：当标签旋转 -90 或 90 度时，文字会竖向排布，此时垂直锚点与水平锚点的语义实际上是互换的，渲染函数中需要根据角度做坐标变换，例如在 SVG 中通过 transform="rotate(-90, x, y)" 实现。这部分属于运行时逻辑，但配合前面定义的类型，可以让变换函数的入参签名严格限定为 ValidatedAngle 与 LabelAnchor，整个链路都保持类型安全。

总结来说，甘特图文本标签的旋转角度与锚点配置，通过字面量联合类型、模板字面量类型、类型保护函数和 Record 映射表这几种手段的组合，可以在 TypeScript 中建立起完整的类型防线，让配置错误在编译期就被发现，同时为使用者提供良好的开发体验。

TypeScript甘特图文本标签修改时间：2026-09-02 11:52:59