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

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

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

设置项目以输出 .d.ts 文件

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

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

添加 TypeScript

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

TSConfig

TSConfig 是一个 jsonc 文件，用于配置你的编译器标志，并声明在哪里查找文件。 在这种情况下，你需要一个像下面这样的文件：

{
  // 将其更改为匹配你的项目
  "include": ["src/**/*"],

  "compilerOptions": {
    // 告诉 TypeScript 读取 JS 文件，因为
    // 通常它们作为源文件被忽略
    "allowJs": true,
    // 生成 d.ts 文件
    "declaration": true,
    // 此编译器运行应
    // 仅输出 d.ts 文件
    "emitDeclarationOnly": true,
    // 类型应放入此目录。
    // 删除此选项会将 .d.ts 文件放在
    // .js 文件旁边
    "outDir": "dist",
    // 当使用 IDE 功能（如
    // VSCode 中的“转到定义”）时转到 js 文件
    "declarationMap": true
  }
}

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

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

运行编译器

你可以在我们的安装页面上学习如何操作。 如果这些文件在你的项目的 .gitignore 中，你需要确保它们被包含在你的包中。

编辑 package.json

TypeScript 复制了 package.json 中模块的 Node 解析，并增加了查找 .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 或 TSTyche。