MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-survey

Modules

runtime.onMessage

Utilisez cet événement pour écouter les messages d'une autre partie de votre  extension. Par exemple, vous pouvez l'utiliser :
 
  • dans un script de contenu, pour écouter les messages d'un script en arrière-plan
  • dans un script en arrière-plan, pour écouter les messages d'un script de contenu
  • dans une page d'options ou un script popup, pour éctouer les messages d'un script d'arrière-plan
  • dans un script d'arrière plan, pour écouter les messages d'une page d'options ou d'un script contextuel

Pour envoyer un message qui sera reçu par le module d'écoute onMessage, utilisez  runtime.sendMessage() ou (pour envoyer un message à un script de contenu) tabs.sendMessage().

Avec le message lui-même, l'écouteur est transmis :

  • Un objet sender donnant les détails sur l'expéditeur du message
  • Une fonction sendResponse qu'ellt peut utiliser pour renvoyer une réponse à l'expéditeur.

Vous pouvez envoyer une réponse synchrone au message en appelant la fonction  sendResponse dans votre écouteur. Voir un exemple.

Pour envoyer un réponse asynchrone, il existe deux options :

  • Renvoie true à partir de l'écouteur d'événement. Cela permet de conserver la fonction sendResponse après le retour de l'écouteur, ce qui vous permet de l'appeler plus tard. Voir un exemple.
  • Renvoie une Promise ) à partir de l'écouteur d'événement et la résout lorsque vous avez la réponse (ou la rejette en cas d'erreur). Voir un exemple.

Dans les versions de Firefox antérieures à la version 51, l'écouteur  runtime.onMessage sera appelé pour les messages envoyés à parti du même script (par exemple, les messages envoyés par le script d'arrière-plan seront également reçus par le script d'arrière-plan). Dans ces versions de Firefox, si vous appelez inconditionnellement runtime.sendMessage() depuis un écouteur  runtime.onMessage, vous allez créer une boucle infinie qui maximisera le CPU et verrouillera Firefox. Si vous devez appeler runtime.sendMessage() depuis runtime.onMessage, vous devez vérifier la propriété sender.url pour vérifier que vous n'envoyez pas de message en réponse à un message envoyé à partir du même script. Ce bug a été résolu à partir de Firefox 51.

Syntaxe

browser.runtime.onMessage.addListener(listener)
browser.runtime.onMessage.removeListener(listener)
browser.runtime.onMessage.hasListener(listener)

Les événements ont trois fonctions:

addListener(callback)
Ajoute un écouteur à cet événement.
removeListener(listener)
Arrêtez d'écouter cet événement. L'argument listener est l'écouteur à supprimer.
hasListener(listener)
Vérifie si un listener est enregistré pour cet événement. Retourne true s'il écoute, false sinon.

Syntaxe addListener

Paramètres

function

Une fonction d'écouteur qui sera appelée lorsque cet événement se produira. La fonction recevra les arguments suivants :

message
object. Le message lui-même. C'est un objet JSON-ifiable.
sender
Un objet runtime.MessageSender représentant l'expéditeur du message.
sendResponse

Une fonction à appeler, plus d'une fois, pour envoyer une réponse au message. La fonction prend un seul argument, qui peut être n'importe quel objet JSON-ifiable. Cet argument est renvoyé à l'expéditeur du message.

Si vous avez plus d'un écouteur onMessage dans le même document, un seul peut envoyer une réponse.

Pour envoyer une réponse de manière synchrone, appelez sendResponse avant l'écouteur de la fonction de renvoie. Pour envoyer une réponse de manière asynchrone :

  • soit gardez une référence à l'argument sendResponse et renvoyez true à partir de la fonction d'écouteur. Vous pourrez ensuite appeler sendResponse après le retour de la fonction d'écouteur.
  • ou renvoyer une Promise de la fonction d'écouteur et résoudre la promesse lorsque la réponse est prête.

La fonction d'écouteur peut renvoyer un booléen ou une Promise.

Compatibilité du navigateur

ChromeEdgeFirefoxFirefox for AndroidOpera
Support simple26 Oui454815

Exemples

Exemple simple

Ce script de contenu est à l'écoute des événements de clic dans la page Web. Si le clic était sur un lien, il affiche la page d'arrière-plan avec l'URL cible:

// content-script.js

window.addEventListener("click", notifyExtension);

function notifyExtension(e) {
  if (e.target.tagName != "A") {
    return;
  }
  browser.runtime.sendMessage({"url": e.target.href});
}

Le script d'arrière-plan écoute ces messages et affiche une notification à l'aide de l'API   notifications :

// background-script.js

browser.runtime.onMessage.addListener(notify);

function notify(message) {
  browser.notifications.create({
    "type": "basic",
    "iconUrl": browser.extension.getURL("link.png"),
    "title": "You clicked a link!",
    "message": message.url
  });
}

Envoyer une réponse asynchrone

Le script de contenu envoie un message au script d'arrière plan lorsque l'utilisateur clique sur la page. Il enregistre également toute réponse envoyé par le script d'arrière plan :

// content-script.js

function handleResponse(message) {
  console.log(`background script sent a response: ${message.response}`);
}

function handleError(error) {
  console.log(`Error: ${error}`);
}

function sendMessage(e) {
  var sending = browser.runtime.sendMessage({content: "message from the content script"});
  sending.then(handleResponse, handleError);  
}

window.addEventListener("click", sendMessage);

Voici une version du script d'arrière-plan correspondant, qui envoie une réponse de manière synchrone depuis l'intérieur de l'écouteur :

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  sendResponse({response: "response from background script"});
}

