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

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

这种设置意味着你可以拥有由 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 添加到你的开发依赖
• 添加一个 tsconfig.json 来配置 TypeScript
• 运行 TypeScript 编译器为 JS 文件生成对应的 d.ts 文件
• (可选) 编辑你的 package.json 以引用类型

添加 TypeScript

🌐 Adding TypeScript

你可以在我们的安装页面上学习如何操作。

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

TS配置

🌐 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位置
无“主”字段	index.d.ts
“主”：index.js“	index.d.ts
“main”：./dist/index.js“	./dist/index.d.ts

提示

🌐 Tips

如果你想为你的 .d.ts 文件编写测试，可以尝试 tsd 或 TSTyche。

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