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
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, sollteextensionId
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 inruntime.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:- ein gültiges
options
-Objekt (bedeutet, es ist ein Objekt, das nur die Eigenschaften vonoptions
enthält, die der Browser unterstützt) - null
- undefined
- ein gültiges
-
Andernfalls werden die Argumente als
(extensionId, message)
interpretiert. Die Nachricht wird an die durchextensionId
identifizierte Erweiterung gesendet.
-
-
wenn drei Argumente gegeben sind, 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 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:
// 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:
// 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
- content-script-register
- devtools-panels
- export-helpers
- find-across-tabs
- mocha-client-tests
- notify-link-clicks-i18n
- store-collected-images
- user-script-register
- webpack-modules
Hinweis: Diese API basiert auf der chrome.runtime
-API von Chromium. Diese Dokumentation ist abgeleitet von runtime.json
im Chromium-Code.