0228. 注释指令
1. 🎯 本节内容
- TS 注释指令
2. 🫧 评价
在 TS 官方文档中,并没有专门介绍注释指令的章节,类似 @ts-ignore、@ts-expect-error、@ts-nocheck …… 这些注释指令的内容大多都分散在各个版本更新的说明文档中。比如:
- TypeScript 3.7 中提到了 // @ts-nocheck in TypeScript files
- TypeScript 3.9 中提到了 // @ts-expect-error Comments
- ……
这些指令大多跟 JS 项目迁移到 TS 版本相关,比如在迁移的过程中,临时关闭一些未迁移模块的类型检查,在迁移完成之后再开启严格的 TS 类型检查。
3. 🔍 章节速览
| 笔记 | 简介 |
|---|---|
| 0222.@ts-ignore | @ts-ignore 无条件忽略下一行类型错误,易掩盖问题;应仅作临时手段并附详尽注释,优先用更安全的 @ts-expect-error 替代。 |
| 0223.@ts-expect-error | @ts-expect-error 是 TypeScript 3.9 引入的注释指令,用于标记预期会出现类型错误的代码,比 @ts-ignore 更安全。 |
| 0291.@ts-ignore vs @ts-expect-error | @ts-expect-error 用于预期有错的场景(错则忽略,无错反报错),适合测试和临时兜底;@ts-ignore 用于无条件忽略错误(有错无错都沉默),风险更高,应慎用。 |
| 0224.@ts-nocheck | @ts-nocheck 是文件级别的类型检查跳过指令,用于完全禁用某个文件的 TypeScript 类型检查,需要位于文件顶部,常用于 JS->TS 项目迁移初期。 |
| 0225.@ts-check | TS 默认不检查 JS 模块,无需修改后缀 .js -> .ts 使用 @ts-check 就可以在特定 JS 模块中启用 TS 类型检查,而 checkJs: true 可以全局启用对 JS 模块的检查,效果相当于为所有 JS 文件自动添加 @ts-check。 |
| 0226.JSDoc 类型注释 | JSDoc 是 JS 的文档注释标准,TS 扩展了 JSDoc 以支持类型注释,让 JS 项目也能享受类型检查的好处。 |