runtime.sendMessage()

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

Wenn Sie an Ihre Erweiterung senden, lassen Sie das Argument extensionId weg. Das runtime.onMessage-Ereignis wird auf jeder Seite Ihrer Erweiterung ausgelöst, außer in dem Frame, der runtime.sendMessage aufgerufen hat.

Wenn Sie an eine andere Erweiterung senden, geben Sie das Argument extensionId an, das auf die ID der anderen Erweiterung gesetzt ist. runtime.onMessageExternal wird in der anderen Erweiterung ausgelöst. Standardmäßig kann Ihre Erweiterung Nachrichten mit sich selbst und jeder anderen Erweiterung (definiert durch extensionId) austauschen. Der externally_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 Sie bitte tabs.sendMessage.

Dies ist eine asynchrone Funktion, die ein Promise zurückgibt.

Hinweis: Sie können auch einen verbindungsbasierten Ansatz zum Austausch von Nachrichten verwenden.

Syntax

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

Parameter

extensionId Optional

string. Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Fügen Sie dies ein, um die Nachricht an eine andere Erweiterung zu senden. Wenn der beabsichtigte Empfänger eine ID explizit mit dem Schlüssel browser_specific_settings in der manifest.json gesetzt hat, sollte extensionId diesen Wert haben. Ansonsten sollte es die ID haben, die für den beabsichtigten Empfänger generiert wurde.

Wenn extensionId weggelassen wird, wird die Nachricht an Ihre Erweiterung gesendet.

message

any. Ein Objekt, das als strukturiertes Klon-Serialisierung verwendet werden kann (siehe Datenklon-Algorithmus).

options Optional

object.

includeTlsChannelId Optional

boolean. Ob die TLS-Kanal-ID in runtime.onMessageExternal für Prozesse übergeben wird, die nach dem Verbindungsereignis lauschen.

Diese Option wird nur in Chromium-basierten Browsern unterstützt.

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

  • wenn ein Argument gegeben ist, ist es die Nachricht, die gesendet werden soll, und die Nachricht wird intern gesendet.

  • wenn zwei Argumente gegeben sind:

    • Die Argumente werden als (message, options) interpretiert, und die Nachricht wird intern gesendet, wenn das zweite Argument eines der folgenden ist:

      1. ein gültiges options-Objekt (bedeutet, es ist ein Objekt, das nur die Eigenschaften von options enthält, die der Browser unterstützt)
      2. null
      3. undefined
    • Andernfalls werden die Argumente als (extensionId, message) interpretiert. Die Nachricht wird an die durch extensionId identifizierte Erweiterung gesendet.

  • wenn drei Argumente gegeben sind, werden die Argumente als (extensionId, message, options) interpretiert. Die Nachricht wird an die durch extensionId identifizierte Erweiterung gesendet.

Beachten Sie, dass vor Firefox 55 die Regeln im Fall von zwei Argumenten anders waren. Nach den alten Regeln, wenn das erste Argument ein String war, wurde es als extensionId behandelt, mit der Nachricht als zweitem Argument. Das bedeutete, dass wenn Sie sendMessage() mit Argumenten wie ("my-message", {}) aufriefen, es eine leere Nachricht an die Erweiterung sendete, die als "my-message" identifiziert ist. Nach den neuen Regeln würden Sie mit diesen Argumenten die Nachricht "my-message" intern senden, mit einem leeren options-Objekt.

Rückgabewert

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

Browser-Kompatibilität

BCD tables only load in the browser

Beispiele

Hier ist ein Inhalts-Skript, das beim Klicken des Benutzers auf das Inhaltsfenster eine Nachricht an das Hintergrundskript sendet. Die Nachrichtennutzlast ist {greeting: "Greeting from the content script"}, und der Absender erwartet auch, eine Antwort zu erhalten, die in der Funktion handleResponse behandelt wird:

js
// 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) {
  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:

js
// background-script.js
function 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: Anstatt sendResponse() zu verwenden, ist das Zurückgeben eines Promise der empfohlene Ansatz für Firefox-Add-ons. Beispiele, die ein Promise verwenden, sind im Beispielabschnitt des runtime.onMessage-Listeners verfügbar.

Beispiel-Erweiterungen

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