runtime.Port

Type

Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :

name

string. Le nom du port, défini dans runtime.connect() ou tabs.connect() appel qui l'a créé. Si ce port est connecté à une application native, son nom est le nom de l'application native.

disconnect

function. Déconnecte un port. Chaque extrémité peut appeler cela quand ils ont fini avec le port. Cela provoquera le déclenchement de onDisconnect à l'autre extrémité. Ceci est utile si l'autre extrémité maintient un état relatif à ce port, qui peut être nettoyé lors de la déconnexion. Si ce port est connecté à une application native, cette fonction ferme l'application native.

error

object. Si le port a été déconnecté en raison d'une erreur, il sera défini sur un objet avec un message, de propriété de chaîne, vous donnant plus d'informations sur l'erreur. Voir onDisconnect.

onDisconnect

object. Cela contient les fonctions addListener() et removeListener() communes à tous les événements pour les extensions créées à l'aide des API. WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura appelé Port.disconnect(). Cet événement ne sera déclenché qu'une fois pour chaque port. La fonction d'écouteur recevra l'objet Port. Si le port a été déconnecté en raison d'une erreur, l'argument Port contiendra une propriété error donnant plus d'informations sur l'erreur :

js

port.onDisconnect.addListener((p) => {
  if (p.error) {
    console.log(`Disconnected due to an error: ${p.error.message}`);
  }
});

Notez que dans Google Chrome port.error n'est pas supporté: utilisez plutôt runtime.lastError pour obtenir le message d'erreur.

onMessage

object. Cela contient les fonctions addListener() et removeListener() communes à tous les événements pour les extensions créées à l'aide des API WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura envoyé un message à ce port. L'écouteur recevra l'objet JSON envoyé par l'autre extrémité.

postMessage

function. Envoyer un message à l'autre extrémité. Cela prend un argument, qui est un objet JSON représentant le message à envoyer. Il sera fourni à tout script écoutant l'événement onMessage du port, ou à l'application native si ce port est connecté à une application native.

senderFacultatif

runtime.MessageSender. Contient des informations sur l'expéditeur du message. ette propriété ne sera présente que sur les ports transmis aux écouteurs onConnect/onConnectExternal.

Compatibilité des navigateurs

Exemples

Connecting from content scripts

This content script:

• connects to the background script and stores the Port in a variable called myPort.
• listens for messages on myPort and logs them.
• sends messages to the background script, using myPort, when the user clicks the document.

// content-script.js

var myPort = browser.runtime.connect({ name: "port-from-cs" });
myPort.postMessage({ greeting: "hello from content script" });

myPort.onMessage.addListener(function (m) {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", function () {
  myPort.postMessage({ greeting: "they clicked the page!" });
});

The corresponding background script:

• listens for connection attempts from the content script.

• when it receives a connection attempt:

  • stores the port in a variable named portFromCS.
  • sends the content script a message using the port.
  • starts listening to messages received on the port, and logs them.

• sends messages to the content script, using portFromCS, when the user clicks the extension's browser action.

// background-script.js

var portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({ greeting: "hi there content script!" });
  portFromCS.onMessage.addListener(function (m) {
    console.log("In background script, received message from content script");
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(function () {
  portFromCS.postMessage({ greeting: "they clicked the button!" });
});

Script à contenu multiple

Si plusieurs scripts de contenu communiquent en même temps, vous voudrez peut-être stocker chaque connexion dans un tableau.

// background-script.js

var ports = [];

function connected(p) {
  ports[p.sender.tab.id] = p;
  //...
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(function () {
  ports.forEach((p) => {
    p.postMessage({ greeting: "they clicked the button!" });
  });
});

Connecting to native applications

This example connects to the native application "ping_pong" and starts listening for messages from it. It also sends the native application a message when the user clicks a browser action icon:

/*
On startup, connect to the "ping_pong" app.
*/
var port = browser.runtime.connectNative("ping_pong");

/*
Listen for messages from the app.
*/
port.onMessage.addListener((response) => {
  console.log("Received: " + response);
});

/*
On a click on the browser action, send the app a message.
*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending:  ping");
  port.postMessage("ping");
});