从 .js 文件创建 .d.ts 文件

使用 TypeScript 3.7，TypeScript 添加了对使用 JSDoc 语法从 JavaScript 生成 .d.ts 文件的支持。

¥With TypeScript 3.7, TypeScript added support for generating .d.ts files from JavaScript using JSDoc syntax.

这种设置意味着你可以拥有 TypeScript 驱动的编辑器的编辑器体验，而无需将项目移植到 TypeScript，也不必在代码库中维护 .d.ts 文件。TypeScript 支持大部分 JSDoc 标签，你可以找到 这里的参考。

¥This set up means you can own the editor experience of TypeScript-powered editors without porting your project to TypeScript, or having to maintain .d.ts files in your codebase. TypeScript supports most JSDoc tags, you can find the reference here.

设置你的项目以触发 .d.ts 文件

¥Setting up your Project to emit .d.ts files

要在你的项目中添加 .d.ts 文件的创建，你最多需要执行四个步骤：

¥To add creation of .d.ts files in your project, you will need to do up-to four steps:

• 将 TypeScript 添加到你的开发依赖

  ¥Add TypeScript to your dev dependencies

• 添加 tsconfig.json 以配置 TypeScript

  ¥Add a tsconfig.json to configure TypeScript

• 运行 TypeScript 编译器为 JS 文件生成对应的 d.ts 文件

  ¥Run the TypeScript compiler to generate the corresponding d.ts files for JS files

• （可选）编辑 package.json 以引用类型

  ¥(optional) Edit your package.json to reference the types

添加 TypeScript

¥Adding TypeScript

你可以在我们的 安装页面 中了解如何执行此操作。

¥You can learn how to do this in our installation page.

TSConfig

TSConfig 是一个 jsonc 文件，它配置你的编译器标志，并声明在哪里可以找到文件。在这种情况下，你需要如下文件：

¥The TSConfig is a jsonc file which configures both your compiler flags, and declare where to find files. In this case, you will want a file like the following:

{
  // Change this to match your project
  "include": ["src/**/*"],
  "compilerOptions": {
    // Tells TypeScript to read JS files, as
    // normally they are ignored as source files
    "allowJs": true,
    // Generate d.ts files
    "declaration": true,
    // This compiler run should
    // only output d.ts files
    "emitDeclarationOnly": true,
    // Types should go into this directory.
    // Removing this would place the .d.ts files
    // next to the .js files
    "outDir": "dist",
    // go to js file when using IDE functions like
    // "Go to Definition" in VSCode
    "declarationMap": true
  }
}

你可以在 tsconfig 参考 中了解有关选项的更多信息。使用 TSConfig 文件的替代方法是 CLI，这与 CLI 命令的行为相同。

¥You can learn more about the options in the tsconfig reference. An alternative to using a TSConfig file is the CLI, this is the same behavior as a CLI command.

sh
npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types

运行编译器

¥Run the compiler

你可以在我们的 安装页面 中了解如何执行此操作。如果你的项目的 .gitignore 中有这些文件，你需要确保这些文件包含在你的包中。

¥You can learn how to do this in our installation page. You want to make sure these files are included in your package if you have the files in your project’s .gitignore.

编辑 package.json

¥Editing the package.json

TypeScript 复制了 package.json 中模块的节点解析，并增加了一个查找 .d.ts 文件的步骤。粗略地说，解析会先检查可选的 types 字段，然后是 "main" 字段，最后会在根目录中尝试 index.d.ts。

¥TypeScript replicates the node resolution for modules in a package.json, with an additional step for finding .d.ts files. Roughly, the resolution will first check the optional types field, then the "main" field, and finally will try index.d.ts in the root.

Package.json	默认 .d.ts 的位置
没有 “types” 字段	检查 “main”，然后检查 index.d.ts
“types”：“main.d.ts”	main.d.ts
“types”：“./dist/main.js”	./dist/main.d.ts

如果不存在，则使用 “main”

¥If absent, then “main” is used

Package.json	默认 .d.ts 的位置
没有 “main” 字段	index.d.ts
“main”:“index.js”	index.d.ts
“main”:“./dist/index.js”	./dist/index.d.ts

提示

¥Tips

如果你想为 .d.ts 文件编写测试，请尝试 tsd。

¥If you’d like to write tests for your .d.ts files, try tsd.