WebExtensions JavaScript 组件参考¶
此页面包含用于实现 WebExtensions API 的各个类的参考文档。这些文档是从源代码中的 jsdoc 注释生成的。
ExtensionAPI 类¶
- class ExtensionAPI()¶
WebExtension API 的基类。每个 API 创建一个从该类继承的新类，派生类为使用该 API 的每个扩展实例化一次。
- ExtensionAPI.ExtensionAPI¶
- ExtensionAPI.getAPI(_context)¶
- 参数:
_context (BaseContext)
- ExtensionAPI.onManifestEntry(_entryName)¶
- 参数:
_entryName (字符串)
- ExtensionAPI.onShutdown(_isAppShutdown)¶
- 参数:
_isAppShutdown (布尔值)
- static ExtensionAPI.onDisable(_id)¶
- 参数:
_id (字符串)
- static ExtensionAPI.onUninstall(_id)¶
- 参数:
_id (字符串)
- static ExtensionAPI.onUpdate(_id, _manifest)¶
- 参数:
_id (字符串)
_manifest (对象)
Extension 类¶
- class Extension()¶
此类是主进程中活动 WebExtension 的主要表示形式。
- Extension.Extension¶
- Extension.activePermissions¶
返回一个表示此扩展拥有所有功能的对象，包括清单中的固定功能以及动态授予的权限。
- Extension.addonData¶
类型: 对象
待办事项：移动到 Extension 类，错误 1871094。
- Extension.backgroundState¶
backgroundState 可以是 starting、running、suspending 或 stopped。如果扩展没有后台页面，则未定义。有关更多详细信息，请参阅 ext-backgroundPage.js。
- Extension.baseURI¶
类型: nsIURI
- Extension.manifestOptionalPermissions¶
返回清单中的可选权限，如果 originControls 为 true，则包括主机权限。
- Extension.persistentListeners¶
类型: Map.<字符串, Map.<字符串, 任何>>
- Extension.principal¶
类型: nsIPrincipal
- Extension.shortcuts¶
- Extension.tabManager¶
类型: TabManagerBase
扩展的 TabManager，在 Management 的“startup”事件中初始化。
- Extension.temporarilyInstalled¶
类型: 布尔值
- Extension.terminateBackground¶
- Extension.windowManager¶
类型: WindowManagerBase
扩展的 WindowManager，在 Management 的“startup”事件中初始化。
- Extension._readDirectory(path, directoriesOnly=false)¶
发现目录或 JAR 文件中的文件名。
- 参数:
path (字符串) – 要查看的目录或 jar 文件的路径。
directoriesOnly (布尔值) – 如果为 true，则仅返回目录中存在的目录。
- 返回值:
Promise.<Array.<字符串>> – 文件/目录名称数组（仅名称，而非路径）。
- Extension.callOnClose(obj)¶
当此扩展关闭时，在给定对象上调用 close() 方法。这可能发生在浏览器关闭期间，或者在手动禁用或卸载扩展时。
- 参数:
obj (对象) – 当此扩展关闭时，在其上调用 close() 方法的对象。
- Extension.clearCache(reason)¶
当安装扩展（如果我们无法在卸载时执行此操作）或升级或降级扩展时，清除与扩展主体关联的缓存资源。
- 参数:
reason (字符串|未定义) – BOOTSTRAP_REASON 字符串（如果提供）。对于没有相应 AddonManager 附加组件包装器的扩展对象（例如，使用 ExtensionTestUtils 而没有 useAddonManager 可选属性创建的测试扩展），预期值为 undefined。
- 返回值:
Promise.<void> – 当 nsIClearDataService 异步方法调用完成后解析的 Promise。
- Extension.getLocalizedManifest(locale)¶
加载语言环境并返回本地化的清单。扩展必须初始化，并且在调用之前解析清单。
- 参数:
locale (字符串) – 要加载的语言环境，如果需要。
- 返回值:
Promise.<对象> – 规范化的清单。
- Extension.getManifestOrigins()¶
- 返回值:
Array.<字符串> – 清单中通过 permissions、host_permissions 或 content_scripts 键引用的所有来源。
- Extension.getManifestOriginsMatchPatternSet()¶
- 返回值:
MatchPatternSet – 仅针对清单中通过 permissions、host_permissions 或 content_scripts 键引用的来源的 MatchPatternSet。
- Extension.getRequestedPermissions()¶
返回扩展根据其清单请求的其他权限。目前，这是 mv3 中的 host_permissions（和内容脚本）。
- Extension.getRequiredPermissions()¶
返回一个对象，表示扩展根据清单文件中的固定属性可以访问的任何功能。结果包含“permissions”属性的内容以及从清单文件字段派生的其他功能，用户应该被告知这些功能（例如，注入内容脚本的来源）。
对于具有来源控制的 MV3 扩展，这并不包括来源。
- Extension.getURL(path)¶
返回此扩展程序中给定路径的 moz-extension: URL。
除非 id 或 uuid 属性已设置，否则不得调用此方法。
- 参数:
path (string) – URL 的路径部分。
- 返回值:
string –
- Extension.manifestError(message)¶
报告有关扩展程序清单文件错误。
- 参数:
message (string) – 错误消息
- Extension.manifestWarning(message)¶
报告有关扩展程序清单文件的警告。
- 参数:
message (string) – 警告消息
- Extension.permissionsObject(permissionsArray, hostPermissions)¶
给定一个主机和权限数组，生成一个结构化的权限对象，其中包含单独的主机来源和权限数组。
- 参数:
permissionsArray (Array)
hostPermissions (Array)
- 返回值:
object – 权限对象
- Extension.serializeExtended()¶
扩展序列化数据，仅在扩展进程中需要，并且永远不会在 Web 内容进程中反序列化。与 @see {ExtensionChild} 保持同步。
- Extension.updatePermissions(reason)¶
根据需要更新站点权限。
- 参数:
reason (string) – 如果提供，则为 BOOTSTRAP_REASON 字符串。如果 reason 未定义，则正在添加或删除附加组件权限，这可能会影响站点权限。
EventManager 类¶
- class EventManager(params)¶
这是一个用于管理事件侦听器的通用类。
示例
new EventManager({ context, name: "api.subAPI", register: fire => { let listener = (...) => { // Fire any listeners registered with addListener. fire.async(arg1, arg2); }; // Register the listener. SomehowRegisterListener(listener); return () => { // Return a way to unregister the listener. SomehowUnregisterListener(listener); }; } }).api() The result is an object with addListener, removeListener, and hasListener methods. `context` is an add-on scope (either an ExtensionContext in the chrome process or ExtensionContext in a content process).
BaseContext 类¶
- class BaseContext()¶
此类包含我们关于单个扩展的信息。它永远不会直接实例化，而是每个进程类型的子类扩展此类并添加与该进程相关的成员。
- BaseContext.BaseContext¶
- BaseContext.cloneScope¶
类型: 对象
- BaseContext.isTopContext¶
类型: 布尔值
- BaseContext.principal¶
类型: nsIPrincipal
- BaseContext.useWebIDLBindings¶
扩展上下文是否正在使用 WebIDL 绑定用于 WebExtensions API。在子类（例如 WorkerContextChild）中覆盖，并在 ExtensionAPI 类中可选地用于自定义 API 的行为，当对扩展 API 的调用源自 WebIDL 绑定时。
- BaseContext.viewType¶
类型：string
- BaseContext.close()¶
unload() 的简单代理，用于与 callOnClose() 一起使用。
- BaseContext.getCaller()¶
捕获属于扩展程序的最新堆栈帧。
- 返回值:
nsIStackFrame –
- BaseContext.jsonStringify(...args)¶
安全地对来自扩展程序的对象调用 JSON.stringify()。
- 返回值:
string – obj 的字符串化表示形式
- BaseContext.normalizeError(error, caller)¶
规范化给定的错误对象以供目标作用域使用。如果目标是属于该作用域的错误对象，则按原样返回。如果它是一个具有 message 属性的普通对象，则将其转换为属于目标作用域的错误。如果它是一个不属于克隆作用域的 Error 对象，则会报告它，并将其转换为意外异常错误。
- 参数:
error (Error|object)
caller (nsIStackFrame)
- 返回值:
Error –
- BaseContext.openConduit(subject, address)¶
打开与该上下文链接的管道，填充相关的地址字段。仅在具有关联 contentWindow 的子上下文中可用。
- BaseContext.withLastError(error, caller, callback)¶
将 .lastError 的值设置为 error，调用给定的回调，并在回调返回时未检查该值的情况下报告错误。
- 参数:
error (object) – 一个具有 message 属性的对象。可以是属于目标作用域的 Error 对象。
caller (nsIStackFrame) – 触发此回调的可选调用者帧，用于错误报告。
callback (function) – 要调用的回调。
- 返回值:
* – 回调的返回值。
- BaseContext.wrapPromise(promise, callback=null)¶
包装给定的 promise，以便可以安全地将其返回到此上下文中的扩展代码。
但是，如果提供了 callback，则将其用作 promise 的完成函数，并且不返回任何 promise。在这种情况下，当 promise 成功或失败时调用回调。在后一种情况下，lastError 设置为拒绝值，并且回调函数必须检查 browser.runtime.lastError 或 extension.runtime.lastError 以防止将其报告到控制台。
- 参数:
promise (Promise) – 要用其包装回调的 promise。可以解析为 SpreadArgs 实例，在这种情况下，每个元素都将用作单独的参数。除非 promise 对象属于 cloneScope 全局对象，否则在调用 callback 函数或解析包装的 promise 之前，其解析值会克隆到 cloneScope 中。
callback (function) – 要包装的回调函数
- 返回值:
Promise|undefined – 如果回调为 null，则为属于目标作用域的 promise 对象。否则为 undefined。
WindowManager 类¶
- class WindowManagerBase(extension)¶
管理特定扩展程序的原生浏览器窗口及其包装器。
- 参数:
extension (Extension) – 要管理窗口的扩展程序。
- WindowManagerBase.canAccessWindow(window, context)¶
返回扩展程序在给定上下文中是否可以访问此窗口。
- 参数:
window (DOMWindow) – 正在测试的浏览器窗口
context (BaseContext|null) – 执行此测试的扩展程序上下文。
- 返回值:
boolean –
- WindowManagerBase.convert(window, ...args)¶
将给定的浏览器窗口转换为 JSON 兼容的对象，采用 WebExtension API 需要返回的格式，可以安全地传递给扩展程序代码。
- 参数:
window (DOMWindow) – 要转换的浏览器窗口。
args (*) – 要传递给 {@link WindowBase#convert} 的其他参数。
- 返回值:
object –
- WindowManagerBase.get(_windowId, _context)¶
返回给定 ID 的浏览器窗口的 WindowBase 包装器。
- 参数:
_windowId (integer) – 要返回包装器的浏览器窗口的 ID。
_context (BaseContext) – 执行匹配的扩展程序上下文。用于确定相关属性的当前窗口。
- 抛出:
ExtensionError – 如果不存在具有给定 ID 的窗口。
- 返回值:
WindowBase –
- WindowManagerBase.getAll()¶
返回每个当前存在的浏览器窗口的 WindowBase 包装器的迭代器。
- 返回值:
Iterator.<WindowBase> –
- WindowManagerBase.getWrapper(window)¶
返回此扩展程序的给定浏览器窗口的 WindowBase 包装器。此方法将始终为任何给定的浏览器窗口返回相同的包装器对象。
- 参数:
window (DOMWindow) – 要返回包装器的浏览器窗口。
- 返回值:
WindowBase|undefined – 此选项卡的包装器。
- WindowManagerBase.query(queryInfo=null, context=null)¶
返回与给定查询信息匹配的 WindowBase 对象的迭代器。
- 参数:
queryInfo (object|null) – 包含要过滤的属性的对象。可以包含 {@link WindowBase#matches} 识别的任何属性。未知属性将被忽略。
context (BaseContext|null) – 执行匹配的扩展上下文。用于确定相关属性的当前窗口。
- 返回值:
Iterator.<WindowBase> –
- WindowManagerBase.wrapWindow(_window)¶
返回一个新的 WindowBase 实例，包装给定的浏览器窗口。
- 参数:
_window (DOMWindow) – 要返回包装器的浏览器窗口。
- 返回值:
WindowBase –
TabManager 类¶
- class TabManagerBase(extension)¶
管理特定扩展的原生标签、它们的包装器及其动态权限。
- 参数:
extension (Extension) – 要管理标签的扩展。
- TabManagerBase.activateScripts(nativeTab)¶
如果扩展具有 activeTab 权限或（未授予的）主机权限，则激活 MV3 内容脚本。
- 参数:
nativeTab (NativeTab)
- TabManagerBase.addActiveTabPermission(nativeTab)¶
如果扩展已请求 activeTab 权限，则在给定原生标签中的当前内部窗口授予其这些权限。
- 参数:
nativeTab (NativeTab) – 要授予权限的原生标签。
- TabManagerBase.canAccessTab(_nativeTab)¶
使用扩展上下文确定访问权限。
- 参数:
_nativeTab (NativeTab) – 要检查访问权限的标签。
- 返回值:
boolean – 如果扩展对此标签具有权限，则为 True。
- TabManagerBase.convert(nativeTab, fallbackTabSize=null)¶
将给定的原生标签转换为 JSON 兼容的对象，格式要求 WebExtension API 返回，可以安全地传递给扩展代码。
- 参数:
nativeTab (NativeTab) – 要转换的原生标签。
fallbackTabSize (object) – 如果此标签的延迟几何数据尚未初始化，则为几何数据。
- 返回值:
object –
- TabManagerBase.get(_tabId)¶
返回具有给定 ID 的标签的 TabBase 包装器。
- 参数:
_tabId (integer) – 要返回包装器的标签的 ID。
- 抛出:
ExtensionError – 如果不存在具有给定 ID 的标签。
- 返回值:
TabBase –
- TabManagerBase.getWrapper(nativeTab)¶
返回此扩展对给定原生标签的 TabBase 包装器。此方法将始终为任何给定的原生标签返回相同的包装器对象。
- 参数:
nativeTab (NativeTab) – 要返回包装器的标签。
- 返回值:
TabBase|undefined – 此标签的包装器。
- TabManagerBase.hasActiveTabPermission(nativeTab)¶
如果扩展已请求 activeTab 权限，并且已在此标签的当前内部窗口授予权限，则返回 true。
- 参数:
nativeTab (NativeTab) – 要检查权限的原生标签。
- 返回值:
boolean – 如果扩展对此标签具有 activeTab 权限，则为 True。
- TabManagerBase.hasTabPermission(nativeTab)¶
如果扩展具有访问给定原生标签的受限属性的权限，则返回 true。实际上，这意味着它已请求“tabs”权限或对给定标签具有 activeTab 权限。
注意：不要对不是当前平台的原生标签的对象使用此方法：此方法隐式地为传递的 nativeTab 参数生成一个包装器，并且特定于平台的 tabTracker 实例可能会将其存储在一个映射中，该映射仅在标签关闭时清除（因此，如果 nativeTab 不是真正的原生标签，它将永远不会从特定于平台的 tabTracker 实例中清除），请参阅 Bug 1458918 以了解其原理。
- 参数:
nativeTab (NativeTab) – 要检查权限的原生标签。
- 返回值:
boolean – 如果扩展对此标签具有权限，则为 True。
- TabManagerBase.query(queryInfo=null, context=null)¶
返回与给定查询信息匹配的 TabBase 对象的迭代器。
- TabManagerBase.revokeActiveTabPermission(nativeTab)¶
撤销扩展对给定原生标签的当前内部窗口的 activeTab 权限。
- 参数:
nativeTab (NativeTab) – 要撤销权限的原生标签。
- TabManagerBase.wrapTab(_nativeTab)¶
返回一个新的 TabBase 实例，包装给定的原生标签。
- 参数:
_nativeTab (NativeTab) – 要返回包装器的原生标签。
- 返回值:
TabBase –