browser.runtime.onMessage.addListener(handleMessage);

Envoi d'une réponse asynchrone à l'aide de sendResponse

Voici un autre version du script d'arrière-plan de l'exemple précédent. Il envoie une réponse de manière asynchrone, après le retour de l'écouteur. Remarque return true; dans l'écouteur : cela indique au navigateur que vous avez l'intention d'utiliser l'argument  sendResponse après le retour de l'écouteur.

// background-script.js

function handleMessage(request, sender, sendResponse) {  
  console.log(`content script sent a message: ${request.content}`);
  setTimeout(() => {
    sendResponse({response: "async response from background script"});
  }, 1000);  
  return true;
}

browser.runtime.onMessage.addListener(handleMessage);

Envoi d'une réponse asynchrone à l'aide d'une Promise

Voici un script de contenu qui obtient le premier lien <a> dans la page, et envoie un message demandant si l'emplacement du lien est mis en signet. Il s'attend à obtenir un booléen en réponse : true si l'emplacement est mis en signet, false sinon :

// content-script.js

const firstLink = document.querySelector("a");

function handleResponse(isBookmarked) {
  if (isBookmarked) {
    firstLink.classList.add("bookmarked");
  }
}

browser.runtime.sendMessage({
  url: firstLink.href
}).then(handleResponse);

Voici le script d'arrière plan. Il utilise bookmarks.search() pour voir si le lien est bookmarké, ce qui renvoie une Promise:

// background-script.js

function isBookmarked(message, sender, response) {
  return browser.bookmarks.search({
    url: message.url
  }).then(function(results) {
    return results.length > 0;
  });
}

browser.runtime.onMessage.addListener(isBookmarked);

Si le gestionnaire asynchrone ne renvoie pas de promesse, vous pouvez explicitement construire une promesse. Cet exemple plutôt artificiel envoie une réponse après un délai d'une seconde, en utilisant Window.setTimeout():

// background-script.js

function handleMessage(request, sender, sendResponse) {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve({response: "async response from background script"});
    }, 1000);
  });
}

browser.runtime.onMessage.addListener(handleMessage);

Example extensions

Remerciements :

Cette API est basée sur l'API Chromium chrome.runtime. Cette documentation est dérivée de runtime.json dans le code de Chromium code.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : hellosct1
 Dernière mise à jour par : hellosct1,