TNotes.typescript

Appearance

0225. @ts-check

0225. @ts-check ​

1. 🎯 本节内容 ​

  • @ts-check 注释的基本用法
  • 在 JS 文件中启用类型检查
  • 与 JSDoc 的配合使用

2. 🫧 评价 ​

@ts-check 允许在 JS 文件中启用 TS 类型检查，无需将文件改为 .ts 扩展名。

  • 适合在 JS 项目中逐步引入类型检查
  • 位置和 @ts-nocheck 一样，必须位于文件顶部才能生效
  • JS 项目可以配合 JSDoc 注释提供类型信息
  • 将项目从 JS 迁移到 TS 初期常用，比直接迁移到 TS 风险更低，更好地完成渐进式迁移

3. 💻 demos.1 - 体验 @ts-check 的作用 ​

@ts-check 在 JS 文件中启用 TS 类型检查。

js
// 使用 TypeScript 的 JavaScript 项目

// 若果你加上 @ts-check 注释，那么将会开启 TS 类型检查
// @ts-check

// 在 JS 文件中，类型通常可以被自动推断。
// 当无法推断类型时，可使用 JSDoc 语法进行显式声明。

/**
 * 可以通过 JSDoc 在 JavaScript 中实现渐进式类型
 * @type {number}
 */
var foo
// 上述写法相当于 TypeScript 中的: let foo: number

var bar
// 上述写法相当于 TypeScript 中的: let bar: any

foo = 0 // ✅ OK
foo = false // ❌ Error 不能将类型“boolean”分配给类型“number”。ts(2322)

bar = 0 // ✅ OK
bar = 'string' // ✅ OK
js
// @ts-check

// ✅ 基本类型推断
let count = 0
count = 'hello' // ❌ 报错

在 1.js 中，我们可以使用 JSDoc 语法来声明一个未初始化的变量的类型，在开启 @ts-check 检查之后，TS 能够解析出变量 foo 的类型是 number，由于 bar 没有使用 JSDoc 来声明其类型，并且也没有赋初始值，因此默认会被推断为 any 类型。

在 2.js 中，当我们开启 @ts-check 检查之后，let count = 0 会根据变量 count 的初始值 0 自动完成类型推断，相当于let count: number = 0。

1 有 @ts-check
1 无 @ts-check
2 有 @ts-check
2 无 @ts-check

4. 🤔 @ts-check 如何与 tsconfig.json 配合使用？ ​

常见有两种模式：

  1. 单个 JS 文件启用检查，JS 文件默认不启用检查，需要检查的 JS 模块手动添加 @ts-check 注释
  2. 全局 JS 文件启用检查，JS 文件默认启用检查，需要关闭检查的 JS 模块手动添加 @ts-nocheck 注释

4.1. 单个 JS 文件启用检查 ​

json
{
  "compilerOptions": {
    "allowJs": true, // 允许编译 JS 文件
    "checkJs": false, // 全局不检查 JS 文件
    "noEmit": true // 不生成输出文件
  },
  "include": ["src//*"]
}
js
// src/utils.js
// @ts-check

function multiply(a, b) {
  return a * b
}
js
// 下面这个文件不会被检查（没有 @ts-check）
// src/helpers.js
function divide(a, b) {
  return a / b // 不会报错
}

4.2. 全局 JS 文件启用检查 ​

json
{
  "compilerOptions": {
    "checkJs": true // 全局检查所有 JS 文件
  }
}
js
// legacy-code.js
// 这时候如果想要让某个文件关闭检查，需要结合 @ts-nocheck 注释命令。
// @ts-nocheck

function oldFunction() {
  // 不进行类型检查
}
js
// new-code.js
// 自动检查（因为 checkJs: true）

function newFunction(x) {
  return x * 2
}

5. 🤔 checkJs 配置的作用是？ ​

  • 当启用 checkJs 时，JS 文件中的错误将被报告。
  • 这相当于在所有项目包含的 JS 文件顶部添加 // @ts-check 。

6. 🔗 引用 ​

Discussions