本文探讨了在 JavaScript 代码中依赖于全局 window 对象上的外部库时，如何处理类型定义和确保库加载完成的最佳实践。通过声明全局接口扩展 window 对象，可以解决编译问题和方便测试中的模拟。同时，使用动态脚本加载和 onload 事件监听，可以确保在库加载完成后再执行依赖代码，避免运行时错误。
当你的 JavaScript 代码依赖于一个全局变量（例如，window 对象上的一个外部库），并且该库不是你的代码直接引入的，你需要确保代码能够正确识别该全局变量，同时避免编译错误。以下是一些处理这种情况的最佳实践。
1. 扩展全局 window 接口（TypeScript）
如果你的项目使用 TypeScript，你需要扩展全局 window 接口，以便 TypeScript 编译器能够识别外部库。这可以通过声明一个全局接口来实现：
declare global {
interface Window {
ats?: any; // 将 'ats' 替换为你的库的名称
}
}上述代码告诉 TypeScript 编译器，window 对象可能包含一个名为 ats 的属性，其类型可以是 any。 使用 any 类型虽然简单，但会牺牲类型安全性。更理想的情况是，如果知道库的结构，可以定义更精确的类型。 例如，如果 ats 是一个包含 retrieveEnvelope 方法的对象，你可以这样定义：
declare global {
interface Window {
ats?: {
retrieveEnvelope: (callback: (envelope: string) => void) => void;
};
}
}这样做的好处是，当你使用 window.ats.retrieveEnvelope 时，TypeScript 会进行类型检查，帮助你避免潜在的错误。
2. 动态加载外部库
为了确保你的代码在外部库加载完成后再执行，可以使用动态脚本加载。这可以通过创建一个 <script> 元素，并将其添加到 DOM 中来实现。
function loadScript(src, callback) {
var script = document.createElement('script');
script.type = 'text/javascript';
script.async = true; // 异步加载
script.src = src;
script.onload = function() {
callback(); // 库加载完成后执行回调函数
};
script.onerror = function() {
console.error('Failed to load script: ' + src);
};
document.head.appendChild(script);
}
// 示例用法
loadScript('https://yourlibrarypath/ats.js', function() {
// 库加载完成后执行的代码
if (window.ats) {
window.ats.retrieveEnvelope(function (envelope) {
console.log('Located ATS.js');
// 在这里处理 envelope
});
} else {
console.error('ATS.js is not available.');
}
});上述代码首先创建一个 <script> 元素，设置其 src 属性为外部库的 URL，并将其添加到 <head> 标签中。onload 事件处理程序会在脚本加载完成后执行回调函数。onerror 事件处理程序会在加载失败时执行。
3. 使用 Promise 和 async/await (现代 JavaScript)
如果你的环境支持 Promise 和 async/await，可以使用 Promise 来封装脚本加载过程，使代码更具可读性和可维护性。
function loadScriptAsync(src) {
return new Promise((resolve, reject) => {
var script = document.createElement('script');
script.type = 'text/javascript';
script.async = true;
script.src = src;
script.onload = () => {
resolve();
};
script.onerror = () => {
reject(new Error('Failed to load script: ' + src));
};
document.head.appendChild(script);
});
}
// 示例用法
async function initialize() {
try {
await loadScriptAsync('https://yourlibrarypath/ats.js');
if (window.ats) {
window.ats.retrieveEnvelope(function (envelope) {
console.log('Located ATS.js');
// 在这里处理 envelope
});
} else {
console.error('ATS.js is not available.');
}
} catch (error) {
console.error(error);
}
}
initialize();在这个例子中，loadScriptAsync 函数返回一个 Promise，当脚本加载成功时 resolve，加载失败时 reject。async/await 语法使得异步代码看起来更像同步代码。
4. 测试中的 Mock
在测试环境中，你可能需要模拟外部库的行为。通过扩展全局 window 接口，你可以轻松地在测试中模拟 ats 对象。
// 示例 (使用 Jest)
describe('ATS integration', () => {
it('should retrieve envelope', () => {
const mockRetrieveEnvelope = jest.fn();
(window as any).ats = {
retrieveEnvelope: mockRetrieveEnvelope
};
// 你的测试代码
expect(mockRetrieveEnvelope).toHaveBeenCalled();
});
});在这个例子中，我们使用 Jest 的 jest.fn() 创建了一个模拟函数 mockRetrieveEnvelope，并将其赋值给 window.ats.retrieveEnvelope。这样，当你的代码调用 window.ats.retrieveEnvelope 时，实际上会调用这个模拟函数。你可以使用 Jest 的 expect 函数来验证该函数是否被调用，以及传递了哪些参数。
总结
- 使用 declare global 扩展 window 接口，提供类型信息，避免编译错误，并方便测试中的模拟。
- 使用动态脚本加载和 onload 事件监听，确保在外部库加载完成后再执行依赖代码，避免运行时错误。
- 考虑使用 Promise 和 async/await 简化异步代码。
- 在测试环境中，使用模拟对象来隔离你的代码，确保测试的可靠性。
通过遵循这些最佳实践，你可以更安全、更可靠地使用全局 window 对象上的外部库。
