WebExtensions Javascript Component Reference

This page contains reference documentation for the individual classes used to implement WebExtensions APIs. This documentation is generated from jsdoc comments in the source code.

ExtensionAPI class

class ExtensionAPI(extension)

Base class for WebExtension APIs. Each API creates a new class that inherits from this class, the derived class is instantiated once for each extension that uses the API.

Extension class

class Extension(addonData, startupReason)

We create one instance of this class per extension. |addonData| comes directly from bootstrap.js when initializing.

Extension.callOnClose(obj)

Call the close() method on the given object when this extension is shut down. This can happen during browser shutdown, or when an extension is manually disabled or uninstalled.

Arguments:
  • obj (object) – An object on which to call the close() method when this extension is shut down.
Extension.getURL(path)

Returns the moz-extension: URL for the given path within this extension.

Must not be called unless either the id or uuid property has already been set.

Arguments:
  • path (string) – The path portion of the URL.
Returns:

string –
Extension.manifestError(message)

Report an error about the extension’s manifest file.

Arguments:
  • message (string) – The error message
Extension.manifestWarning(message)

Report a warning about the extension’s manifest file.

Arguments:
  • message (string) – The warning message

EventManager class

class EventManager(context, name, register)

This is a generic class for managing event listeners.

Arguments:
  • context (BaseContext) – An object representing the extension instance using this event.
  • name (string) – A name used only for debugging.
  • register (functon) – A function called whenever a new listener is added.

BaseContext class

class BaseContext(envType, extension)

This class contains the information we have about an individual extension. It is never instantiated directly, instead subclasses for each type of process extend this class and add members that are relevant for that process.

BaseContext.close()

A simple proxy for unload(), for use with callOnClose().

BaseContext.jsonStringify(args)

Safely call JSON.stringify() on an object that comes from an extension.

Arguments:
  • args (array.<any>) – Arguments for JSON.stringify()
Returns:

string – The stringified representation of obj
BaseContext.normalizeError(error)

Normalizes the given error object for use by the target scope. If the target is an error object which belongs to that scope, it is returned as-is. If it is an ordinary object with a message property, it is converted into an error belonging to the target scope. If it is an Error object which does not belong to the clone scope, it is reported, and converted to an unexpected exception error.

Arguments:
  • error (Error|object) –
Returns:

Error –
BaseContext.sendMessage(target, messageName, data, options)

A wrapper around MessageChannel.sendMessage which adds the extension ID to the recipient object, and ensures replies are not processed after the context has been unloaded.

Arguments:
  • target (nsIMessageManager) –
  • messageName (string) –
  • data (object) –
  • options (object) –
  • options.sender (object) –
  • options.recipient (object) –
Returns:

Promise –
BaseContext.withLastError(error, callback)

Sets the value of .lastError to error, calls the given callback, and reports an error if the value has not been checked when the callback returns.

Arguments:
  • error (object) – An object with a message property. May optionally be an Error object belonging to the target scope.
  • callback (function) – The callback to call.
Returns:

* – The return value of callback.
BaseContext.wrapPromise(promise, callback)

Wraps the given promise so it can be safely returned to extension code in this context.

If callback is provided, however, it is used as a completion function for the promise, and no promise is returned. In this case, the callback is called when the promise resolves or rejects. In the latter case, lastError is set to the rejection value, and the callback function must check browser.runtime.lastError or extension.runtime.lastError in order to prevent it being reported to the console.

Arguments:
  • promise (Promise) – The promise with which to wrap the callback. May resolve to a SpreadArgs instance, in which case each element will be used as a separate argument. Unless the promise object belongs to the cloneScope global, its resolution value is cloned into cloneScope prior to calling the callback function or resolving the wrapped promise.
  • callback (function) – The callback function to wrap
Returns:

Promise|undefined – If callback is null, a promise object belonging to the target scope. Otherwise, undefined.

WindowManager class

class WindowManagerBase(extension)

Manages native browser windows and their wrappers for a particular extension.

Arguments:
  • extension (Extension) – The extension for which to manage windows.
WindowManagerBase.convert(window, args)

Converts the given browser window to a JSON-compatible object, in the format requried to be returned by WebExtension APIs, which may be safely passed to extension code.

