扩展API

Chrome文档 • Firefox文档

不同的浏览器提供不同的全局变量来访问扩展API（Chrome提供chrome，Firefox提供browser等）。

WXT简化了这一过程——总是使用browser：

browser.action.onClicked.addListener(() => {
  // ...
});

除此之外，请参考Chrome和Mozilla的文档以了解如何使用特定的API。WXT可以像使用browser一样实现所有普通扩展的功能，无需额外配置。

Webextension Polyfill

自v0.1.0起

默认情况下，WXT会使用 Mozilla 提供的webextension-polyfill来确保浏览器之间的一致性。

要访问类型，请从wxt/browser导入相关命名空间：

import { Runtime } from 'wxt/browser';

function handleMessage(message: any, sender: Runtime.Sender) {
  // ...
}

关闭polyfill

自v0.19.0起

在MV3发布及Chrome官方弃用MV2后（2024年6月），polyfill不再起到任何作用。

你可以通过以下方式关闭它：

// wxt/config.ts
export default defineConfig({
  extensionApi: 'chrome',
});

这将使wxt/browser根据运行时浏览器自动导出browser或chrome全局变量：

export const browser: WxtBrowser =
  // @ts-expect-error
  globalThis.browser?.runtime?.id == null
    ? globalThis.chrome
    : // @ts-expect-error
      globalThis.browser;

在polyfill关闭后，访问类型的方式有所不同。它们不需要导入即可使用，它们会包含在browser对象中：

function handleMessage(message: any, sender: browser.runtime.Sender) {
  // ...
}

特征检测

由于一些浏览器和运行时的版本不同，某些API在运行时不可用。如果某个API不可用，则它将为undefined。

WARNING

类型在这里帮不上忙。WXT提供的browser对象上的类型假设所有API都存在。你需要自行确认某个API是否可用。

要检查某个API是否可用，请使用特征检测：

if (browser.runtime.onSuspend != null) {
  browser.runtime.onSuspend.addListener(() => {
    // ...
  });
}

这里，可选链式调用是你的最佳选择：

browser.runtime.onSuspend?.addListener(() => {
  // ...
});

或者，如果你在尝试使用不同名称的类似API（为了支持MV2和MV3）时，可以这样做：

(browser.action ?? browser.browser_action).onClicked.addListener(() => {
  //
});