runtime.onMessageExternal

Verwenden Sie dieses Ereignis, um Nachrichten von anderen Erweiterungen oder Webseiten zu empfangen.

Standardmäßig kann eine Erweiterung Nachrichten von jeder anderen Erweiterung empfangen. Der Schlüssel externally_connectable im Manifest kann jedoch verwendet werden, um die Kommunikation auf bestimmte Erweiterungen zu beschränken und die Kommunikation mit Webseiten zu ermöglichen.

Um eine Nachricht zu senden, die vom onMessageExternal-Listener empfangen wird, verwenden Sie runtime.sendMessage(), und übergeben Sie die ID des Empfängers im extensionId Parameter.

Zusammen mit der Nachricht selbst wird dem Listener übergeben:

  • ein sender-Objekt, das Details über den Nachrichtenabsender liefert
  • eine sendResponse-Funktion, die der Listener verwenden kann, um eine Antwort an den Absender zurückzusenden.

Diese API kann nicht in einem Content-Skript verwendet werden.

Syntax

js
browser.runtime.onMessageExternal.addListener()
browser.runtime.onMessageExternal.removeListener(listener)
browser.runtime.onMessageExternal.hasListener(listener)

Ereignisse haben drei Funktionen:

addListener(listener)

Fügt diesem Ereignis einen Listener hinzu.

removeListener(listener)

Beendet das Lauschen auf dieses Ereignis. Das listener-Argument ist der Listener, der entfernt werden soll.

hasListener(listener)

Überprüft, ob ein listener für dieses Ereignis registriert ist. Gibt true zurück, wenn er hörend ist, ansonsten false.

addListener Syntax

Parameter

listener

Die Funktion, die aufgerufen wird, wenn dieses Ereignis eintritt. Der Funktion werden folgende Argumente übergeben:

message

object. Die Nachricht selbst. Dies ist ein JSON-fähiges Objekt.

sender

Ein runtime.MessageSender Objekt, das den Absender der Nachricht repräsentiert.

sendResponse

Eine Funktion, die höchstens einmal aufgerufen werden kann, um eine Antwort auf die Nachricht zu senden. Die Funktion nimmt ein einzelnes Argument an, das ein beliebiges JSON-fähiges Objekt sein kann. Dieses Argument wird an den Nachrichtenabsender zurückgegeben.

Wenn Sie mehr als einen onMessageExternal-Listener im selben Dokument haben, kann nur einer eine Antwort senden.

Um eine Antwort synchron zu senden, rufen Sie sendResponse auf, bevor die Listener-Funktion zurückkehrt. Um eine Antwort asynchron zu senden, tun Sie eines der folgenden:

  • Behalten Sie eine Referenz auf das sendResponse-Argument und geben Sie true aus der Listener-Funktion zurück. Sie können dann sendResponse aufrufen, nachdem die Listener-Funktion zurückgekehrt ist.
  • Geben Sie ein Promise von der Listener-Funktion zurück und lösen Sie das Promise, wenn die Antwort bereit ist.

Browser-Kompatibilität

BCD tables only load in the browser

Beispiele

In diesem Beispiel sendet die Erweiterung "blue@mozilla.org" eine Nachricht an die Erweiterung "red@mozilla.org":

js
// sender: browser.runtime.id === "blue@mozilla.org"

// Send a message to the extension whose ID is "red@mozilla.org"
browser.runtime.sendMessage("red@mozilla.org", "my message");
js
// recipient: browser.runtime.id === "red@mozilla.org"

function handleMessage(message, sender) {
  // check that the message is from "blue@mozilla.org"
  if (sender.id === "blue@mozilla.org") {
    // process message
  }
}

browser.runtime.onMessageExternal.addListener(handleMessage);

Hinweis: Diese API basiert auf der chrome.runtime API von Chromium. Diese Dokumentation ist aus runtime.json im Chromium-Code abgeleitet.