乐趣区

关于javascript:有JSDoc还需要TypeScript吗

这听起来是不是很耳熟:你想写一个小型脚本,不论是为页面、命令行工具,还是其余什么类型。你从 JavaScript 开始,直到你想起写代码时没有类型是如许苦楚。所以你把文件从 .js 重命名为.ts。而后意识到你曾经关上了一个麻烦的玩意儿。

如果你在为一个网站或一个库写代码,你就须要引入编译的步骤。如果你在编写 CLI 脚本,你能够求助于 Deno(它反对 TypeScript,开箱即用),然而你须要设置你的 IDE 来了解 Deno 的 API,而且混合和匹配 Deno 和 node 并不总是那么容易。

一旦你在本地实现了所有工作,你就须要思考如何散发你的代码。你会查看你编译的 .js 文件吗?你会创立一个 CI 管道来主动编译你的 .ts 文件吗?如果你在写一个库,你如何公布你的库,以便它能够被其余我的项目应用?

你实际上不须要 TypeScript

问题是 …… 你不须要为了取得动态类型剖析而编写 TypeScript!

你能够通过应用 JSDoc 在 JavaScript 中取得 TypeScript 的所有益处

TypeScript 所提供的是一个动态类型零碎。这意味着类型信息在运行代码中没有影响。当你的 TypeScript 被执行时,所有的类型信息都会齐全失落(这就是为什么你不写一个类型守卫,就不能测试一个变量是否是某个类型的起因)。

这也意味着 TypeScript 只是提供给 TypeScript 分析器的额定类型信息,对运行你代码的 JavaScript 引擎没有任何意义。当你把 TypeScript 编译成 JavaScript 时,它基本上只是从你的代码中删除了所有的类型信息,所以它又变成了无效的 JavaScript 代码。

JSDoc

在 JavaScript 诞生 25 年多后,JSDoc 作为一种正文 JavaScript 代码的形式被引入。它是一种正式的标记语言,容许 IDE 在开发者看到一个函数时提供额定的上下文。

相似的正文标记存在于大多数语言中,我置信你曾经晓得它了。这就是它的样子:

/**
 * This is the JSDOC block. IDEs will show this text when you hover the
 * printName function.
 *
 * @param {string} name
 */
function printName(name) {console.log(name)
}

TypeScript 和 JSDoc

较少人晓得的是,JSDoc 是你充沛应用 TypeScript 所须要的。TypeScript 分析器可能了解用 JSDoc 写的类型,并给你提供与 .ts 文件雷同的动态剖析。

我不会在这里提供残缺的语法文档。最重要的是你要晓得,简直所有你能在 .ts 文件中做的事件,你都能用 JSDoc 来做。但这里有几个例子:

带有原生类型的函数参数:

/**
 * @param {string} a
 * @param {number} b
 */
function foo(a, b) {}

应用 TypeScript 提供的开箱即用的类型:

/**
 * @param {HTMLElement} element
 * @param {Window} window
 */
function foo(element, window) {}

/** @type {number[]} */
let years

定义对象字面量和函数:

/** @type {{name: string; age: number}} */
let person

/** @type {(s: string, b: boolean) => void} */
let myCallback

*.d.ts 文件中导入类型:

/** @param {import('./types').User} user */
const deleteUser = (user) => {}

定义一个类型供当前应用:

/**
 * @typedef {object} Color
 * @property {number} chroma
 * @property {number} hue
 */

/** @type {Color[]} */
const colors = [{ chroma: 0.2, hue: 262},
  {chroma: 0.2, hue: 28.3},
]

参见官网 TypeScript JSDoc 文档以取得详尽的列表。

如果你有简单的类型,你依然能够编写你的 *.d.ts 文件并在你的 JSDoc 正文中导入它们。

留神,你依然须要为 typescript 设置你的我的项目(和 IDE),你须要创立一个 tsconfig.json 文件,将编译器选项 allowJscheckJs设置为true

// tsconfig.json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
    // ...
  }
}

什么时候写 TypeScript

尽管齐全应用 JSDoc 进行类型申明是可能的,但这并不是最不便的。TypeScript 的语法要好得多,而且不那么反复。

TypeScript 团队创立了一个 ” 作为正文的类型 ”ECMAScript 提案,容许你编写 TypeScript 并在不批改的状况下在 JavaScript 引擎中运行(JavaScript 引擎将把这些类型正文视为正文。)

然而在这个提案被承受之前,咱们只能决定应用 JSDoc 或者 TypeScript 工具链。

倡议

所以当初我的倡议是这样的:

  • 当你正在做一个有编译步骤的我的项目时,应用 TypeScript 没有什么害处
  • 然而如果你不须要编译步骤,那么保持应用 JSDoc 类型正文可能更容易。

以上就是本文的全部内容,如果对你有所帮忙,欢送点赞、珍藏、转发 \~

退出移动版