JavaScript API

WebExtensions 的 JavaScript API 可以用于扩展的后台脚本和扩展程序捆绑的任何其他文档中，包括浏览器操作或页面操作弹出窗口、侧边栏、选项页面或新标签页。扩展的内容脚本也可以访问其中一些 API。（请参阅内容脚本指南中的列表）。

要使用功能更强大的 API，您需要在扩展程序的 manifest.json 中请求权限。

您可以使用 browser 命名空间访问 API

js

function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({ currentWindow: true }, logTabs);

许多 API 都是异步的，返回一个 Promise

js

function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

let setCookie = browser.cookies.set({ url: "https://mdn.org.cn/" });
setCookie.then(logCookie, logError);

浏览器 API 差异

请注意，这与 Google Chrome 的扩展系统不同，后者使用 chrome 命名空间而不是 browser，并且对于异步函数使用回调而不是 Promise。作为移植辅助工具，WebExtensions API 的 Firefox 实现支持 chrome 和回调以及 browser 和 Promise。Mozilla 还编写了一个 polyfill，使使用 browser 和 Promise 的代码可以在 Chrome 中保持不变：https://github.com/mozilla/webextension-polyfill。

Firefox 还使用回调在 chrome 命名空间下实现这些 API。这允许为 Chrome 编写的代码在 Firefox 中针对此处记录的 API 基本上保持不变地运行。

Microsoft Edge 使用 browser 命名空间，但尚未支持基于 Promise 的异步 API。在 Edge 中，目前异步 API 必须使用回调。

并非所有浏览器都支持所有 API：有关详细信息，请参阅浏览器对 JavaScript API 的支持和 Chrome 不兼容性。

示例

在 JavaScript API 列表中，简短的代码示例说明了如何使用 API。您可以使用工具箱中的控制台试用大多数这些示例。但是，您需要在 Web 扩展的上下文中运行工具箱。为此，请打开 about:debugging，然后打开此 Firefox，针对任何已安装或临时的扩展单击检查，然后打开控制台。然后，您可以在控制台中粘贴并运行示例代码。

例如，以下是此页面上第一个代码示例在 Firefox 开发版中的工具箱控制台中运行的情况

Illustration of a snippet of web extension code run from the console in the Toolbox

JavaScript API 列表

请参见以下 JavaScript API 的完整列表

读取和修改属性，并侦听使用 action 清单键定义的浏览器工具栏按钮上的点击。

计划代码在将来的特定时间运行。这类似于 setTimeout() 和 setInterval()，除了这些函数不适用于按需加载的后台页面。

使用 WebExtensions bookmarks API，扩展可以与浏览器的书签系统交互并对其进行操作。您可以使用它来为页面添加书签、检索现有书签以及编辑、删除和组织书签。

browserAction

读取和修改属性，并侦听使用 browser_action 清单键定义的浏览器工具栏按钮上的点击。

browserSettings

使扩展能够修改某些全局浏览器设置。此 API 的每个属性都是一个 types.BrowserSetting 对象，提供修改特定设置的功能。

browsingData

使扩展能够清除用户浏览时积累的数据。

captivePortal

确定用户连接的受限门户状态。受限门户是在用户首次连接到 Wi-Fi 网络时显示的网页。用户在受限门户网页上提供信息或执行操作以获得更广泛的网络资源访问权限，例如接受条款和条件或付款。

WebExtension clipboard API（与标准 Clipboard API 不同）使扩展能够将项目复制到系统剪贴板。目前，WebExtension clipboard API 仅支持复制图像，但它旨在将来支持复制文本和 HTML。

侦听用户执行已使用 commands 清单 json 键注册的命令。

contentScripts

使用此 API 注册内容脚本。注册内容脚本会指示浏览器将给定的内容脚本插入与给定 URL 模式匹配的页面中。

contextualIdentities

使用上下文身份：列出、创建、删除和更新上下文身份。

