TypeScript 声明文件使用指南：下载、安装与查找 @types 包

文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载导读在 TypeScript 工程中为 JavaScript 库如 lodash、moment补全类型信息最直接的途径就是安装其对应的声明文件。本文以 zh/declaration-files/consumption.md 为核心系统讲解声明文件的下载、使用与查找三个环节并结合本仓库中declaration-files系列文档介绍、发布、库结构与 tsconfig.json 配置 的源码级细节说明types包如何被 TypeScript 自动识别与解析。读完本文你将掌握装什么包、怎么导入、去哪找、配什么编译选项的完整闭环。一、先理解声明文件是什么声明文件.d.ts文件的作用是为已有的 JavaScript 代码提供类型描述。它不包含任何可运行的实现只告诉 TypeScript 编译器某个库暴露了哪些函数、类、属性以及它们的类型形状。正如 声明文件介绍 所述需要编写.d.ts文件的常见场景就是为某个 npm 包添加类型信息。对库的使用者来说则不需要自己动手写声明文件只需要找到并安装现成的声明包即可——这正是本文要讲的主题而如何编写并发布声明文件属于编写指南的范畴。二、下载一条 npm 命令拿到类型想要获取声明文件只需要用到 npm。例如为 lodash 库安装类型声明npm install --save types/lodash这条命令会从 npm 的typesscope 下下载lodash的类型声明包并写入node_modules/types/lodash。安装后无需任何额外配置TypeScript 即可识别 lodash 的类型。什么时候不需要安装types包有一个重要前提如果一个 npm 包自身已经捆绑了声明文件那就不必再去下载对应的types包了。判断方法如下查看包的package.json中是否声明了types或typings字段指向其主声明文件或者主声明文件名恰好是index.d.ts且位于包根目录与index.js并列。发布章节 给出了捆绑声明的标准示例{ name: awesome, author: Vandelay Industries, version: 1.0.0, main: ./lib/main.js, types: ./lib/main.d.ts }注意typings与types具有相同的意义都可以使用。TypeScript 本身就是一个自带声明文件的例子——它把.d.ts放进了自己的 npm 包里因此使用者不需要依赖额外的types/typescript。三、使用模块导入与全局变量两种姿势下载完成后就可以直接在 TypeScript 里使用 lodash 了不论是在模块里还是全局代码里。方式一模块中使用推荐在模块系统中使用import导入import * as _ from lodash; _.padStart(Hello TypeScript!, 20, );import * as _ from lodash会把 lodash 的全部导出绑定到_上_.padStart的签名参数、返回类型会由types/lodash提供完整的类型检查与智能提示。方式二全局使用无模块加载器环境如果你没有使用模块那么只需直接使用全局变量__.padStart(Hello TypeScript!, 20, );这种方式适用于在浏览器中以script标签加载库、且未启用模块加载器的场景。之所以能直接用是因为很多流行库如 lodash、moment以UMD 格式发布它既能在 Node.js / RequireJS 里作为模块被import/require也能在没有模块加载器时向全局作用域暴露变量。可参考 库结构章节 中关于 UMD 的判断方法如果库代码顶端出现typeof define、typeof window、typeof module这类检测大概率就是 UMD 库对应声明文件会通过export as namespace同时支持两种用法。以 module.d.ts 模板 为例模板开头就有这样一行export as namespace myLib;export as namespace正是该模块在非模块环境下暴露全局变量的声明写法——当你安装的types/lodash内部含有类似结构时全局使用才能成立。四、查找types 的命名规律与检索途径大多数情况下类型声明包的名字总是与其在 npm 上的包的名字相同但带有types/前缀。也就是说lodash→types/lodashexpress→types/expressmoment→types/moment如果你想确认某个库的声明包是否存在可以在 aka.ms/types 上检索该地址是微软提供的 types 搜索入口会重定向到相应的查询页面。提示如果你要找的声明文件不存在你可以贡献一份这样就方便了下一位开发者。贡献方式是把声明文件提交到 DefinitelyTyped 社区仓库它会通过 types-publisher 工具自动发布为types包。详见 DefinitelyTyped 的贡献指南页面。五、原理深化TypeScript 如何看见 types 包安装好types/lodash后为什么无需配置就能生效这背后是 tsconfig 的自动包含机制见 tsconfig.json 配置 中的types、typeRoots和types一节默认所有可见的types包会在编译过程中被包含进来。node_modules/types文件夹下以及它们子文件夹下的所有包都是可见的也就是说./node_modules/types/、../node_modules/types/、../../node_modules/types/等等逐级向上的目录都会被搜索。这意味着即使你从未在代码中importlodash只要node_modules/types/lodash存在_对应的全局声明也能被解析。这也解释了为什么全局使用场景下仅仅安装声明包就能获得类型。两个重要的编译选项当你对自动包含的范围不满意时可以用两个选项精确控制typeRoots如果指定了typeRoots只有typeRoots下面的包才会被包含进来。例如{ compilerOptions: { typeRoots: [./typings] } }这个配置会包含所有./typings下面的包而不包含./node_modules/types里面的包。types只列出你想引入的types包。例如{ compilerOptions: { types: [node, lodash, express] } }该配置将仅包含./node_modules/types/node、./node_modules/types/lodash和./node_modules/types/expressnode_modules/types/*中的其它包不会被引入。指定types: []可以禁用自动引入types包。需要注意自动引入只在你使用全局声明而非模块导入时是重要的。如果你使用import foo语句TypeScript 仍然会查找node_modules和node_modules/types文件夹来获取foo包——即显式导入不受types白名单限制。六、声明文件的来源捆绑发布 vs DefinitelyTyped理解了装什么之后再补全从哪来的认知。根据 发布章节声明文件主要有两种发布途径与 npm 包捆绑如果声明文件是由源码生成的就与源码一起发布。TypeScript 工程和 JavaScript 工程都可以使用--declaration编译选项自动生成.d.ts文件。TypeScript 自身就是这种模式的代表。发布到typesorganization否则推荐将声明文件提交到 DefinitelyTyped由官方工具自动发布到 npm 的typesscope 下。绝大多数第三方库如 lodash、express走这条路径。这一区分直接决定了你在使用环节的操作库自带声明 → 直接npm install lib即可无需types包库不自带声明 →npm install --save types/lib补装类型个别库两者都没有 → 按 编写指南 自写或等待社区贡献。七、常见坑与进阶建议import * as _与import _的区别对于以export 方式导出CommonJS 风格的声明文件参见 module-function.d.ts 模板 中export MyFunction的写法import * as x from ...可能无法正确工作需要import x require(...)。若在 tsconfig 中启用esModuleInterop: true则可直接用默认导入import _ from lodashTypeScript 会自动处理。版本对齐types包的版本号通常与对应库的主版本保持一致如types/lodash4对应 lodash 4.x安装时可留意版本匹配避免 API 形状不一致导致类型报错。避免全局命名冲突如果一个工程安装了多个声明包且都向全局注入类型可能出现命名冲突。库结构章节的脚注 建议尽量用库提供的全局变量declare namespace来组织类型而不是散落在顶层。安装进 dependencies 而非 devDependencies当你的包作为库被他人引用时声明依赖属于运行期需求应放入dependencies否则使用者需要手动安装这些types包只有 CLI 工具等不被当库使用的场景才适合放devDependencies详见 发布章节。小结本文完整覆盖了 TypeScript 声明文件的消费端工作流用npm install --save types/库名下载、用import * as _ from lodash或全局变量使用、按types/前缀规律在 aka.ms/types 查找并深入解释了typeRoots与types两个编译选项如何控制types包的自动包含范围以及库自带声明 vs DefinitelyTyped 发布两种来源对使用方式的影响。掌握这些要点后你就能在任何 TypeScript 工程中快速、正确地接入第三方库的类型支持。赞分享文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载相关推荐解决MPV播放器痛点gh_mirrors/mpv-config脚本功能详解解决MPV播放器痛点gh_mirrors/mpv config脚本功能详解 gh_mirrors/mpv config是针对Windows平台MPV播放器的增终极TypeScript声明文件指南让pkg打包配置实现类型安全的完整教程终极TypeScript声明文件指南让pkg打包配置实现类型安全的完整教程 在Node.js项目开发中类型安全是提升代码质量和开发效率的关键因素。而当我们使开发工具简化TypeScript声明文件打包rollup-plugin-dts简化TypeScript声明文件打包rollup plugin dts 项目介绍 在现代前端开发中TypeScript已经成为不可或缺的一部分。然而随着项上一篇Steam挂刀行情站24小时自动化追踪四大平台饰品价格的终极指南下一篇【亲测免费】 强大而灵活的Qt应用全局热键库 —— QHotkey创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考