使用 window 对象上的外部库的最佳实践-js教程-PHP中文网

使用 window 对象上的外部库的最佳实践

碧海醫心

发布： 2025-08-08 16:32:26

原创

508人浏览过

使用 window 对象上的外部库的最佳实践

本文探讨了在 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 事件处理程序会在加载失败时执行。

库宝AI

库宝AI是一款功能多样的智能伙伴助手，涵盖AI写作辅助、智能设计、图像生成、智能对话等多个方面。

109

查看详情

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 函数来验证该函数是否被调用，以及传递了哪些参数。

总结