Arguments:
  • window (DOMWindow) – The browser window to convert.
  • args (*) – Additional arguments to be passed to {@link WindowBase#convert}.
Returns:

Object –
WindowManagerBase.get(windowId, context)

Returns a WindowBase wrapper for the browser window with the given ID.

Arguments:
  • id (integer) – The ID of the browser window for which to return a wrapper.
  • context (BaseContext) – The extension context for which the matching is being performed. Used to determine the current window for relevant properties.
Throws:

ExtensionError – If no window exists with the given ID.
WindowManagerBase.getAll()

Returns an iterator of WindowBase wrappers for each currently existing browser window.

Returns:Iterator.<WindowBase> –
WindowManagerBase.getWrapper(window)

Returns this extension’s WindowBase wrapper for the given browser window. This method will always return the same wrapper object for any given browser window.

Arguments:
  • window (DOMWindow) – The browser window for which to return a wrapper.
Returns:

WindowBase – The wrapper for this tab.
WindowManagerBase.query(queryInfo, context)

Returns an iterator of WindowBase objects which match the given query info.

Arguments:
  • queryInfo (Object|null) – An object containing properties on which to filter. May contain any properties which are recognized by {@link WindowBase#matches}. Unknown properties will be ignored.
  • context (BaseContext|null) – The extension context for which the matching is being performed. Used to determine the current window for relevant properties.
Returns:

Iterator.<WindowBase> –
WindowManagerBase.wrapWindow(window)

Returns a new WindowBase instance wrapping the given browser window.

Arguments:
  • window (DOMWindow) – The browser window for which to return a wrapper.
Returns:

WindowBase –

TabManager class

class TabManagerBase(extension)

Manages native tabs, their wrappers, and their dynamic permissions for a particular extension.

Arguments:
  • extension (Extension) – The extension for which to manage tabs.
TabManagerBase.addActiveTabPermission(nativeTab)

If the extension has requested activeTab permission, grant it those permissions for the current inner window in the given native tab.

Arguments:
  • nativeTab (NativeTab) – The native tab for which to grant permissions.
TabManagerBase.convert(nativeTab, fallbackTab)

Converts the given native tab to a JSON-compatible object, in the format requried to be returned by WebExtension APIs, which may be safely passed to extension code.

Arguments:
  • nativeTab (NativeTab) – The native tab to convert.
  • fallbackTab (NativeTab) – A tab to retrieve geometry data from if the lazy geometry data for this tab hasn’t been initialized yet.
Returns:

Object –
TabManagerBase.get(tabId)

Returns a TabBase wrapper for the tab with the given ID.

Arguments:
  • id (integer) – The ID of the tab for which to return a wrapper.
Throws:

ExtensionError – If no tab exists with the given ID.
Returns:

TabBase –
TabManagerBase.getWrapper(nativeTab)

Returns this extension’s TabBase wrapper for the given native tab. This method will always return the same wrapper object for any given native tab.

Arguments:
  • nativeTab (NativeTab) – The tab for which to return a wrapper.
Returns:

TabBase – The wrapper for this tab.
TabManagerBase.hasActiveTabPermission(nativeTab)

Returns true if the extension has requested activeTab permission, and has been granted permissions for the current inner window if this tab.

Arguments:
  • nativeTab (NativeTab) – The native tab for which to check permissions.
Returns:

boolean – True if the extension has activeTab permissions for this tab.
TabManagerBase.hasTabPermission(nativeTab)

Returns true if the extension has permissions to access restricted properties of the given native tab. In practice, this means that it has either requested the “tabs” permission or has activeTab permissions for the given tab.

Arguments:
  • nativeTab (NativeTab) – The native tab for which to check permissions.
Returns:

boolean – True if the extension has permissions for this tab.
TabManagerBase.query(queryInfo, context)

Returns an iterator of TabBase objects which match the given query info.

Arguments:
  • queryInfo (Object|null) – An object containing properties on which to filter. May contain any properties which are recognized by {@link TabBase#matches} or {@link WindowBase#matches}. Unknown properties will be ignored.
  • context (BaseContext|null) – The extension context for which the matching is being performed. Used to determine the current window for relevant properties.
Returns:

Iterator.<TabBase> –
TabManagerBase.revokeActiveTabPermission(nativeTab)

Revoke the extension’s activeTab permissions for the current inner window of the given native tab.

Arguments:
  • nativeTab (NativeTab) – The native tab for which to revoke permissions.