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 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(), wobei die ID des Empfängers in der extensionId-Parameter übergeben wird.

Zusammen mit der Nachricht erhält der Listener folgende Parameter:

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

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

Weitere Informationen zum Empfangen von Nachrichten und zum Senden von Antworten sowie Beispiele für die verschiedenen Möglichkeiten, Antworten zu senden, finden Sie unter runtime.onMessage.

Syntax

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

Ereignisse haben drei Funktionen:

addListener(listener)

Fügt einen Listener zu diesem Ereignis hinzu.

removeListener(listener)

Beendet das Abhören dieses Ereignisses. Das Argument listener ist der zu entfernende Listener.

hasListener(listener)

Prüft, ob ein listener für dieses Ereignis registriert ist. Gibt true zurück, wenn er registriert ist, andernfalls false.

addListener-Syntax

Parameter

listener

Die Funktion, die aufgerufen wird, wenn dieses Ereignis eintritt. Die Funktion erhält folgende Argumente:

message

object. Die Nachricht. Dies ist ein JSON-serialisierbares 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 Argument an, das ein JSON-serialisierbares Objekt ist. Dieses Argument wird an den Absender der Nachricht zurückgegeben.

Falls 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ückgibt.

Um eine Antwort asynchron zu senden, verwenden Sie eine der folgenden Optionen:

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

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

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

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);

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
onMessageExternal
Respond with Promise

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Has more compatibility info.

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