Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Unstable
Used in the internal implementation of SDK modules which use content scripts to interact with web content.
It exports the Worker trait, which enables content scripts and the add-on code to exchange messages using the port or postMessage APIs.
The Worker is similar to the web worker interface defined by the W3C. But unlike "web workers," these workers run in the same process as web content and browser chrome, so code within workers can block the UI.
Globals
Constructors
Worker(options)
Creates a content worker.
Parameters
options : object
Required options:
| Name | Type | |
|---|---|---|
| window | object |
The content window to create JavaScript sandbox for communication with. |
Optional options:
| Name | Type | |
|---|---|---|
| contentScriptFile | string,array |
The local file URLs of content scripts to load. Content scripts specified by this option are loaded before those specified by the |
| contentScript | string,array |
The texts of content scripts to load. Content scripts specified by this option are loaded after those specified by the |
| onMessage | function |
Functions that will registered as a listener to a 'message' events. |
| onError | function |
Functions that will registered as a listener to an 'error' events. |
Worker
Worker is composed from the EventEmitter trait, therefore instances of Worker and their descendants expose all the public properties exposed by EventEmitter along with additional public properties that are listed below.
Methods
postMessage(data)
Asynchronously emits "message" events in the enclosed worker, where content script was loaded.
Parameters
data : number,string,JSON
The data to send. Must be stringifiable to JSON.
destroy()
Destroy the worker by removing the content script from the page and removing all registered listeners. A detach event is fired just before removal.
Properties
port
Object that allows you to:
- send customized messages to the worker using the
port.emitfunction - receive events from the worker using the
port.onfunction
url
The URL of the content.
tab
If this worker is attached to a content document, returns the related tab.
Events
message
This event allows the content worker to receive messages from its associated content scripts. Calling the self.postMessage() function from a content script will asynchronously emit the message event on the corresponding worker.
Arguments
value : The event listener is passed the message, which must be a JSON-serializable value.
error
This event allows the content worker to react to an uncaught runtime script error that occurs in one of the content scripts.
Arguments
Error : The event listener is passed a single argument which is an Error object.
detach
This event is emitted when the document associated with this worker is unloaded or the worker's destroy() method is called.
Note that you can't communicate with the content script in response to this event. If you try, you'll see this error:
Error: Couldn't find the worker to receive this message. The script may not be initialized yet, or may already have been unloaded
You can handle the detach event in the content script itself though:
// in content script
self.port.on("detach", function() {
window.close();
});