TypeScript Ambient 变量声明完全指南从 declare var 到接口合并扩展全局变量【免费下载链接】typescript-book:books: The definitive guide to TypeScript and possibly the best TypeScript book :book:. Free and Open Source 项目地址: https://gitcode.com/gh_mirrors/ty/typescript-book导读本篇指南聚焦 TypeScript 的Ambient环境变量声明如何在 TypeScript 项目中安全地使用 JavaScript 运行时或第三方库提供的全局变量如 Node.js 的process、浏览器的window并让类型系统对这些变量进行完整的类型检查。读完本文你将掌握declare var的基本用法、用接口interface结构化描述全局变量的最佳实践以及利用 TypeScript 接口合并机制零成本扩展全局变量的能力。文中所有示例均以当前仓库 typescript-book 中的文档与源码为依托可直接复制运行验证。背景什么是 Ambient DeclarationsTypeScript 的一个核心设计目标是让你能够安全、轻松地在 TypeScript 中直接使用已有的 JavaScript 库而 TypeScript 实现这一点的方式就是declaration声明。正如 docs/types/ambient/intro.md 所述TypeScript 的一个主要设计目标是使你能安全且轻松地在 TypeScript 中使用现有的 JavaScript 库其手段就是声明。Ambient环境声明带来的两大实战价值安全使用流行的 JavaScript 库——为运行时环境或第三方 JS 代码补充类型信息让编译器帮你提前发现错误增量迁移存量项目——把 JavaScript/CoffeeScript 或其他可编译为 JS 的语言项目平滑迁移到 TypeScript而无需一次性重写全部代码。值得一提的是研究第三方 JavaScript 代码的 ambient 声明模式也是为你自己的 TypeScript 代码库编写高质量类型标注的良好练习。起步用declare var声明一个全局变量要让 TypeScript 认识某个尚未定义的全局变量最基本的做法是使用declare关键字配合var声明。例如要告诉 TypeScript 存在一个名为process的变量Node.js 环境注入的全局对象可以这样写declare var process: any;在声明之后你就可以在代码中直接使用process而不再触发编译错误process.exit();如果没有这行声明TypeScript 会报错Cannot find name process因为编译器的编译上下文中根本不存在这个标识符。declare的本质是向编译器做出承诺这个变量在运行时一定存在类型信息我负责提供。关于declare关键字与声明文件的更多说明可参阅 docs/types/ambient/d.ts.md。注意ambient 声明是你与编译器之间的一份承诺。如果声明的变量在运行时并不存在而你仍然使用了它程序会在运行期静默地崩溃process is not defined之类编译器无法提前拦截。同时ambient 声明又像文档——如果源库更新了而声明文件没有同步更新就可能出现运行时正常、编译报错的错位现象。你通常不需要自己写node.d.ts对process这个具体变量来说你并不需要自己编写声明社区已经维护了一份高质量的 Node.js 类型声明DefinitelyTyped 社区项目。在当前的 typescript-book 仓库中就保留了一份这类声明的真实样例code/compiler/typings/node/node.d.ts。其中对process的声明是declare var process: NodeJS.Process; declare var global: NodeJS.Global;可以看到它并没有把process声明为any而是声明为命名空间NodeJS下的Process接口实例。这份文件同时声明了__filename、__dirname、setTimeout、require、module、Buffer等一系列 Node.js 全局量与内建模块。而 code/compiler/typings/tsd.d.ts 则通过三斜线指令把这份声明引入编译上下文/// reference pathnode/node.d.ts /这正是现实中接入社区类型声明的典型方式先查社区DefinitelyTyped有没有现成声明没有再自己动手。自己写声明是降低入门摩擦的关键技能但不必重复造轮子。升级用接口为全局变量提供结构化类型declare var process: any;虽然能让编译通过但any意味着完全放弃类型检查——process.foo.bar.baz()这类拼写错误也不会被拦截。因此本书推荐尽可能用接口interface来描述全局变量interface Process { exit(code?: number): void; } declare var process: Process;这样的写法有两大好处类型检查生效现在process.exit(1)是合法的而process.exit(boom)会立即报错参数类型不匹配拼写错误的属性访问同样会被编译器拦截。可扩展性接口在 TypeScript 中是开放open-ended的其他人可以在不修改原始声明的前提下为其追加成员。关于接口的深入讲解可参阅 docs/types/interfaces.md。在真实的 code/compiler/typings/node/node.d.ts 中NodeJS.Process接口正是这种模式的完整范例它包含argv: string[]、env: any、pid: number、cwd(): string、memoryUsage()等几十个成员其中就包括文档示例中用到的签名export interface Process extends EventEmitter { // ... exit(code?: number): void; // ... }扩展接口合并让全局变量可生长接口的开放性是 ambient 变量声明的点睛之笔。由于接口可以重复声明并自动合并任何人都能为全局变量补充成员。例如假设我们要给process添加一个exitWithLogging方法文档原文中是 for our amusement即演示用途interface Process { exitWithLogging(code?: number): void; } process.exitWithLogging function() { console.log(exiting); process.exit.apply(process, arguments); };整个过程分为两步声明合并再次声明interface Process并追加exitWithLogging成员TypeScript 会把两次声明合并为一个接口于是process.exitWithLogging立即获得了类型运行时实现在 JavaScript 运行时层面真的给process挂上这个函数Node.js 的process是普通对象支持动态添加属性。这样其他团队成员也可以照葫芦画瓢在各自模块中按需扩展全局变量而类型系统始终知道这些额外功能的存在。这正是 docs/types/lib.d.ts.md 中修改原生类型章节反复使用的模式——为window、Math、Date、String等全局量追加类型成员如interface Math { seedrandom(seed?: string); }、interface Window { helloWorld(): void; }。声明文件的组织方式.d.ts与global.d.ts声明可以放在普通.ts文件中也可以放在.d.ts声明文件中。对于真实项目强烈建议使用独立的.d.ts文件例如命名为global.d.ts或vendor.d.ts理由如下扩展名为.d.ts时文件顶层的每个定义都必须带declare前缀这迫使作者明确意识到TypeScript 不会为这些声明生成任何代码从而自觉保证被声明的实体在运行时确实存在把环境声明集中管理便于维护与审计。全局声明文件的典型场景包括声明编译期常量Webpack 的DefinePlugin注入的变量见 docs/project/globals.mddeclare const BUILD_MODE_PRODUCTION: boolean; // 可用于条件编译 declare const BUILD_VERSION: string;快速声明无类型的第三方库在从 JS 迁移到 TS 时可用declare var $: any;或declare module jquery;快速消除摩擦细节见 docs/types/migrating.md在模块文件中扩展全局类型如果声明必须写在带import/export的模块文件里可用declare global { ... }块重新进入全局命名空间export {}; declare global { interface String { endsWith(suffix: string): boolean; } }重要提醒摘自 docs/project/globals.md任何会生成 JavaScript 的代码都应优先使用文件模块global.d.ts只用于声明编译期常量、扩展lib.d.ts中的标准类型避免污染全局命名空间。与lib.d.ts的关系环境变量声明的另一面每次安装 TypeScript 都会自带一份特殊的声明文件lib.d.ts它包含了 JavaScript 运行时与 DOM 的各类常见构造的环境声明且自动进入编译上下文。其内容主体正是一堆变量声明 一堆接口声明例如declare var window: Window; declare var Math: Math; declare var Date: DateConstructor;以window为例就是一个简单的declare var 变量名 接口类型标注对应的Window接口则包含animationStartTime: number、applicationCache: ApplicationCache、closed: boolean等海量成员。由于这些全局量都指向接口你可以用前面学到的接口合并技术向Window、Math、Date、String等追加成员而无需修改lib.d.ts本身——这与扩展Process接口的原理完全一致。详见 docs/types/lib.d.ts.md。理解这一层关系你就掌握了一条完整的认知链路declare var process: any; // 最简声明关闭类型检查 declare var process: Process; // 结构化声明启用类型检查 interface Process { exit(code?: number): void; } // 接口可被任何人扩展 interface Process { exitWithLogging(...): void; } // 接口合并增量扩展小结与延伸阅读Ambient 变量声明的核心要点可以浓缩为三句话用declare var告诉编译器全局变量存在——最简形式是declare var process: any;优先用接口而非any——declare var process: Process;能真正获得类型检查接口合并让全局变量可扩展——重复声明同一个接口即可追加成员无需改动原始声明文件。在写自己的声明之前记得先确认社区是否已有现成方案例如 DefinitelyTyped 中的node、jquery、datejs等仓库内的 code/compiler/typings/node/node.d.ts 与 code/compiler/typings/tsd.d.ts 是很好的学习样本。进一步阅读docs/types/ambient/intro.md——Ambient 声明总览与设计动机docs/types/ambient/d.ts.md——declare关键字与声明文件规范docs/types/lib.d.ts.md——lib.d.ts内部结构与原生类型扩展docs/project/globals.md——global.d.ts的使用场景与注意事项docs/types/migrating.md——利用 ambient 声明迁移 JavaScript 项目【免费下载链接】typescript-book:books: The definitive guide to TypeScript and possibly the best TypeScript book :book:. Free and Open Source 项目地址: https://gitcode.com/gh_mirrors/ty/typescript-book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考