content/worker
This module is used in the internal implementation of SDK modules
which use
content scripts to interact with web content,
such as the panel
or page-mod
modules.
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.
API Reference
Classes
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.
Example
var workers = require("sdk/content/worker");
let worker = workers.Worker({
window: require("sdk/window/utils").getMostRecentBrowserWindow(),
contentScript:
"self.port.on('hello', function(name) { " +
" self.port.emit('response', window.location.href); " +
"});"
});
worker.port.emit("hello", { name: "worker"});
worker.port.on("response", function (location) {
console.log(location);
});
Constructors
Worker(options)
Creates a content worker.
Options for the constructor, with the following keys:
The content window to create JavaScript sandbox for communication with.
The local file URLs of content scripts to load. Content scripts specified
by this option are loaded before those specified by the contentScript
option. Optional.
The texts of content scripts to load. Content scripts specified by this
option are loaded after those specified by the contentScriptFile
option.
Optional.
Functions that will registered as a listener to a 'message' events.
Functions that will registered as a listener to an 'error' events.
Methods
postMessage(data)
Asynchronously emits "message"
events in the enclosed worker, where content
script was loaded.
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 : EventEmitter
EventEmitter object that allows you to:
- send customized messages to the worker using the
port.emit
function - receive events from the worker using the
port.on
function
url : string
The URL of the content.
tab : object
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.
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.
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.