12k
All articles

值得学习的冷门 TypeScript 特性

了解七个鲜为人知的TypeScript功能,从const类型参数和NoInfer到断言函数与verbatimModuleSyntax,并附版本信息和代码示例。

OpenReplay Team
OpenReplay Team
值得学习的冷门 TypeScript 特性

有七个 TypeScript 特性,许多资深开发者至今仍未用上:const 类型参数(5.0)、NoInfer(5.4)、断言函数(3.7)、带标签的元组元素(4.0)、型变注解(4.7)、accessor 关键字(4.9),以及 import type 与 verbatimModuleSyntax 的搭配使用(3.8 与 5.0)。

如果你是在 4.x 前后学会 TypeScript 的,之后一直忙于交付项目,那么你很可能仍在调用处手写 as const,或者为了防止类型推断被拓宽而额外添加类型参数。新版本为这两件事都提供了更简洁的写法。

本文逐一介绍这些特性:它的作用、引入它的版本,并附上一个能在严格模式下编译通过的简短示例。

要点速览

  • 当约束为只读类型(如 readonly string[])时,const 类型参数(TypeScript 5.0)会将 ["/", "/users"] 推断为 readonly ["/", "/users"]。
  • NoInfer<T>(TypeScript 5.4)可以阻止某个参数成为推断来源,因此默认值不会拓宽由其他参数确定的类型。
  • 以 asserts value is T 形式编写的断言函数,会在调用之后的整个作用域内收窄其参数类型,而不仅限于 if 代码块内部。
  • 在 verbatimModuleSyntax 下,只有当 type 作用于整条导入语句时,该导入才会被移除。import { type X } from "./mod" 会输出 import {} from "./mod",因此该模块仍会被执行。

按版本划分的 TypeScript 高级特性

下表列出了这七个冷门 TypeScript 特性、引入它们的版本,以及最需要关注它们的开发者群体。

特性引入版本主要受众
断言函数3.7应用与库代码
import type3.8构建配置
带标签的元组元素4.0Hook 与 API 作者
型变注解(in/out)4.7库作者
accessor 关键字4.9装饰器使用者
const 类型参数5.0泛型 API 作者
verbatimModuleSyntax5.0构建配置
NoInfer<T>5.4泛型 API 作者

const 类型参数(TypeScript 5.0)

TypeScript 5.0 新增了类型参数上的 const 修饰符。它让编译器在推断数组和对象字面量时,表现得就像调用方写了 as const 一样。调用方不再需要记得添加断言,就能获得字面量类型。

如果希望得到只读结果,应将 const 修饰符与只读约束搭配使用。若使用 string[] 这类可变约束,TypeScript 5.0 至 5.2 会回退为 string[];从 5.3 起,编译器则会推断为可变元组。此外,const 修饰符只对直接写在调用中的字面量生效,事先声明的变量会保留其已被拓宽的类型。

function defineRoutes<T extends readonly string[]>(paths: T): T { return paths; }
const a = defineRoutes(["/", "/users"]);        // string[]

function defineRoutesExact<const T extends readonly string[]>(paths: T): T { return paths; }
const b = defineRoutesExact(["/", "/users"]);   // readonly ["/", "/users"]

function defineRoutesMutable<const T extends string[]>(paths: T): T { return paths; }
const c = defineRoutesMutable(["/", "/users"]); // ["/", "/users"] (TS 5.3+; string[] in 5.0–5.2)

用 NoInfer 控制类型推断(TypeScript 5.4)

TypeScript 5.4 新增的 NoInfer<T> 可以阻止编译器将某个参数用作推断来源。该参数随后会根据从其他参数推断出的类型进行检查,而不会反过来拓宽该类型。在 5.4 之前,常见的变通做法是再添加一个受第一个类型参数约束的类型参数。这种做法虽然可行,但会引入一个在签名中只出现一次的多余类型参数。

function createSelect<T extends string>(options: T[], initial: NoInfer<T>) {
  return { options, value: initial };
}

createSelect(["draft", "published"], "draft");    // OK
createSelect(["draft", "published"], "archived");
// Error: Argument of type '"archived"' is not assignable
// to parameter of type '"draft" | "published"'.

如果没有 NoInfer,T 会被拓宽为 "draft" | "published" | "archived",这个拼写错误也就能顺利通过编译。工具类型参考文档将它与 Partial、Pick 一同收录。

断言函数(TypeScript 3.7)

断言函数一旦正常返回(未抛出异常),就会在所在作用域的后续代码中收窄其参数类型。这使它非常适合编写无需分支的快速失败(fail-fast)守卫语句。类型守卫(value is T)只会在调用它的条件语句内部收窄类型;而 TypeScript 3.7 引入的 asserts value is T 签名则会收窄调用之后的所有代码。

function assertIsDefined<T>(value: T, name = "value"): asserts value is NonNullable<T> {
  if (value === undefined || value === null) {
    throw new Error(`${name} is not defined`);
  }
}

const root = document.getElementById("app"); // HTMLElement | null
assertIsDefined(root, "#app");
root.classList.add("ready");                 // root: HTMLElement

断言函数有一个坑:如果把辅助函数写成箭头函数并赋值给一个未加类型注解的 const,调用处就会报错:“Assertions require every name in the call target to be declared with an explicit type annotation.”。解决办法是改用函数声明,或者为该 const 显式标注类型。

带标签的元组元素(TypeScript 4.0)

