使用 TypeScript 的 JS 项目

使用代码库时，TypeScript 中的类型系统具有不同级别的严格性：

¥The type system in TypeScript has different levels of strictness when working with a codebase:

  • 仅基于 JavaScript 代码推断的类型系统

    ¥A type-system based only on inference with JavaScript code

  • JavaScript 中的增量输入 通过 JSDoc

    ¥Incremental typing in JavaScript via JSDoc

  • 在 JavaScript 文件中使用 // @ts-check

    ¥Using // @ts-check in a JavaScript file

  • TypeScript 代码

    ¥TypeScript code

  • 启用 strict 的 TypeScript

    ¥TypeScript with strict enabled

每一步都代表朝着更安全的类型系统迈进，但并非每个项目都需要那种级别的验证。

¥Each step represents a move towards a safer type-system, but not every project needs that level of verification.

使用 JavaScript 的 TypeScript

¥TypeScript with JavaScript

这是当你使用使用 TypeScript 的编辑器来提供自动补齐、跳转到符号和重构工具（如重命名）等工具时。homepage 有一个带有 TypeScript 插件的编辑器列表。

¥This is when you use an editor which uses TypeScript to provide tooling like auto-complete, jump to symbol and refactoring tools like rename. The homepage has a list of editors which have TypeScript plugins.

通过 JSDoc 在 JS 中提供类型提示

¥Providing Type Hints in JS via JSDoc

在 .js 文件中，通常可以推断出类型。当无法推断类型时，可以使用 JSDoc 语法指定它们。

¥In a .js file, types can often be inferred. When types can’t be inferred, they can be specified using JSDoc syntax.

JSDoc 注释出现在声明之前，用于设置该声明的类型。例如：

¥JSDoc annotations come before a declaration will be used to set the type of that declaration. For example:

js
/** @type {number} */
var x;
 
x = 0; // OK
x = false; // OK?!
Try

你可以找到受支持的 JSDoc 模式的完整列表 在 JSDoc 支持的类型中。

¥You can find the full list of supported JSDoc patterns in JSDoc Supported Types.

@ts-check

上一个代码示例的最后一行会在 TypeScript 中引发错误，但在 JS 项目中默认情况下不会。要启用 JavaScript 文件中的错误，请添加：// @ts-check 到你的 .js 文件的第一行，让 TypeScript 将其作为错误引发。

¥The last line of the previous code sample would raise an error in TypeScript, but it doesn’t by default in a JS project. To enable errors in your JavaScript files add: // @ts-check to the first line in your .js files to have TypeScript raise it as an error.

js
// @ts-check
/** @type {number} */
var x;
 
x = 0; // OK
x = false; // Not OK
Type 'boolean' is not assignable to type 'number'.2322Type 'boolean' is not assignable to type 'number'.Try

如果你有很多 JavaScript 文件要添加错误，那么你可以切换到使用 jsconfig.json。你可以通过向文件添加 // @ts-nocheck 注释来跳过检查某些文件。

¥If you have a lot of JavaScript files you want to add errors to then you can switch to using a jsconfig.json. You can skip checking some files by adding a // @ts-nocheck comment to files.

TypeScript 可能会提供你不同意的错误，在这些情况下，你可以通过在前一行添加 // @ts-ignore 或 // @ts-expect-error 来忽略特定行的错误。

¥TypeScript may offer you errors which you disagree with, in those cases you can ignore errors on specific lines by adding // @ts-ignore or // @ts-expect-error on the preceding line.

js
// @ts-check
/** @type {number} */
var x;
 
x = 0; // OK
// @ts-expect-error
x = false; // Not OK
Try

要了解有关 TypeScript 如何解释 JavaScript 的更多信息，请阅读 TS 类型如何检查 JS

¥To learn more about how JavaScript is interpreted by TypeScript read How TS Type Checks JS