TypeScript中如何定义支持甘特图任务非工作时间遮罩层的自定义颜色与透明度类型

在复杂的项目排期系统中，甘特图常常需要把周末、节假日等非工作时间用遮罩层标出。如果遮罩层的颜色和透明度只能在组件内部写死，一旦遇到深色主题或多项目共用一套组件的情况，就很难适配。利用TypeScript的静态类型能力，我们可以把遮罩层的自定义颜色与透明度抽象成明确的类型，让调用方在传入配置时就受到编译期检查。

为什么需要专门定义遮罩层类型

很多前端同学在封装甘特图时，习惯用any或者直接写一个宽泛的object来接收样式配置。这种做法在小型项目里看似省事，但当组件被多个业务线复用时，很容易出现传入非法颜色字符串或者透明度大于一的数值，导致渲染异常且很难排查。通过精确的类型定义，我们能把“合法的颜色格式”和“合法的透明度区间”固化下来。

另外，非工作时间遮罩层往往不是单一纯色，有的产品希望用带alpha通道的十六进制色，有的希望用rgba函数，有的还需要预设几种主题色。类型系统如果只支持string，就无法区分这些差异。我们用联合类型和字面量可以帮助IDE在书写时给出精准提示，也避免运行时再做大量兜底判断。

基础颜色与透明度类型设计

首先可以把颜色限定为几种常见格式：带透明度的十六进制（如#RRGGBBAA）、rgb或rgba字符串、以及预定义的主题色名称。透明度单独抽出来时，应限制为0到1之间的数字。下面是一组基础类型示例。

// 支持的颜色格式联合类型
type MaskColor =
  | string & { __brand: 'hexWithAlpha' } // 形如 #1e90ff80
  | `rgb(${number}, ${number}, ${number})`
  | `rgba(${number}, ${number}, ${number}, ${number})`
  | 'theme-gray'
  | 'theme-blue'
  | 'theme-warn';

// 透明度类型，使用模板字面量约束可读性较弱，这里用类型别名配合注释说明
type MaskOpacity = number; // 业务约定取值范围 0 - 1

// 更严格的透明度封装
type StrictOpacity = 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;

上面的MaskColor使用了模板字面量类型来约束rgb与rgba的写法，同时用品牌类型（brand）思路标注十六进制带透明度的场景。实际工程中，如果觉得品牌类型过于繁琐，也可以直接写成普通string并在文档中说明格式。StrictOpacity则用联合字面量把透明度变成可枚举的安全值，适合不需要任意精度的场景。

当我们需要同时描述颜色和透明度时，如果颜色本身已经带了alpha通道，再传opacity就会产生歧义。因此在类型层面最好明确二者是互斥或叠加的关系，这就要用到接下来的接口描述。

遮罩层配置的接口定义

把非工作时间遮罩层看作一个独立配置对象，可以用interface把颜色和透明度组合进去，并通过可选属性处理不同用法。下面给出一个完整的配置类型，既支持单独传颜色，也支持颜色加透明度叠加。

interface GanttOffTimeMask {
  // 遮罩层填充颜色，支持十六进制带透明度或函数式颜色
  color: MaskColor;
  // 当color不含alpha时，用opacity控制整体透明，范围0-1
  opacity?: MaskOpacity;
  // 是否对非工作时间区块使用斜纹背景
  hatch?: boolean;
  // 自定义主题名称，便于多主题切换
  theme?: 'light' | 'dark' | 'high-contrast';
}

// 使用示例
const maskConfig: GanttOffTimeMask = {
  color: 'rgba(30, 144, 255, 1)',
  opacity: 0.25,
  hatch: true,
  theme: 'light'
};

在这个接口里，opacity被标记为可选，因为某些颜色格式自身包含了透明度信息。调用方如果传了rgba且又写了opacity，组件内部可以约定以opacity为准或者忽略其一，这种规则在注释中写清即可。theme字段则展示了如何通过字面量联合类型限制主题，防止拼错单词。

如果项目里甘特图任务量很大，还可以把GanttOffTimeMask作为任务类型的一部分，或者作为全局配置。这样不同类型任务（如研发、测试）可以拥有各自的非工作时间遮罩表现，而类型系统保证所有配置都是合法的。

结合泛型增强复用性

当甘特图需要支持多种渲染引擎（如SVG、Canvas）时，遮罩层的配置可能略有差异。我们可以用泛型让基础类型适配不同渲染层，避免重复声明。下面的代码演示了如何把颜色与透明度类型参数化。

type BaseMask<TColor extends MaskColor> = {
  color: TColor;
  opacity?: StrictOpacity;
};

type SvgMask = BaseMask<`rgb(${number}, ${number}, ${number})`>;
type CanvasMask = BaseMask<string & { __brand: 'hexWithAlpha' }>;

const svgMask: SvgMask = {
  color: 'rgb(200, 200, 200)',
  opacity: 0.4
};

通过泛型约束，SVG遮罩只能使用rgb格式，而Canvas遮罩强制使用带透明度的十六进制，这样在底层绘制时就不必再做格式探测。虽然初期类型编写成本稍高，但在长期维护中能显著减少样式bug。

总体来看，TypeScript定义甘特图非工作时间遮罩层的自定义颜色与透明度类型，核心是把“颜色格式”和“数值区间”变成编译期契约。无论是简单联合类型还是配合接口的完整配置，都能让组件在复杂业务中保持健壮与易用。

TypeScript甘特图非工作时间遮罩层修改时间：2026-08-10 10:21:31