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 externally_connectable Manifest-Schlüssel kann jedoch dazu verwendet werden, 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 wird dem Listener übergeben:

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

Diese API kann nicht in einem Inhaltsskript verwendet werden.

Siehe runtime.onMessage für weitere Informationen über den Empfang von Nachrichten und das Senden von Antworten, sowie Beispiele für die verschiedenen Optionen zum Senden von Antworten.

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)

Hört auf, auf dieses Ereignis zu hören. Das listener-Argument ist der zu entfernende Listener.

hasListener(listener)

Überprüft, ob ein listener für dieses Ereignis registriert ist. Gibt true zurück, wenn es zuhört, ansonsten false.

addListener Syntax

Parameter

listener

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

message

object. Die Nachricht. 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 wird, um eine Antwort auf die Nachricht zu senden. Die Funktion nimmt ein Argument, welches ein JSON-fähiges Objekt ist. Dieses Argument wird an den Absender der Nachricht zurückgegeben.

Wenn Sie mehr als einen onMessageExternal-Listener im selben Dokument haben, dann 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, verwenden Sie eine dieser Optionen:

  • Geben Sie ein Promise von der Listener-Funktion zurück und lösen Sie das Versprechen, wenn die Antwort bereit ist. Dies ist der bevorzugte Ansatz.

  • Behalten Sie eine Referenz auf das sendResponse()-Argument und geben Sie true von der Listener-Funktion zurück. Sie rufen dann sendResponse() auf, nachdem die Listener-Funktion zurückkehrt.

    Hinweis: Promise als Rückgabewert wird in Chrome erst unterstützt, wenn Chrome Bug 1185241 gelöst ist. Als Alternative geben Sie true zurück und verwenden sendResponse wie bei runtime.onMessage beschrieben.

Beispiele

In diesem Beispiel sendet die Erweiterung "[email protected]" eine Nachricht an die Erweiterung "[email protected]":

js
// sender: browser.runtime.id === "[email protected]"

// Send a message to the extension whose ID is "[email protected]"
browser.runtime.sendMessage("[email protected]", "my message");
js
// recipient: browser.runtime.id === "[email protected]"

function handleMessage(message, sender) {
  // check that the message is from "[email protected]"
  if (sender.id === "[email protected]") {
    // process message
  }
}

browser.runtime.onMessageExternal.addListener(handleMessage);

Browser-Kompatibilität

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