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

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

此设置意味着您可以在不将项目移植到 TypeScript 或在代码库中维护 .d.ts 文件的情况下拥有 TypeScript 支持的编辑器的编辑器体验。TypeScript 支持大多数 JSDoc 标签，您可以找到 参考这里。

设置项目以生成 .d.ts 文件

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

• 将 TypeScript 添加到您的开发依赖项中
• 添加一个 tsconfig.json 来配置 TypeScript
• 运行 TypeScript 编译器以生成 JS 文件对应的 d.ts 文件
• (可选) 编辑您的 package.json 以引用类型

添加 TypeScript

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

TSConfig

TSConfig 是一个 jsonc 文件，它配置您的编译器标志，并声明在哪里查找文件。在这种情况下，您需要一个类似于以下内容的文件

{
  // 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 命令具有相同的行为。

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

运行编译器

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

编辑 package.json

TypeScript 复制了 package.json 中模块的节点解析，并在查找 .d.ts 文件时添加了一个额外的步骤。大致来说，解析将首先检查可选的 types 字段，然后检查 "main" 字段，最后将尝试在根目录中查找 index.d.ts。

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”

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

提示

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