本文旨在介绍在JavaScript代码中安全有效地使用全局对象（如window）上的外部库的最佳实践。重点讲解如何处理依赖于在运行时才加载到全局作用域的库的情况，包括类型声明、加载时机处理以及代码的健壮性提升。通过本文，你将学会如何编写更可靠、更易于维护的JavaScript代码，并避免因库未加载而引发的运行时错误。
类型声明：避免编译错误
当你的代码依赖于全局对象上的外部库时，TypeScript编译器可能会因为找不到相应的类型定义而报错。为了解决这个问题，你需要为该库添加类型声明。
一种常见的方法是使用 declare global 来扩展 Window 接口，如下所示：
declare global {
interface Window {
ats?: any; // 将 ats 声明为 window 对象的可选属性
}
}这段代码告诉TypeScript编译器，window 对象可能具有一个名为 ats 的属性。 ? 表示该属性是可选的，这意味着即使 ats 不存在，编译器也不会报错。 any 类型则表示 ats 可以是任何类型。
虽然使用 any 可以快速解决编译问题，但它牺牲了类型安全性。更好的做法是尽可能提供更精确的类型定义。如果可以找到该库的类型定义文件（通常以 .d.ts 结尾），则可以直接引入它。如果没有现成的类型定义文件，可以尝试自己编写一个。
例如，如果 ats 是一个包含 retrieveEnvelope 方法的对象，可以这样定义类型：
declare global {
interface Window {
ats?: {
retrieveEnvelope: (callback: (envelope: string) => void) => void;
};
}
}这样，TypeScript编译器就能对 ats.retrieveEnvelope 的使用进行类型检查，从而减少运行时错误。
延迟加载：确保库可用
仅仅添加类型声明还不够，还需要确保在使用外部库之前，该库已经被加载到全局作用域中。如果过早地访问该库，可能会导致运行时错误。
一个常见的解决方案是使用 onload 事件监听器来等待库加载完成：
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
var src= "https://yourlibrarypath";
var useSSL = document.location.protocol === 'https:';
var d = document, e = d.createElement('script'), p = d.getElementsByTagName('head')[0];
e.type = 'text/javascript'; e.async = true;
e.src = (useSSL ? 'https:' : 'http:') + src;
p.insertBefore(e, p.firstChild);
e.onload = function() {
//library has been loaded...
// 在这里使用外部库
if (window.ats) {
window.ats.retrieveEnvelope(function (envelope: string) {
console.log('Located ATS.js');
this.cachedEnvelope = JSON.parse(envelope).envelope;
});
}
}这段代码首先创建一个 <script> 元素，并将其 src 属性设置为外部库的 URL。然后，它将该元素添加到文档的 <head> 中。 e.async = true; 确保脚本异步加载，不会阻塞页面的渲染。
e.onload 事件监听器会在脚本加载完成后被触发。在 onload 函数中，你可以安全地使用外部库。
注意事项：
- 确保 src 变量指向正确的外部库 URL。
- 如果外部库加载失败， onload 事件监听器可能不会被触发。为了处理这种情况，可以添加一个 onerror 事件监听器。
代码健壮性：避免运行时错误
即使你已经使用了类型声明和延迟加载，仍然可能遇到运行时错误。例如，外部库可能由于网络问题而加载失败，或者库的 API 可能会发生变化。
为了提高代码的健壮性，建议在访问外部库之前进行检查：
if (window.ats) {
// 外部库已加载，可以安全地使用它
window.ats.retrieveEnvelope(function (envelope: string) {
console.log('Located ATS.js');
this.cachedEnvelope = JSON.parse(envelope).envelope;
});
} else {
// 外部库未加载，进行错误处理
console.error('ATS.js is not loaded.');
}这段代码首先检查 window.ats 是否存在。如果存在，则可以安全地使用它。如果不存在，则进行错误处理，例如记录错误信息或显示警告消息。
总结：
在使用全局对象上的外部库时，需要注意以下几点：
- 使用类型声明来避免编译错误。
- 使用延迟加载来确保库可用。
- 在访问外部库之前进行检查，以避免运行时错误。
通过遵循这些最佳实践，你可以编写更可靠、更易于维护的JavaScript代码。
