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 d’arrière-plan ;
  • dans un script d’arrière-plan, pour écouter les messages d’un script de contenu ;
  • dans une page d’options ou un script de popup, pour écouter 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 de popup.

Pour envoyer un message qui sera reçu par l’écouteur onMessage, utilisez runtime.sendMessage() ou (pour envoyer un message à un script de contenu) tabs.sendMessage().

Avec le message lui-même, l’écouteur reçoit en paramètres :

  • Un objet sender donnant les détails sur l’expéditeur du message ;
  • Une fonction sendResponse qu’il 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 :

  • Renvoyer 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.
  • Renvoyer une Promise depuis l’écouteur d’événement, et la résoudre lorsque vous avez la réponse (ou la rejeter en cas d’erreur). Voir un exemple.

Retourner une Promise est maintenant le moyen préféré car sendResponse sera retirée de la spécification W3C. La bibliothèque populaire webextension-polyfill a déjà supprimé cette fonction de son implémentation.

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 poussera le CPU au maximum et bloquera Firefox. Si vous devez appeler runtime.sendMessage() depuis runtime.onMessage, vous devez examiner 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)
Cesse 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 de addListener

Paramètres

function

Une fonction d’écoute 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, au plus 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.

La documentation anglaise, faisant référence, indique “A function to call, at most once, to send a response to the message” – ce qui se traduit par « au plus une fois », c’est-à-dire qu’un seul appel à cette fonction est admis – sans pour autant qu’un appel supplémentaire lève une erreur. Cela peut provoquer une erreur logique difficile à résoudre.
Dans le cas où vous souhaitez utiliser des retours multiples et asynchrones (par exemple provenant d’IndexedDB), il est préférable de renvoyer une réponse de principe et de faire usage d’autres outils de transfert de messages.

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 le retour de la fonction d’écoute. 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.
  • soit renvoyez une promesse depuis la fonction d’écoute, et résolvez la promesse lorsque la réponse est prête. Il s’agit du moyen privilégié.

La fonction d’écoute peut renvoyer un booléen ou une promesse.

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxOperaFirefox pour Android
onMessageChrome Support complet 26Edge Support complet 14Firefox Support complet 45Opera Support complet 15Firefox Android Support complet 48
Respond with PromiseChrome Aucun support NonEdge Aucun support NonFirefox Support complet OuiOpera Aucun support NonFirefox Android Support complet Oui

Légende

Support complet  
Support complet
Aucun support  
Aucun support

Exemples

Exemple simple

Ce script de contenu écoute les événements clic dans la page web. Si le clic a eu lieu sur un lien, il envoie un message à 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": "Vous avez cliqué sur un lien !",
    "message": message.url
  });
}

Envoyer une réponse synchrone

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

// content-script.js

function handleResponse(message) {
  console.log(`le script d’arrière-plan a répondu : ${message.response}`);
}

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

function sendMessage(e) {
  var sending = browser.runtime.sendMessage({content: "message du script de contenu"});
  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(`le script de contenu a envoyé un message : ${request.content}`);
  sendResponse({response: "réponse du script d’arrière-plan"});
}

browser.runtime.onMessage.addListener(handleMessage);

Et voici une autre version, qui utilise Promise.resolve() :

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`le script de contenu a envoyé un message : ${request.content}`);
  return Promise.resolve({response: "réponse du script d’arrière-plan"});
}

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. Remarquez le 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(`le script de contenu a envoyé un message : ${request.content}`);
  setTimeout(() => {
    sendResponse({response: "réponse asynchrone du script d’arrière-plan"});
  }, 1000);
  return true;
}

browser.runtime.onMessage.addListener(handleMessage);

Envoi d’une réponse asynchrone à l’aide d’une promesse

Ce script de contenu reçoit le premier lien <a> dans la page, et envoie un message demandant si l’emplacement du lien fait partie des marque-pages. Il attend comme réponse un booléen : true si l’emplacement est dans les marque-pages, 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 dans les marque-pages, ce qui renvoie une promesse :

// 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: "réponse asynchrone du script d’arrière-plan"});
    }, 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 : Watilin, ariasuni, mdnwebdocs-bot, hellosct1, Nothus
Dernière mise à jour par : Watilin,