在混合应用开发中，原生端通过WebView注入JavaScript对象是一种常见做法。例如Android使用addJavascriptInterface，iOS使用WKScriptMessageHandler配合注入脚本，最终在网页里可以通过window.NativeBridge调用原生能力。问题在于，TypeScript的标准Window接口并不包含这些动态添加的成员。如果直接在TS文件中写window.NativeBridge.call(...)，编译器会报错：类型Window上不存在属性NativeBridge。为了让编辑器提供自动补全、类型检查和重构能力，需要手工为这些桥接方法补充类型声明。
这个类型缺口不仅影响开发体验，更可能让参数传错、返回值误用等情况逃过编译期检查，直到线上才暴露。例如原生端期望超时参数是毫秒数，前端却传入了秒，或者原生端返回的是JSON字符串，前端直接当作对象使用，这些问题在any类型下都无法被及时拦截。因此，合理的类型声明是混合开发中不可省略的一步。
一、先看清楚桥接对象的运行方式
在动手补类型之前，需要明确原生端注入对象的具体形态。常见的方式有两种：一种是注入一个全局对象，例如window.NativeBridge，上面挂载call、on、off等方法；另一种是注入多个独立函数，例如window.getLocation、window.showToast。无论哪一种，TypeScript都不会自动识别，因为标准库的Window接口定义中根本没有这些成员。
以Android的addJavascriptInterface为例，原生代码将Java对象暴露给WebView，JavaScript侧通过全局对象访问它的方法。这个对象在运行时确实存在，但在编译期只是一个未知属性。下面这段代码在TS项目中会直接产生类型错误，尽管它在浏览器或WebView里可以运行。
// 原生端注入的对象，TypeScript 无法识别
window.NativeBridge.call('getLocation', { timeout: 5000 });
// 类型“Window & typeof globalThis”上不存在属性“NativeBridge”。ts(2339)
这里的关键点在于：TypeScript的类型系统基于静态声明，它不会去执行JavaScript来发现运行时注入的属性。因此，我们需要通过声明合并或模块声明的方式，告诉编译器这些运行时对象的存在及其类型结构。接下来分别介绍几种实用的方案。
二、全局接口扩展与声明合并
如果桥接对象只是挂在window上的一个全局对象，最直接的做法是利用TypeScript的声明合并机制。在全局作用域中重新声明Window接口，给它增加NativeBridge属性即可。需要把声明放在.d.ts文件中，并且确保该文件被tsconfig包含。
声明合并是TypeScript的重要特性：多次声明同名的interface，类型系统会把这些成员合并到一起。通过declare global可以进入全局作用域，对Window接口进行扩展。下面是一个完整的global.d.ts示例，同时定义了NativeBridgeAPI接口来描述桥接方法的结构，避免在Window接口里堆砌匿名函数签名。
// global.d.ts
declare global {
interface Window {
NativeBridge?: NativeBridgeAPI;
}
interface NativeBridgeAPI {
call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
on(event: string, callback: (payload: unknown) => void): void;
off(event: string, callback?: (payload: unknown) => void): void;
}
}
export {};
这个声明里，call方法使用了泛型，调用方可以显式指定返回类型，例如window.NativeBridge.call<{latitude: number; longitude: number}>('getLocation')。params使用Record<string, unknown>表示任意键值对，避免过度约束。NativeBridge属性带问号，是因为在非WebView环境下可能不存在，调用前需要做存在性判断。
需要注意的是，global.d.ts文件中末尾的export {}是必要的。它让这个文件被视为模块，同时declare global又能将声明提升到全局作用域。如果文件里没有任何导入导出语句，declare global会被忽略吗？实际上如果文件本身不是模块，接口声明已经默认处于全局，declare global反而可能出现错误。加上export {}后，declare global语法生效，这是更稳妥的写法。记得在tsconfig.json的include中加上这个文件或目录，例如src/types/**/*.d.ts。
这种方案适合小型项目或单个全局桥接对象。它的优点是简单直观，业务代码里无需额外导入，直接使用window.NativeBridge就能获得类型提示。缺点是所有全局类型都集中在一个文件中，当桥接方法很多、涉及多个模块时，维护成本会上升，而且全局接口扩展无法表达命名空间隔离。
三、模块声明方式适配复杂桥接SDK
如果桥接逻辑不是直接挂在window上，而是封装成了独立的SDK模块，业务代码通过import引入，那么更适合使用declare module来补充模块类型。例如原生团队发布了一个npm包，实际类型可能缺失或不全，前端可以写一个本地声明文件覆盖或补充。
declare module的作用是声明某个模块的类型，用来告诉TypeScript在导入这个模块时有哪些导出。以下示例假设存在一个名为native-bridge-sdk的包，里面导出了NativeBridge对象。
// native-bridge.d.ts
declare module 'native-bridge-sdk' {
export interface NativeBridge {
call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
}
export const NativeBridge: NativeBridge;
}
业务代码中就可以正常导入并获得类型检查：
import { NativeBridge } from 'native-bridge-sdk';
async function getLocation(): Promise<{ latitude: number; longitude: number }> {
return NativeBridge.call<{ latitude: number; longitude: number }>('getLocation');
}
这种方式的优势在于类型边界清晰，桥接相关的声明与业务代码解耦。如果团队负责维护多个WebView容器，每个容器的桥接能力不同，也可以用不同的声明模块来分别处理，避免全局Window接口被无限膨胀。缺点是使用前需要确保声明文件能够被TypeScript找到，通常放在项目根目录的types文件夹，并在tsconfig的include或typeRoots中配置。
此外，模块声明还能配合路径映射使用。如果SDK并非来自node_modules，而是通过构建工具注入的虚拟模块，也可以声明对应模块名。只要运行时确实能够导入该名称，类型声明就能正常工作。
四、用泛型映射进一步约束桥接方法
前两种方案解决了有没有类型的问题，但如果桥接方法数量较多，每个方法都是string参数加unknown返回值，依然无法防止把参数类型写错。更进阶的做法是建立一个方法名与参数、返回类型的映射表，然后用泛型对call方法做更精确的约束。
下面定义BridgeMethodMap，列出不同方法对应的参数和返回值。再让TypedNativeBridge的call方法根据传入的方法名自动推导出准确的参数类型和Promise返回值类型。
interface BridgeMethodMap {
getLocation: {
params: { timeout?: number };
result: { latitude: number; longitude: number };
};
showToast: {
params: { message: string; duration?: number };
result: void;
};
}
interface TypedNativeBridge {
call<K extends keyof BridgeMethodMap>(
method: K,
...args: BridgeMethodMap[K]['params'] extends never
? []
: [params: BridgeMethodMap[K]['params']]
): Promise<BridgeMethodMap[K]['result']>;
}
使用时，如果传入的方法名是getLocation，第二个参数就会自动变成{ timeout?: number }，返回值类型也会被锁定为{ latitude: number; longitude: number }。这样即使原生端方法很多，只要维护好BridgeMethodMap，调用的类型安全性就能得到很大提升。
这种方案适合桥接方法固定、参数结构清晰的场景。维护成本在于当原生端新增或修改方法时，需要同步更新映射表。不过这个成本通常是值得的，因为它能把接口契约固化在类型层，减少前端与原生端的沟通误差。对于参数结构特别复杂的方法，还可以把params类型单独提取成interface，保持映射表可读性。
需要注意的是，如果某些方法确实存在动态参数无法穷举的情况，可以保留一个更宽松的签名作为兜底，例如call方法重载，让大多数常用方法走严格类型，少数特殊方法退回unknown。这样既不会牺牲整体类型安全，也不会因为过度限制而无法调用。
五、实际使用中的细节与避坑
补齐类型声明之后，实际调用时还要注意桥接对象可能不存在的运行环境。因为WebView注入通常发生在页面加载之后，或者只在特定App内才可用，所以调用前最好做判断。下面的写法可以避免在普通浏览器或未注入的原生环境中抛错。
if (window.NativeBridge) {
await window.NativeBridge.call('getLocation');
} else {
console.warn('NativeBridge 未注入，当前环境可能不支持原生能力');
}
另一个容易被忽略的问题是d.ts文件的加载范围。很多项目默认只包含src目录下的.ts文件，如果类型声明放在项目根目录的types文件夹，必须手动加入tsconfig的include字段，否则声明不会生效。例如可以把配置写成"include": ["src/**/*.ts", "types/**/*.d.ts"]。如果使用了eslint，也要确保相关文件不会被lint规则误伤。
还有一点，尽量少用as any来绕过类型检查。当遇到类型不匹配时，优先修正声明文件或调整映射表。临时使用any虽然能快速通过编译，但会让之前建立起来的类型安全形同虚设。如果确实无法确定某个方法的返回值结构，可以显式使用unknown，然后在业务侧做收窄处理，这样至少保留了类型检查的严谨性。
总结来说，为WebView桥接方法添加类型并不是一次性工作，而是随着原生能力迭代持续维护的过程。根据项目阶段和团队协作方式选择合适的声明策略，可以把原生与前端之间的契约变得清晰可靠，减少运行时错误，提升开发效率。
TypeScriptWebView桥接类型声明修改时间：2026-09-19 11:54:00