TypeScript Academy · 课时

JSDoc 类型注解：过渡方案

Q: 「JSDoc 类型注解：过渡方案」这节课中我会学到什么？

在转换之前使用 JSDoc 为 JS 文件添加类型 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在转换之前使用 JSDoc 为 JS 文件添加类型

JSDoc 类型注解：过渡方案 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

将 JSDoc 作为 TypeScript 桥梁

启用 checkJs: true 后，TypeScript 可以读取 JavaScript 文件中的 JSDoc 类型注释。这样无需重命名文件，就能为 JS 添加类型。

/** @type {string} */
let name = "Alice"; // TypeScript checks this as string

@param 和 @returns

使用 JSDoc 标签为函数参数和返回类型添加注释。

/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
function greet(name, age) {
  return `${name} is ${age}`;
}

使用 @typedef 定义对象类型

使用 @typedef 在 JSDoc 中定义可复用的类型别名。

/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {boolean} isActive
 */

/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };

使用 @template 定义泛型

使用 @template 在 JSDoc 中编写泛型函数。

/**
 * @template T
 * @param {T[]} arr
 * @returns {T | undefined}
 */
function first(arr) {
  return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefined

从 .ts 文件导入类型

JSDoc 支持使用 @type {import("./types").User} 将 TypeScript 类型导入 JS 文件。

/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };

使用 @ts-check 进行按文件检查

在 JS 文件顶部添加 // @ts-check，即可仅为该文件启用 TypeScript 检查，而无需在全局启用 checkJs: true。

// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number

@ts-ignore 和 @ts-expect-error

使用内联指令抑制特定的 JSDoc 类型错误，而不必禁用整个文件的检查。

// @ts-ignore
const x = badFunction(); // single error suppressed

// @ts-expect-error
const y = anotherBad(); // error expected here

JSDoc 枚举

使用 @enum 在 JSDoc 中模拟 TypeScript 枚举。

/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };

JSDoc 中的类型断言

使用 /** @type {SomeType} */ (expression) 进行 JSDoc 类型断言，其效果等同于 TypeScript 中的 as SomeType。

const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typed

何时迁移到 .ts

JSDoc 注释是桥梁，而不是终点。当文件中的类型注释已经完整且稳定后，请将其重命名为 .ts，并使用原生 TypeScript 语法替代 JSDoc 类型注释。

// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)

回顾：将 JSDoc 作为桥梁

JSDoc 类型注释可以在不重命名文件的情况下启用 JS 文件的 TypeScript 检查。使用 @type、@param、@typedef 和 @template，在转换为原生 TypeScript 之前逐步提升类型安全性。

快速检查

哪个 JSDoc 标签可以在单个文件中启用 TypeScript 检查，而无需全局启用 checkJs？

您学到的内容

JSDoc 类型注释是连接 JavaScript 和 TypeScript 的桥梁：使用 @type、@param、@typedef 和 @template 为 JS 文件添加类型。使用 // @ts-check 启用按文件检查，准备就绪后再转换为原生 TypeScript。

常见问题解答

「JSDoc 类型注解：过渡方案」课时是免费的吗？

是的 — 「JSDoc 类型注解：过渡方案」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「JSDoc 类型注解：过渡方案」这节课中我会学到什么？

在转换之前使用 JSDoc 为 JS 文件添加类型你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「JSDoc 类型注解：过渡方案」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy