拓冰网站定制 
文档教程【免费下载链接】typescript-bookThe Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.项目地址https://gitcode.com/gh_mirrors/typ/typescript-book点击查看免费下载导读字面量类型Literal Types是 TypeScript 类型系统中以值代型的核心机制它让开发者可以把某个具体值如字符串a、数字1、布尔值true当作类型来使用从而将运行时校验提前到编译期。本文以 The Concise TypeScript Book 的 literal-types.md 为骨架系统讲解三类字面量类型、字面量类型与联合类型/类型别名type alias的组合用法并延伸讲解字面量推断literal inference、字面量收窄narrowing、可辨识联合discriminated unions与穷尽性检查exhaustiveness checking帮助你在实际项目中用字面量类型写出更精确、更安全的 TypeScript 代码。一、什么是字面量类型字面量类型Literal Type是某个集合类型collective type中的单元素子集它定义了一个极其精确的值——该值必须是 JavaScript 的原始值primitive。换句话说普通的类型如string描述的是任意字符串这一类值的集合而字面量类型描述的是唯一的那个具体值。例如string是集合类型而字面量字符串a就是该集合中只包含a这一个元素的子集。在 TypeScript 中字面量类型只有三类分别对应 JavaScript 的三种原始值类别写法示例含义字符串字面量String Literal Typea只允许值a数值字面量Numeric Literal Type1只允许值1布尔字面量Boolean Literal Typetrue只允许值true基础示例const a a; // 字符串字面量类型 const b 1; // 数值字面量类型 const c true; // 布尔字面量类型这里有一个容易被忽略的细节const a a中a的类型并不是string而是字面量类型a。这是因为const声明的变量值不可再变TypeScript 会将其收窄为最精确的字面量类型这一机制正是下文要讲的字面量推断。二、字面量类型的三种用途联合、类型守卫与类型别名字符串、数值和布尔字面量类型在 TypeScript 中主要用于三处联合类型unions、类型守卫type guards与类型别名type aliases。最典型的用法是将字面量类型组合成联合类型别名union type alias把某个变量允许的取值限定为一个明确的枚举集合。以原文档中的示例为例type O a | b | c;这里的O是一个联合类型别名它只由指定的三个值组成——O类型的变量只允许被赋值为a、b或c任何其他字符串都不是合法取值会在编译期直接报错let o: O a; // ✅ 合法 o d; // ❌ Type d is not assignable to type O这种以字面量值构成联合的模式是 TypeScript 中最常用的领域建模手段它把业务上允许的取值状态、方向、动作等直接写进类型系统让编译器替你守住合法值边界。关于联合类型的基础语法使用|符号连接多个类型可参阅仓库中的 union-type.mdlet x: string | number; x hello; // 合法 x 123; // 合法三、字面量推断Literal Inference为什么 const 和 let 推断结果不同字面量类型与变量声明方式密切相关。字面量推断Literal Inference是 TypeScript 根据变量取值推断其字面量类型的能力但这一推断是否发生取决于该值将来能否被改变。const x x; // 推断为字面量类型 x因为这个值之后无法被修改 let y y; // 推断为 string因为我们可以修改这个值const x x值不可变TypeScript 给出最精确的类型——字面量类型xlet y y值可被重新赋值TypeScript 主动放宽为string。对象属性不会自动获得字面量类型字面量推断有一个常见陷阱对象的属性即使由const声明其类型也会被放宽为更宽的类型。如下例取自 literal-inference.mdtype X a | b; let o { x: a, // 这里被推断为更宽的 string }; const fn (x: X) ${x}-foo; console.log(fn(o.x)); // ❌ Argument of type string is not assignable to parameter of type X这段代码会报错虽然o.x的取值是a但 TypeScript 认为对象属性在将来可能被修改因此把o.x推断为string而fn的参数要求更窄narrower的类型X两者不兼容。两种修复方案方案一使用const断言as const把属性锁定为最精确的字面量类型let o { x: a as const, };方案二直接断言为目标联合类型Xlet o { x: a as X, };两种写法都能让o.x的类型变为a从而顺利传入fn(o.x)。as const的语义是把这个值当作不可变的字面量在配置对象、路由常量、状态映射等场景中非常实用。四、用类型守卫Type Guards收窄字面量字面量类型真正的威力体现在收窄narrowing当联合类型由多个字面量组成时TypeScript 会在条件分支内把变量的类型收窄到具体的字面量。相等性收窄与 switch在字面量联合上最常用的是相等性收窄equality narrowing通过、!、、!或switch语句判断变量是否等于某个具体字面量值从而收窄其类型。示例取自 narrowing.mdconst checkStatus (status: success | error) { switch (status) { case success: return true; case error: return null; } };在case success分支内status的类型被精确收窄为success在case error分支内收窄为error。这正是字面量联合 switch的经典组合也让穷尽性检查成为可能见第六节。自定义类型守卫type predicate当字面量联合需要由函数来判断时可以编写类型谓词type predicate形式的守卫函数返回类型写为value is T告诉编译器该函数返回true时参数应被当作类型T。示例取自 type-predicates.mdconst isString (value: unknown): value is string typeof value string; const foo (bar: unknown) { if (isString(bar)) { console.log(bar.toUpperCase()); } else { console.log(não é uma string); // 不是字符串 } };值得注意TypeScript 5.5 起会在filter这类回调中自动推断类型谓词如x is T从而知道像undefined这样的值已被过滤掉得到更精确的结果类型const nums [1, null, 2].filter(x x ! null); // nums 的类型被推断为 number[]而不是 (number | null)[]这一自动推断对清晰的检查如x ! undefined有效但对含糊的检查如!!x不会生效。五、可辨识联合Discriminated Unions字面量属性作为判别器当多个对象类型以字面量属性作为判别标志组成联合时就形成了可辨识联合Discriminated Unions这是字面量类型在结构化数据建模中最强大的应用。示例取自 discriminated-unions.mdtype Square { kind: square; // 判别属性discriminant size: number; }; type Circle { kind: circle; // 判别属性discriminant radius: number; }; type Shape Square | Circle; const area (shape: Shape) { switch (shape.kind) { case square: return Math.pow(shape.size, 2); case circle: return Math.PI * Math.pow(shape.radius, 2); } }; const square: Square { kind: square, size: 5 }; const circle: Circle { kind: circle, radius: 2 }; console.log(area(square)); // 25 console.log(area(circle)); // 12.566370614359172要点在于kind属性用字面量类型square/circle声明TypeScript 通过检查shape.kind即可在switch各分支中把shape收窄为对应的具体类型——在case square分支内shape就是Square可以放心访问shape.size。六、穷尽性检查Exhaustiveness Checking用 never 守住边界字面量联合 switch还催生了一项重要的安全机制穷尽性检查exhaustiveness checking——确保联合的所有可能取值都被switch/if分支处理。示例取自 exhaustiveness-checking.mdtype Direction up | down; const move (direction: Direction) { switch (direction) { case up: console.log(Movendo para cima); // 向上移动 break; case down: console.log(Movendo para baixo); // 向下移动 break; default: const exhaustiveCheck: never direction; console.log(exhaustiveCheck); // 此行永远不会执行 } };其原理是当所有合法分支都被case覆盖后default分支中direction的类型会被收窄为never把direction赋值给never类型变量是合法的。而一旦未来有人给Direction增加了第三个字面量值如left却忘记添加对应分支default中direction的类型就会变成left赋值给never便会触发编译错误从而在编译期提醒你补全新分支。同样的思想也出现在never类型的其他用法中例如在default分支抛出异常参见 never-type.mdtype Direction up | down; const move (direction: Direction): void { switch (direction) { case up: // 向上移动 break; case down: // 向下移动 break; default: const exhaustiveCheck: never direction; throw new Error(Direção não tratada: ${exhaustiveCheck}); // 未处理的方向 } };七、进阶模板字面量联合Template Union Types字面量类型的另一大进阶用法是模板字面量类型用反引号模板语法在类型层面拼接字符串字面量。当模板的占位符本身是联合类型时TypeScript 会自动做笛卡尔积展开生成全部组合的字符串字面量联合。示例取自 template-union-types.mdtype Status active | inactive; type Products p1 | p2; type ProductId id-${Products}-${Status}; // 展开结果: id-p1-active | id-p1-inactive | id-p2-active | id-p2-inactive这种模式非常适合生成约定式的 ID 格式、路由路径或消息前缀把字符串格式的合法性也纳入类型系统。八、小结与实战建议字面量类型虽然语法简单却是 TypeScript 精确类型建模的基石。回顾全文要点字面量类型是集合类型中的单元素子集仅包含string、number、boolean三类原始值字面量类型的核心用法是与|组合成联合类型别名把取值限定为明确枚举声明方式影响推断const推断为字面量类型let与对象属性会被放宽需要精确类型时用as const或显式断言见 literal-inference.md结合switch/等条件判断可实现字面量收窄配合自定义类型谓词能处理更复杂的判断逻辑见 narrowing.md、type-predicates.md用字面量属性作判别器可以构建可辨识联合让结构化数据的分支处理既安全又直观结合never做穷尽性检查能在联合类型新增取值时强制你补全所有分支见 exhaustiveness-checking.md、never-type.md模板字面量联合可自动展开字符串组合用于校验格式化的 ID 与路径。在实际项目中建议优先用字面量联合替代散落的魔法字符串如状态值active | inactive、方向up | down并把可辨识联合作为对象数据建模的首选方案这样不仅能获得编译期自动补全与错误提示还能在需求演进时第一时间发现遗漏的分支处理。以上全部示例与讲解均可在 The Concise TypeScript Book 仓库的website/src/content/docs/pt-br/book/目录英文原版对应website/src/content/docs/book/中查阅原文配合源码逐一验证。赞分享文档教程【免费下载链接】typescript-bookThe Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.项目地址https://gitcode.com/gh_mirrors/typ/typescript-book点击查看免费下载相关推荐TypeScript 字面量类型Literal Types完全指南精确值与联合类型的基石TypeScript 字面量类型Literal Types完全指南精确值与联合类型的基石 导读 字面量类型Literal Type是 TypeScri文档教程TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合 字面量类型Literal Types是 Type教程TypeScript 字面量类型Literal Types精读从单元素集合到联合类型实战TypeScript 字面量类型Literal Types精读从单元素集合到联合类型实战 本文基于开源仓库 typ/typescript bookThe文档教程上一篇gh_mirrors/paip-lisp中的Actor-Critic算法策略与价值结合下一篇pyllama安全与最佳实践确保AI模型稳定运行的10个关键要点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TypeScript 字面量类型（Literal Types）完全指南：从精确值约束到联合类型实战
文档教程【免费下载链接】typescript-bookThe Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.项目地址https://gitcode.com/gh_mirrors/typ/typescript-book点击查看免费下载导读字面量类型Literal Types是 TypeScript 类型系统中以值代型的核心机制它让开发者可以把某个具体值如字符串a、数字1、布尔值true当作类型来使用从而将运行时校验提前到编译期。本文以 The Concise TypeScript Book 的 literal-types.md 为骨架系统讲解三类字面量类型、字面量类型与联合类型/类型别名type alias的组合用法并延伸讲解字面量推断literal inference、字面量收窄narrowing、可辨识联合discriminated unions与穷尽性检查exhaustiveness checking帮助你在实际项目中用字面量类型写出更精确、更安全的 TypeScript 代码。一、什么是字面量类型字面量类型Literal Type是某个集合类型collective type中的单元素子集它定义了一个极其精确的值——该值必须是 JavaScript 的原始值primitive。换句话说普通的类型如string描述的是任意字符串这一类值的集合而字面量类型描述的是唯一的那个具体值。例如string是集合类型而字面量字符串a就是该集合中只包含a这一个元素的子集。在 TypeScript 中字面量类型只有三类分别对应 JavaScript 的三种原始值类别写法示例含义字符串字面量String Literal Typea只允许值a数值字面量Numeric Literal Type1只允许值1布尔字面量Boolean Literal Typetrue只允许值true基础示例const a a; // 字符串字面量类型 const b 1; // 数值字面量类型 const c true; // 布尔字面量类型这里有一个容易被忽略的细节const a a中a的类型并不是string而是字面量类型a。这是因为const声明的变量值不可再变TypeScript 会将其收窄为最精确的字面量类型这一机制正是下文要讲的字面量推断。二、字面量类型的三种用途联合、类型守卫与类型别名字符串、数值和布尔字面量类型在 TypeScript 中主要用于三处联合类型unions、类型守卫type guards与类型别名type aliases。最典型的用法是将字面量类型组合成联合类型别名union type alias把某个变量允许的取值限定为一个明确的枚举集合。以原文档中的示例为例type O a | b | c;这里的O是一个联合类型别名它只由指定的三个值组成——O类型的变量只允许被赋值为a、b或c任何其他字符串都不是合法取值会在编译期直接报错let o: O a; // ✅ 合法 o d; // ❌ Type d is not assignable to type O这种以字面量值构成联合的模式是 TypeScript 中最常用的领域建模手段它把业务上允许的取值状态、方向、动作等直接写进类型系统让编译器替你守住合法值边界。关于联合类型的基础语法使用|符号连接多个类型可参阅仓库中的 union-type.mdlet x: string | number; x hello; // 合法 x 123; // 合法三、字面量推断Literal Inference为什么 const 和 let 推断结果不同字面量类型与变量声明方式密切相关。字面量推断Literal Inference是 TypeScript 根据变量取值推断其字面量类型的能力但这一推断是否发生取决于该值将来能否被改变。const x x; // 推断为字面量类型 x因为这个值之后无法被修改 let y y; // 推断为 string因为我们可以修改这个值const x x值不可变TypeScript 给出最精确的类型——字面量类型xlet y y值可被重新赋值TypeScript 主动放宽为string。对象属性不会自动获得字面量类型字面量推断有一个常见陷阱对象的属性即使由const声明其类型也会被放宽为更宽的类型。如下例取自 literal-inference.mdtype X a | b; let o { x: a, // 这里被推断为更宽的 string }; const fn (x: X) ${x}-foo; console.log(fn(o.x)); // ❌ Argument of type string is not assignable to parameter of type X这段代码会报错虽然o.x的取值是a但 TypeScript 认为对象属性在将来可能被修改因此把o.x推断为string而fn的参数要求更窄narrower的类型X两者不兼容。两种修复方案方案一使用const断言as const把属性锁定为最精确的字面量类型let o { x: a as const, };方案二直接断言为目标联合类型Xlet o { x: a as X, };两种写法都能让o.x的类型变为a从而顺利传入fn(o.x)。as const的语义是把这个值当作不可变的字面量在配置对象、路由常量、状态映射等场景中非常实用。四、用类型守卫Type Guards收窄字面量字面量类型真正的威力体现在收窄narrowing当联合类型由多个字面量组成时TypeScript 会在条件分支内把变量的类型收窄到具体的字面量。相等性收窄与 switch在字面量联合上最常用的是相等性收窄equality narrowing通过、!、、!或switch语句判断变量是否等于某个具体字面量值从而收窄其类型。示例取自 narrowing.mdconst checkStatus (status: success | error) { switch (status) { case success: return true; case error: return null; } };在case success分支内status的类型被精确收窄为success在case error分支内收窄为error。这正是字面量联合 switch的经典组合也让穷尽性检查成为可能见第六节。自定义类型守卫type predicate当字面量联合需要由函数来判断时可以编写类型谓词type predicate形式的守卫函数返回类型写为value is T告诉编译器该函数返回true时参数应被当作类型T。示例取自 type-predicates.mdconst isString (value: unknown): value is string typeof value string; const foo (bar: unknown) { if (isString(bar)) { console.log(bar.toUpperCase()); } else { console.log(não é uma string); // 不是字符串 } };值得注意TypeScript 5.5 起会在filter这类回调中自动推断类型谓词如x is T从而知道像undefined这样的值已被过滤掉得到更精确的结果类型const nums [1, null, 2].filter(x x ! null); // nums 的类型被推断为 number[]而不是 (number | null)[]这一自动推断对清晰的检查如x ! undefined有效但对含糊的检查如!!x不会生效。五、可辨识联合Discriminated Unions字面量属性作为判别器当多个对象类型以字面量属性作为判别标志组成联合时就形成了可辨识联合Discriminated Unions这是字面量类型在结构化数据建模中最强大的应用。示例取自 discriminated-unions.mdtype Square { kind: square; // 判别属性discriminant size: number; }; type Circle { kind: circle; // 判别属性discriminant radius: number; }; type Shape Square | Circle; const area (shape: Shape) { switch (shape.kind) { case square: return Math.pow(shape.size, 2); case circle: return Math.PI * Math.pow(shape.radius, 2); } }; const square: Square { kind: square, size: 5 }; const circle: Circle { kind: circle, radius: 2 }; console.log(area(square)); // 25 console.log(area(circle)); // 12.566370614359172要点在于kind属性用字面量类型square/circle声明TypeScript 通过检查shape.kind即可在switch各分支中把shape收窄为对应的具体类型——在case square分支内shape就是Square可以放心访问shape.size。六、穷尽性检查Exhaustiveness Checking用 never 守住边界字面量联合 switch还催生了一项重要的安全机制穷尽性检查exhaustiveness checking——确保联合的所有可能取值都被switch/if分支处理。示例取自 exhaustiveness-checking.mdtype Direction up | down; const move (direction: Direction) { switch (direction) { case up: console.log(Movendo para cima); // 向上移动 break; case down: console.log(Movendo para baixo); // 向下移动 break; default: const exhaustiveCheck: never direction; console.log(exhaustiveCheck); // 此行永远不会执行 } };其原理是当所有合法分支都被case覆盖后default分支中direction的类型会被收窄为never把direction赋值给never类型变量是合法的。而一旦未来有人给Direction增加了第三个字面量值如left却忘记添加对应分支default中direction的类型就会变成left赋值给never便会触发编译错误从而在编译期提醒你补全新分支。同样的思想也出现在never类型的其他用法中例如在default分支抛出异常参见 never-type.mdtype Direction up | down; const move (direction: Direction): void { switch (direction) { case up: // 向上移动 break; case down: // 向下移动 break; default: const exhaustiveCheck: never direction; throw new Error(Direção não tratada: ${exhaustiveCheck}); // 未处理的方向 } };七、进阶模板字面量联合Template Union Types字面量类型的另一大进阶用法是模板字面量类型用反引号模板语法在类型层面拼接字符串字面量。当模板的占位符本身是联合类型时TypeScript 会自动做笛卡尔积展开生成全部组合的字符串字面量联合。示例取自 template-union-types.mdtype Status active | inactive; type Products p1 | p2; type ProductId id-${Products}-${Status}; // 展开结果: id-p1-active | id-p1-inactive | id-p2-active | id-p2-inactive这种模式非常适合生成约定式的 ID 格式、路由路径或消息前缀把字符串格式的合法性也纳入类型系统。八、小结与实战建议字面量类型虽然语法简单却是 TypeScript 精确类型建模的基石。回顾全文要点字面量类型是集合类型中的单元素子集仅包含string、number、boolean三类原始值字面量类型的核心用法是与|组合成联合类型别名把取值限定为明确枚举声明方式影响推断const推断为字面量类型let与对象属性会被放宽需要精确类型时用as const或显式断言见 literal-inference.md结合switch/等条件判断可实现字面量收窄配合自定义类型谓词能处理更复杂的判断逻辑见 narrowing.md、type-predicates.md用字面量属性作判别器可以构建可辨识联合让结构化数据的分支处理既安全又直观结合never做穷尽性检查能在联合类型新增取值时强制你补全所有分支见 exhaustiveness-checking.md、never-type.md模板字面量联合可自动展开字符串组合用于校验格式化的 ID 与路径。在实际项目中建议优先用字面量联合替代散落的魔法字符串如状态值active | inactive、方向up | down并把可辨识联合作为对象数据建模的首选方案这样不仅能获得编译期自动补全与错误提示还能在需求演进时第一时间发现遗漏的分支处理。以上全部示例与讲解均可在 The Concise TypeScript Book 仓库的website/src/content/docs/pt-br/book/目录英文原版对应website/src/content/docs/book/中查阅原文配合源码逐一验证。赞分享文档教程【免费下载链接】typescript-bookThe Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.项目地址https://gitcode.com/gh_mirrors/typ/typescript-book点击查看免费下载相关推荐TypeScript 字面量类型Literal Types完全指南精确值与联合类型的基石TypeScript 字面量类型Literal Types完全指南精确值与联合类型的基石 导读 字面量类型Literal Type是 TypeScri文档教程TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合 字面量类型Literal Types是 Type教程TypeScript 字面量类型Literal Types精读从单元素集合到联合类型实战TypeScript 字面量类型Literal Types精读从单元素集合到联合类型实战 本文基于开源仓库 typ/typescript bookThe文档教程上一篇gh_mirrors/paip-lisp中的Actor-Critic算法策略与价值结合下一篇pyllama安全与最佳实践确保AI模型稳定运行的10个关键要点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考