JavaScript / TypeScript / 系统课时
模块扩充
模块扩充
当第三方库、框架插件或项目补丁在运行时给已有对象增加成员时,原模块的类型声明往往不会自动知道这些变化。模块扩充让你在不修改原包声明文件的前提下,把新增成员合并进既有类型,同时保留原模块的导入方式和类型推断。
学习目标
- 理解模块扩充如何与原模块声明合并
- 为已有类或接口补充新成员,并同步提供运行时实现
- 识别模块扩充不能新增顶层导出等关键限制
扩充发生在类型层
模块扩充使用 declare module "模块名" 描述“这个已有模块还多了哪些类型成员”。它不会修改 JavaScript 对象,也不会自动创建方法。因此,如果扩充的是一个真实会被调用的方法,代码里必须同时存在对应的运行时实现。
扩充代码所在文件应本身是一个模块,通常通过顶层 import 或 export 达成。这样 declare module 会被解释为对既有模块的补充,而不是重新声明一个孤立的环境模块。
给已有类增加实例方法
先准备原模块 observable.ts,它只导出一个保存值的泛型类:
export class Observable<T> {
constructor(public readonly value: T) {}
}再创建 observable-map.ts。先导入原类,再扩充 Observable<T> 的实例类型,最后把真实方法挂到原型上:
import { Observable } from "./observable";
declare module "./observable" {
interface Observable<T> {
map<U>(fn: (value: T) => U): Observable<U>;
}
}
Observable.prototype.map = function <T, U>(
this: Observable<T>,
fn: (value: T) => U
): Observable<U> {
return new Observable(fn(this.value));
};调用方必须加载这段补丁代码,才能让运行时对象真正拥有 map:
import { Observable } from "./observable";
import "./observable-map";
const result = new Observable(3).map((n) => `value=${n * 2}`);
console.log(result.value);编译并运行这三个文件:
npx tsc --strict --module commonjs --target ES2020 --outDir dist observable.ts observable-map.ts main.ts && node dist/main.js预期输出:
value=6如果删掉 import "./observable-map",类型是否仍可见取决于该扩充文件是否被编译进项目,但运行时一定不会执行原型赋值;调用 map 时就可能出现“不是函数”的错误。因此,类型扩充和运行时补丁要作为同一个功能一起交付。
模块名必须指向同一个目标
declare module "./observable" 中的字符串会按正常模块解析规则定位目标,最好与实际导入使用同一种模块说明符。路径写错、别名配置不一致或扩充了另一个重名模块,都会导致声明没有合并到预期类型上。
对于 npm 包,写法同样是 declare module "包名"。如果只想给其中某个已导出的接口补属性,就在扩充块中重新声明同名接口;TypeScript 会按照声明合并规则把成员并入原接口。
不能用扩充创造新的顶层 API
模块扩充的能力边界是“补丁”,不是“重新设计模块”。它只能扩充已经存在、可以被名字引用的声明,不能凭空新增新的顶层导出成员;默认导出也因为没有可供扩充引用的导出名称而不能直接扩充。
适合使用模块扩充的场景包括框架插件为请求对象增加字段、库的插件系统给实例增加方法,以及项目内部对第三方类型做小范围补丁。若你实际改变了公共 API 的所有权和设计,优先修改源类型或提交上游修复,而不是长期依赖扩充掩盖结构问题。