runtime.sendMessage()

Sendet eine einzelne Nachricht an Ereignis-Listener innerhalb Ihrer Erweiterung oder einer anderen Erweiterung.

Wenn Sie an Ihre eigene Erweiterung senden, lassen Sie dasextensionId-Argument weg. Das runtime.onMessage-Ereignis wird auf jeder Seite in Ihrer Erweiterung ausgelöst, mit Ausnahme des Frames, derruntime.sendMessage aufgerufen hat.

Wenn Sie an eine andere Erweiterung senden, geben Sie dasextensionId-Argument mit der ID der anderen Erweiterung an.runtime.onMessageExternal wird in der anderen Erweiterung ausgelöst. Standardmäßig kann Ihre Erweiterung Nachrichten mit sich selbst und jeder anderen Erweiterung (definiert durchextensionId) austauschen. Derexternally_connectable-Manifest-Schlüssel kann jedoch verwendet werden, um die Kommunikation auf bestimmte Erweiterungen zu beschränken.

Erweiterungen können mit dieser Methode keine Nachrichten an Inhalts-Skripte senden. Um Nachrichten an Inhalts-Skripte zu senden, verwenden Sietabs.sendMessage.

Dies ist eine asynchrone Funktion, die einPromise zurückgibt.

Hinweis:Sie können auch einenverbindungsbasierten Ansatz zum Nachrichtenaustausch verwenden.

Syntax

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

Parameter

extensionIdOptional

string. Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Geben Sie dies an, um die Nachricht an eine andere Erweiterung zu senden. Wenn der beabsichtigte Empfänger eine ID explizit mit dembrowser_specific_settings-Schlüssel in der manifest.json-Datei festgelegt hat, sollteextensionId diesen Wert haben. Andernfalls sollte es die für den beabsichtigten Empfänger generierte ID haben.

WennextensionId weggelassen wird, wird die Nachricht an Ihre Erweiterung gesendet.

message

any. Ein Objekt, das strukturiert klonbar serialisiert werden kann (sieheDatenklonierungsalgorithmus).

optionsOptional

object.

includeTlsChannelIdOptional

boolean. Ob die TLS-Kanal-ID in prozesse übergeben wird, die auf das Verbindung-Ereignis hören, inruntime.onMessageExternal.

Diese Option wird nur in auf Chromium basierenden Browsern unterstützt.

Abhängig von den gegebenen Argumenten ist diese API manchmal mehrdeutig. Die folgenden Regeln werden verwendet:

wenn ein Argument gegeben wird, ist es die zu sendende Nachricht, und die Nachricht wird intern gesendet.
wenn zwei Argumente gegeben werden:
- die Argumente werden als(message, options) interpretiert, und die Nachricht wird intern gesendet, wenn das zweite Argument eines der Folgenden ist:
  1. ein gültigesoptions-Objekt (das heißt, es handelt sich um ein Objekt, das nur die Eigenschaften vonoptions enthält, die der Browser unterstützt)
  2. null
  3. undefined
- andernfalls werden die Argumente als(extensionId, message) interpretiert. Die Nachricht wird an die durchextensionId identifizierte Erweiterung gesendet.
wenn drei Argumente gegeben werden, werden die Argumente als(extensionId, message, options) interpretiert. Die Nachricht wird an die durchextensionId identifizierte Erweiterung gesendet.

Beachten Sie, dass vor Firefox 55 die Regeln im 2-Argument-Fall anders waren. Unter den alten Regeln, wenn das erste Argument ein String war, wurde es alsextensionId behandelt, mit der Nachricht als zweitem Argument. Das bedeutete, dass, wenn SiesendMessage() mit Argumenten wie("meine-nachricht", {}) aufriefen, es eine leere Nachricht an die durch "meine-nachricht" identifizierte Erweiterung senden würde. Unter den neuen Regeln würden Sie mit diesen Argumenten die Nachricht "meine-nachricht" intern senden, mit einem leeren Options-Objekt.

Rückgabewert

EinPromise. Wenn der Empfänger eine Antwort gesendet hat, wird diese mit der Antwort erfüllt. Andernfalls wird es ohne Argumente erfüllt. Wenn beim Verbinden mit der Erweiterung ein Fehler auftritt, wird das Promise mit einer Fehlermeldung abgelehnt.

Beispiele

Hier ist ein Inhalts-Skript, das eine Nachricht an das Hintergrundskript sendet, wenn der Benutzer auf das Inhaltsfenster klickt. Der Nachrichtennutzlast ist{greeting: "Greeting from the content script"}, und der Sender erwartet auch, eine Antwort zu erhalten, die in derhandleResponse-Funktion behandelt wird:

// content-script.jsfunction handleResponse(message) {  console.log(`Message from the background script: ${message.response}`);}function handleError(error) {  console.log(`Error: ${error}`);}function notifyBackgroundPage(e) {  const sending = browser.runtime.sendMessage({    greeting: "Greeting from the content script",  });  sending.then(handleResponse, handleError);}window.addEventListener("click", notifyBackgroundPage);

Das entsprechende Hintergrundskript sieht so aus:

// background-script.jsfunction handleMessage(request, sender, sendResponse) {  console.log(`A content script sent a message: ${request.greeting}`);  sendResponse({ response: "Response from background script" });}browser.runtime.onMessage.addListener(handleMessage);

Hinweis:Anstelle vonsendResponse() zu nutzen, ist die Rückgabe einesPromise der empfohlene Ansatz für Firefox-Add-ons.Beispiele, die ein Promise verwenden, sind imBeispielabschnitt desruntime.onMessage-Listeners verfügbar.