使扩展能够获取和设置 Cookie，并在 Cookie 更改时收到通知。

declarativeNetRequest

此 API 使扩展能够指定描述如何处理网络请求的条件和操作。这些声明性规则使浏览器能够评估和修改网络请求，而无需向扩展程序通知单个网络请求。

使扩展能够与浏览器的开发者工具交互。您可以使用此 API 创建开发者工具页面、与正在检查的窗口交互、检查页面网络使用情况。

使扩展能够解析域名。

访问仅扩展的特殊 DOM 功能。

使扩展能够与浏览器的下载管理器交互。您可以使用此 API 模块下载文件、取消、暂停、恢复下载并在文件管理器中显示已下载的文件。

分派事件的 API 使用的常用类型。

与您的扩展相关的实用程序。获取与您的扩展程序打包在一起的资源的 URL。获取扩展程序页面的 Window 对象。获取各种设置的值。

extensionTypes

其他 WebExtension API 中使用的一些常用类型。

在网页中查找文本，并突出显示匹配项。

使用 history API 与浏览器历史记录交互。

用于国际化扩展的功能。您可以使用这些 API 从扩展程序打包的语言环境文件中获取本地化字符串，找出浏览器的当前语言，并找出其Accept-Language 标头的值。

使用身份 API 获取OAuth2授权码或访问令牌，扩展程序可以使用该令牌访问支持 OAuth2 访问的服务（例如 Google 或 Facebook）的用户数据。

找出用户系统何时处于空闲、锁定或活动状态。

获取有关已安装加载项的信息。

向浏览器的菜单系统添加项目。

notifications

使用底层操作系统的通知机制向用户显示通知。由于此 API 使用操作系统的通知机制，因此通知的显示方式和行为细节可能因操作系统和用户设置而异。

使扩展程序能够在用户在浏览器的地址栏中键入内容时实现自定义行为。

读取和修改地址栏按钮的属性，并侦听其点击事件，该按钮使用page_action清单键定义。

permissions

使扩展程序能够在安装后在运行时请求额外的权限。

pkcs11 API 使扩展程序能够枚举PKCS #11安全模块，并使它们能够作为密钥和证书来源供浏览器访问。

访问和修改各种与隐私相关的浏览器设置。

使用代理 API 代理 Web 请求。您可以使用proxy.onRequest事件监听器拦截 Web 请求，并返回一个对象，该对象描述是否以及如何代理它们。

此模块提供有关您的扩展程序及其运行环境的信息。

将 JavaScript 和 CSS 插入网站。此 API 提供了两种插入内容的方法

使用搜索 API 检索已安装的搜索引擎并执行搜索。

使用会话 API 列出和恢复浏览器运行期间已关闭的标签页和窗口。

sidebarAction

获取和设置扩展程序侧边栏的属性。

使扩展程序能够存储和检索数据，并侦听存储项的更改。

与浏览器的标签系统交互。

使浏览器扩展程序能够获取浏览器主题的详细信息并更新主题。

使用 topSites API 获取包含用户经常访问的页面的数组。

定义BrowserSetting类型，用于表示浏览器设置。

userScripts

使用此 API 注册用户脚本，用户脚本是旨在操作网页或提供新功能的第三方脚本。注册用户脚本会指示浏览器将脚本附加到与注册期间指定的 URL 模式匹配的页面。

webNavigation

为导航的各个阶段添加事件监听器。导航包括浏览器中的一个框架从一个 URL 转换到另一个 URL，通常（但并非总是）响应用户操作，例如点击链接或在地址栏中输入 URL。

为发出 HTTP 请求的各个阶段添加事件监听器，其中包括在ws://和wss://上的 websocket 请求。事件监听器接收有关请求的详细信息，并且可以修改或取消请求。

与浏览器窗口交互。您可以使用此 API 获取有关打开的窗口的信息，以及打开、修改和关闭窗口。您还可以侦听窗口打开、关闭和激活事件。