TypeScript 4.0 新增的带标签元组元素允许你为元组类型中的每个位置命名。这些名称会显示在编辑器的悬停提示、签名帮助和错误信息中。元组标签只影响编辑器和错误信息的显示内容,并不改变元组本身的类型,调用方在解构时也可以使用任意名称。从 TypeScript 5.2 起,元组还可以混合使用带标签和不带标签的元素。

Hook 风格的返回类型是其典型用例:

type ToggleState = [isOn: boolean, toggle: () => void];

function useToggle(initial = false): ToggleState {
  let isOn = initial;
  return [isOn, () => { isOn = !isOn; }];
}

const [open, toggleOpen] = useToggle(); // any names work; labels show in hovers

型变注解:in 与 out(TypeScript 4.7)

TypeScript 4.7 引入的型变注解允许你显式声明一个类型参数是协变(out)、逆变(in),还是两者兼具(不变)。型变注解主要面向库作者,应用代码几乎用不到。4.7 的发布说明将其定位为一种表明设计意图的手段,对于深度递归的类型,还能加快类型检查速度。当注解与参数的实际用法相矛盾时,TypeScript 会报错;但如果注解比实际需要更严格,TypeScript 也会接受。

interface Producer<out T> { get: () => T }
interface Consumer<in T> { accept: (value: T) => void }

interface Bad<in T> { get: () => T }
// Error: Type 'Bad<super-T>' is not assignable to type 'Bad<sub-T>'
// as implied by variance annotation.

accessor 关键字(TypeScript 4.9)

TypeScript 4.9 新增了自动访问器(auto-accessor)。它的声明方式与类字段相同,只需加上 accessor 前缀。编译器会将其转换为一对 getter 和 setter,背后由一个无法从外部访问的私有字段支撑。因此,自动访问器为装饰器提供了一个统一的位置,可以同时拦截对该字段的读取和写入。

下面的示例使用了 TypeScript 5.0 的标准装饰器签名,类型来自编译器内置的 decorators.d.ts。该示例要求关闭 experimentalDecorators,因为旧版装饰器使用的是另一套签名。

function logged<This, V>(
  target: ClassAccessorDecoratorTarget<This, V>,
  context: ClassAccessorDecoratorContext<This, V>
): ClassAccessorDecoratorResult<This, V> {
  return {
    set(value) {
      console.log(`set ${String(context.name)} =`, value);
      target.set.call(this, value);
    },
  };
}

class Settings {
  @logged accessor theme = "light";
}

import type 与 verbatimModuleSyntax(TypeScript 3.8 与 5.0)

在 verbatimModuleSyntax 下,只有当 type 作用于整条语句时,TypeScript 才会删除该导入;其他所有导入都会原样输出。import type 语法最早出现于 TypeScript 3.8,而该编译选项本身则是在 5.0 中引入的,用于取代 importsNotUsedAsValues 和 preserveValueImports。这两个选项在 5.0 中被标记为弃用,在 TypeScript 7 中已不复存在。

{ "compilerOptions": { "verbatimModuleSyntax": true } }
import type { User } from "./api";         // erased entirely
import { fetchUser, type Post } from "./api"; // emits: import { fetchUser } from "./api";
import { type Config } from "./config";    // emits: import {} from "./config";

第三行 import { type Config } 最容易让人踩坑。内联的 type 修饰符仍会留下一条空导入,因此该模块依然会被加载,其副作用也会执行。开启该选项后,任何未加 type 修饰符导入的类型都会导致编译错误。迁移工作主要就是把仅含类型的具名导入改写为 import type。

相关的 TypeScript 进阶主题

以下几个主题有意未在本文中涉及,因为它们各有专文介绍:

总结

这些特性大多要么取代了某种变通写法,要么把原本依赖运行时约定的检查转移到了类型系统中。const 类型参数和 NoInfer 让泛型 API 能够获得精确的类型推断,而无需调用方做额外工作。断言函数和带标签的元组让日常应用代码更加严谨,verbatimModuleSyntax 则让输出的导入语句变得可预测。一个务实的起步方式是:先在某一个包中启用 verbatimModuleSyntax,修复编译器标出的仅类型导入,然后为所有当前要求调用方追加 as const 的泛型加上 const 修饰符。

常见问题

verbatimModuleSyntax 能在输出 CommonJS 的项目中使用吗?

可以,但输出为 CommonJS 的文件必须使用 TypeScript 的 CommonJS 风格语法:导入使用 import fs = require('fs'),导出使用 export =。在这类文件中编写 ESM 的 import 或 export 语句会导致编译错误。当前版本会将其报告为 TS1295,并建议修改 package.json 中的 type 字段或调整 module 相关设置。输出为 ESM 的文件则可以继续使用常规的 import 和 export 语法。

启用 verbatimModuleSyntax 后,还需要 isolatedModules 吗?

不需要。根据 TSConfig 参考文档,只要启用了 verbatimModuleSyntax,isolatedModules 默认就会被设为 true,因此其单文件转译检查会自动生效,你可以删掉显式配置项。这些检查对 esbuild、SWC 和 Babel 等工具十分重要,因为它们会逐个文件独立编译,无法判断导入的名称是类型还是值。

断言函数可以是异步的吗?

不可以。TypeScript 没有异步断言签名,因此 Promise<asserts value is T> 这样的返回类型是无效的。该特性已在 TypeScript issue 37681 中被提出,但尚未成为语言的一部分。常见的变通做法是先 await 异步操作,再对结果调用同步断言函数;或者让异步函数返回经过校验、类型已收窄的值。

Open-source session replay

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.