幻影类型(Phantom Type)
一句话解释
幻影类型是未使用的类型参数,添加编译时区分而无运行时开销。
用大白话说
幻影类型是永远不出现在实际数据中的泛型类型参数——它仅存在于类型级以创建区分。例如,type Meter<T> = number——T 不出现在值中(始终是数字),但不同的 T 值创建不同类型:Meter<"distance"> vs Meter<"time">。这让你在类型级用元数据标记值:
- 状态机(Idle vs Running 状态)
- 单位(米 vs 秒)
- 能力(已授权 vs 未授权)
- 计算阶段无运行时开销——幻影参数被擦除。纯粹是编译时安全机制。
示例
typescript
// Phantom type — T is never used in the value
type Tagged<T extends string> = { readonly _tag: T; value: number };
type Meters = Tagged<"distance">;
type Seconds = Tagged<"time">;
function speed(d: Meters, t: Seconds): number {
return d.value / t.value;
}
const dist: Meters = { _tag: "distance", value: 100 };
const time: Seconds = { _tag: "time", value: 10 };
console.log(speed(dist, time)); // 10
// speed(time, dist); // Error! Wrong typesMeters 和 Seconds 运行时都是 { value: number },但 _tag 幻影在编译时区分它们。不能在 speed() 中交换。
常见混淆
容易混淆的对象: 品牌类型
关键区别: 品牌类型向值添加幻影属性(与 { __brand: 'X' } 交集)。幻影类型使用根本不出现在值中的类型参数。两者都创建编译时区分;品牌类型用属性,幻影类型用未使用的类型参数。
相关术语
相关资源
相关课程
- TypeScript 模式
幻影类型。
解读错误信息
用大白话解释常见错误——什么意思、为什么发生、如何修复。