文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载本篇指南以仓库 zh/handbook/literal-types.md 为骨架展开系统讲解 TypeScript 的字面量类型字符串、数字、布尔三种集合、字面量收窄机制以及它们与联合类型、类型守卫、函数重载结合后的实战用法并结合仓库内 联合类型和交叉类型、枚举、模版字面量类型 等姊妹章节让你掌握从约束单一值到构建可区分联合做穷尽性检查的完整技能。什么是字面量类型一个字面量literal是一个集体类型中更为具体的一种子类型。意思是Hello World是一个string但一个string并不是类型系统中的Hello World。// Hello World 这个具体值属于 string 类型 // 但 string 类型涵盖了无穷多个可能的值并不等于 Hello World目前 TypeScript 中有三种可用的字面量类型集合分别是字面量类型集合示例含义字符串字面量类型ease-in只允许这一个具体的字符串数字字面量类型8、16只允许这一个具体的数字布尔字面量类型true、false只允许这一个具体的布尔值通过使用字面量类型你可以规定一个字符串、数字或布尔值必须含有的确定值。这比笼统地写string/number/boolean更精确是 TypeScript 类型系统收窄narrowing能力的基础。字面量收窄Literal Narrowing当你通过var或let来声明一个变量时实际上你在告诉编译器这个变量中的内容有可能会被改变。与之相对地用const来声明对象会让 TypeScript 知道这个对象永远不会被改变。// 我们通过 const 保证这个变量 helloWorld 永远不会改变 // 所以 TypeScript 将它的类型设置为 Hello World 而不是 string。 const helloWorld Hello World; // 另一方面let 声明的变量可以改变 // 因此编译器将其类型推断为更宽泛的 string。 let hiWorld Hi World;这段代码背后是 TypeScript 的类型推断规则const声明的变量不可重新赋值类型系统可以安全地采用最具体的字面量类型即Hello Worldlet声明的变量随时可能被重新赋值为其他字符串因此只能退而求其次采用其公共超类型string。从无穷多种可能的取值string变量的值有无穷多种到一个更小、确定数量的取值集合上例中Hello World的可能值只有一种的过程就叫收窄narrowing。字面量收窄是后续所有字面量类型应用的前提正是因为有具体值可以被当作类型这一机制ease-in | ease-out这类联合类型才能成立。补充阅读关于let与var的取舍以及const的更多细节可参考仓库 基础类型 中关于let一节。字符串字面量类型字面量类型可以通过联合类型union、类型守卫type guard、类型别名type alias来结合实际字符串值。通过这些特性我们可以让一个字符串表现得像枚举enum一样只接受一组预先约定的取值。用联合约束参数取值type Easing ease-in | ease-out | ease-in-out; class UIElement { animate(dx: number, dy: number, easing: Easing) { if (easing ease-in) { // ... } else if (easing ease-out) { // ... } else if (easing ease-in-out) { // ... } else { // 如果有人无视类型约束仍有可能走到这里。 } } } let button new UIElement(); button.animate(0, 0, ease-in); button.animate(0, 0, uneasy); // Error: Argument of type uneasy is not assignable to parameter of type Easing.你可以传递三种允许的字符串但如果传递其他字符串编译器会在编译期报错Argument of type uneasy is not assignable to parameter of type ease-in | ease-out | ease-in-out错误信息中会完整列出所有允许的取值这既是约束也是一种自我文档化——调用者一看便知该参数支持哪些合法值。用字符串字面量实现函数重载字符串字面量还可以用来为同一个函数按不同参数值分别声明重载overloadfunction createElement(tagName: img): HTMLImageElement; function createElement(tagName: input): HTMLInputElement; // ... 更多重载 ... function createElement(tagName: string): Element { // ... 实现代码 ... }当调用createElement(img)时编译器匹配到第一个重载签名返回值类型为HTMLImageElement调用createElement(input)时匹配第二个返回HTMLInputElement。字符串字面量在此处充当了编译期路由让同一函数在不同实参下返回不同类型的精确结果。重载的完整机制可进一步参考仓库 函数 一章。字符串字面量联合 vs. 枚举原文档指出字面量联合可以使字符串有类似枚举enum的行为。两者对比如下维度字符串字面量联合字符串枚举运行时产物无纯编译期类型会生成真实对象取值约束ease-in \| ease-outDirection.Up等成员适用场景简单、固定的几组取值需要序列化、反向映射或成员名语义正如仓库 枚举 所述字符串枚举每个成员必须用字符串字面量或另一个字符串枚举成员初始化且运行时存在有意义的值、便于调试而字面量联合类型是无运行时开销的纯类型方案适合不需要对象语义的场景。数字字面量类型TypeScript 还有数字字面量类型它的行为和字符串字面量类型相同只允许特定的数字取值。function rollDice(): 1 | 2 | 3 | 4 | 5 | 6 { return (Math.floor(Math.random() * 6) 1) as 1 | 2 | 3 | 4 | 5 | 6; } const result rollDice();这里的返回值类型1 | 2 | 3 | 4 | 5 | 6精确描述了骰子所有可能的点数。需要注意Math.random()返回类型是number与1 | 2 | 3 | ...不兼容因此原文档使用as断言类型断言来明确告知编译器我确定这个值落在合法范围内关于as断言以及 JSX 中只能使用as语法的说明可参考仓库 基础类型 的类型断言一节这种写法隐含了result一定落在六个取值之内这一约束后续对result做switch或比较时类型系统会利用这一点进行穷尽性检查。数字字面量描述配置值数字字面量类型经常用来描述配置值——比number更精确地声明只允许这些档位interface MapConfig { lng: number; lat: number; tileSize: 8 | 16 | 32; } setupMap({ lng: -73.935242, lat: 40.73061, tileSize: 16 });这里tileSize只能取8、16、32三个值。如果传入24编译器会直接报错从而在编译期拦截非法配置而不是等运行时地图渲染出错。这在配置驱动型应用地图切片、图片缩放档位、日志级别等中非常实用。布尔字面量类型TypeScript 还有布尔值字面量类型。你可以用它来约束某些属性之间互有关联的对象——这正是可区分联合discriminated union的雏形interface ValidationSuccess { isValid: true; reason: null; }; interface ValidationFailure { isValid: false; reason: string; }; type ValidationResult | ValidationSuccess | ValidationFailure;在这个模型中ValidationSuccess明确声明isValid: true而非boolean同时reason为nullValidationFailure声明isValid: falsereason为stringValidationResult是两者的联合。当拿到一个ValidationResult值时只要判断isValid的真假TypeScript 就能收窄出当前到底是成功还是失败分支——若是成功分支reason一定为null若是失败分支reason一定是string。这样对象内部各属性之间的一致性如校验通过时不该有失败原因在类型层面被强制保证运行时根本不会出现isValid 为 true 却还带着错误信息的矛盾状态。进阶实战从字面量到可区分联合与穷尽性检查字面量类型最大的价值在于与联合类型组合后构建可区分联合再配合switch实现穷尽性检查。仓库 联合类型和交叉类型 给出了完整示例type NetworkLoadingState { state: loading }; type NetworkFailedState { state: failed; code: number }; type NetworkSuccessState { state: success; response: { title: string; duration: number; summary: string }; }; type NetworkState | NetworkLoadingState | NetworkFailedState | NetworkSuccessState; function logger(state: NetworkState): string { // 在收窄之前不能访问非公共属性如 state.code——编译器会报错。 // 通过 switch 判别 state 字段其类型是字符串字面量 // TypeScript 在代码流分析中逐步缩小联合范围 switch (state.state) { case loading: return Downloading...; case failed: // 此时类型必为 NetworkFailedState访问 code 是安全的。 return Error ${state.code} downloading; case success: return Downloaded ${state.response.title} - ${state.response.summary}; } }要点解析每个分支类型共享一个判别字段state其值分别是loading、failed、success这样的字符串字面量类型在switch (state.state)中把state与这些字面量比较时TypeScript 会精确推断出当前分支的具体类型如NetworkFailedState从而允许安全访问code、response等非公共属性这正是布尔字面量类型一节中属性之间互有关联的对象约束的泛化版。穷尽性检查never与assertNever如果后续给NetworkState增加了新分支例如state: from_cache而logger的switch没有覆盖会出现什么有两种主流做法方式一配合strictNullChecks指定返回类型function logger(s: NetworkState): string { switch (s.state) { case loading: return loading request; case failed: return failed with code ${s.code}; case success: return got response; // 缺少 from_cache 分支时函数可能返回 undefined // 与声明的 string 返回类型冲突编译器报错。 } }因为switch不再穷尽TypeScript 会推断函数有时返回undefined与显式返回类型string冲突而报错。此方法比较微妙且strictNullChecks不一定对旧代码生效。方式二用never类型做显式穷尽检查function assertNever(x: never): never { throw new Error(Unexpected object: x); } function logger(s: NetworkState): string { switch (s.state) { case loading: return loading request; case failed: return failed with code ${s.code}; case success: return got response; default: // 所有合法分支都被移除后剩余类型应为 never // 若忘了处理某个分支s 会是真实类型这里就会报错。 return assertNever(s); } }assertNever检查s是否属于never类型即所有其他情况都被移除后剩下的类型。如果忘记某个分支s将保有一个实际类型从而产生类型错误并且错误信息中包含丢失的类型名称非常直观。再进一步模板字面量类型字符串字面量类型还衍生出了更强大的模板字面量类型Template Literal Types仓库 模版字面量类型 指出它以字符串字面量类型为基础且可以展开为多个字符串类型的联合类型从 TypeScript 4.1 开始支持type World world; type Greeting hello ${World}; // hello world type EmailLocaleIDs welcome_email | email_heading; type FooterLocaleIDs footer_title | footer_sendoff; type AllLocaleIDs ${EmailLocaleIDs | FooterLocaleIDs}_id; // welcome_email_id | email_heading_id | footer_title_id | footer_sendoff_id当替换位置是联合类型时结果类型是各成员组合出的字符串字面量集合多个替换位置还会交叉相乘。模板字面量类型常用于基于属性名派生事件名如firstNameChanged等场景是字面量类型体系的重要延伸感兴趣可继续阅读该章节。小结与学习路径字面量类型是 TypeScript 类型系统的核心基石本文覆盖了收窄const产生最具体的字面量类型let/var退化为宽泛类型三类字面量字符串、数字、布尔字面量类型的定义与典型应用参数约束、函数重载、配置值、判别对象组合威力字面量联合 可区分联合 switchnever实现编译期穷尽性检查延伸方向模板字面量类型在字符串字面量基础上的进一步扩展。本仓库对应的官方手册章节按以下顺序递进建议按序研读以获得完整体系基础类型let/const、类型断言、null/undefined等前置知识字面量类型本文所依据的原始文档联合类型和交叉类型可区分联合与穷尽性检查的完整实现枚举对比字符串字面量联合与枚举的取舍模版字面量类型字符串字面量类型的进阶形态。赞分享文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载相关推荐TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合TypeScript 字面量类型Literal Types实战指南精确值约束、字符串枚举与可辨识联合 字面量类型Literal Types是 Type教程TypeScript 字面量类型Literal Types完全指南从单元素集合到联合、收窄与实战TypeScript 字面量类型Literal Types完全指南从单元素集合到联合、收窄与实战 本文以《The Concise TypeScript B文档教程TypeScript 字面量类型Literal Types完全指南从精确值约束到联合类型实战TypeScript 字面量类型Literal Types完全指南从精确值约束到联合类型实战 导读 字面量类型Literal Types是 Type文档教程上一篇英雄联盟本地化工具箱League Akari 终极指南5倍提升游戏效率下一篇DamaiHelper抢票助手告别手动抢票的全能解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考