--- title: runtime.sendMessage() slug: Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage tags: - API - Add-ons - Extensions - Method - Non-standard - Reference - WebExtensions - runtime - sendMessage translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage ---
{{AddonSidebar()}}

Envoie un simple message aux écouteurs d'événement dans votre extension ou une extension différente.

Si vous envoyez à votre extension, omettez l'argument extensionId. L'événement {{WebExtAPIRef('runtime.onMessage')}} sera déclenché dans chaque page de votre extension, à l'exception du cadre appelé runtime.sendMessage.

Si vous envoyez une extension différente, ajouter l'argument extensionId à l'ID de l'autre extension. {{WebExtAPIRef('runtime.onMessageExternal')}} sera déclenché dans l'autre extension.

Les extensions ne peuvent pas envoyer de messages aux scripts de contenu en utilisant cette méthode. Pour envoyer des messages aux scripts de contenu, utilisez {{WebExtAPIRef('tabs.sendMessage')}}.

C'est une fonction asynchrone qui renvoie une Promise.

Vous pouvez également utiliser une approche basée sur la connexion pour échanger des messages.

Syntaxe

var sending = browser.runtime.sendMessage(
  extensionId,             // optional string
  message,                 // any
  options                  // optional object
)

Paramètres

extensionId{{optional_inline}}
string. L'ID de l'extension à envoyer le message. Incluez ceci pour envoyer le message à une extension différente..Si le destinataire prévu a défini un ID explicitement en utilisant la clé d' applications dans  manifest.json, extensionId doit avoir une valeur. Sinon, il devrait avoir l'ID qui a été généré pour le destinataire prévu.
Si extensionId est omis, le message sera envoyé à votre propre extension.
message
any. Un objet qui peut être structuré clone sérialisé.
options{{optional_inline}}
object.
includeTlsChannelId{{optional_inline}}
boolean. Indique si l'ID de canal TLS sera transmis à {{WebExtAPIRef('runtime.onMessageExternal')}} pour les processus qui écoutent l'événement de connexion.
toProxyScript{{optional_inline}}
boolean. Doit être True si le message est destiné à un fichier PAC chargé à l'aide de l'API {{WebExtAPIRef("proxy")}}.

En fonction des arguments qui lui sont donnés, cette API est parfois ambiguë. Les règles suivantes sont utilisées :

Notez qu'avant Firefox 55, le règles étaient différentes dans le cas des 2 arguments. Sous les anciennes règles, si le premier argument était une chaîne, il était traité comme extensionId, avec le message comme deuxième argument. Cel signifiait que si vous appelez sendMessage() avec des arguments comme ("my-message", {}), il enverrait un message vide à l'extension identifiée par "my-message". Sous les nouvelles règles, avec ces arguments, vous enverriez le message "my-message" en interne, avec un objet options vide.

Valeur retournée

Une Promise. Si le destinataire a envoyé une réponse, celle-ci sera remplie avec la réponse en tant qu'objet JSON. Sinon, il sera rempli sans arguments. si une erreur survient lors de la connexion à l'extension, la promessage sera rejetée avec un message d'erreur.

Compatibilité du navitageur

{{Compat("webextensions.api.runtime.sendMessage")}}

Exemples

Voici un script de contenu qui envoie un message au script d'arrière-plan lorsque l'utilisateur clique sur la fenêtre de contenu. La charge utile du message est {greeting: "Greeting from the content script"}, et l'expéditeur s'attend également à recevoir une réponse, qui est gérée dans la fonction handleResponse :

// content-script.js

function handleResponse(message) {
  console.log(`Message from the background script:  ${message.response}`);
}

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

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

window.addEventListener("click", notifyBackgroundPage);

Le script d'arrière-plan correspondant ressemble à ceci :

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log("Message from the content script: " +
    request.greeting);
  sendResponse({response: "Response from background script"});
}

browser.runtime.onMessage.addListener(handleMessage);

{{WebExtExamples}}

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.