0Pricing
TypeScript Academy · 课时

在 JS 中使用 // @ts-check；通过 JSDoc 获取类型

使用 // @ts-check 和 JSDoc 在 .js 文件中启用类型检查；添加 @param/@returns、@type/@typedef 和 @template 以实现泛型模式；配置 tsconfig 逐步迁移。

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

简介

目标：在.js 文件中获得 TypeScript 的优势。您将启用 // @ts-check，添加JSDoc 类型，并配置 tsconfig 以逐步采用类型检查。

  • 逐文件检查与项目范围检查
  • @param、@returns、@type、@typedef
  • 使用 @template 编写类似泛型的辅助函数

启用检查

在 .js 文件顶部添加 // @ts-check。使用 @param/@returns 为函数添加说明和类型。

// calculator.js
// @ts-check

/**
 * Adds two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function add(a, b) {
  return a + b
}

// Usage: type errors appear if you pass non-numbers
// add("2", 3) // TS will flag this in JS

类型定义与类型标注

使用 @typedef 定义可复用的结构，使用 @type 为变量添加类型标注。可选字段使用 ? 标记。

// models.js
// @ts-check

/** @typedef {{ id: string; name: string; age?: number }} User */

/** @type {User} */
export const currentUser = { id: "u1", name: "Ada" }

/**
 * Greets a user.
 * @param {User} u
 * @returns {string}
 */
export function greet(u) {
  return `Hello, ${u.name}!`
}

模板参数

@template 为 JS 中类似泛型的函数引入类型参数。在调用位置可以进行推断。

// helpers.js
// @ts-check

/**
 * Maps items with a function, preserving types.
 * @template T,U
 * @param {T[]} items
 * @param {(x: T) => U} f
 * @returns {U[]}
 */
export function map(items, f) {
  const out = []
  for (const x of items) out.push(f(x))
  return out
}

// Inference: T=number, U=string
// map([1,2], n => n.toFixed(2))

JS 的 tsconfig 配置

项目范围检查：启用 checkJs 以检查所有 .js 文件。将 allowJs 设置为将 JS 文件纳入程序。由打包工具处理输出时，使用 noEmit。

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "checkJs": true,
    "allowJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["./**/*.js"],
  "exclude": ["node_modules"]
}

迁移提示

迁移提示：

  • 从使用 // @ts-check 的关键文件开始。
  • 为共享结构创建小型 @typedef。
  • 类型稳定后，逐步将热点路径重命名为 .ts。

ts-check 检查

快速检查：如何在 .js 文件中启用 TS 检查？

回顾

回顾：启用 // @ts-check，添加 @param/@returns/@typedef/@template，并在迁移到 .ts 之前收紧 JS 项目的 tsconfig 配置。

常见问题解答

「在 JS 中使用 // @ts-check；通过 JSDoc 获取类型」课时是免费的吗？

是的 — 「在 JS 中使用 // @ts-check；通过 JSDoc 获取类型」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 1 节课。

「在 JS 中使用 // @ts-check；通过 JSDoc 获取类型」这节课中我会学到什么？

使用 // @ts-check 和 JSDoc 在 .js 文件中启用类型检查；添加 @param/@returns、@type/@typedef 和 @template 以实现泛型模式；配置 tsconfig 逐步迁移。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

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

「在 JS 中使用 // @ts-check；通过 JSDoc 获取类型」课时需要多长时间？

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

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

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

← 返回 TypeScript Academy