runtime.onMessage

browser.runtime.onMessage.addListener(listener)
browser.runtime.onMessage.removeListener(listener)
browser.runtime.onMessage.hasListener(listener)

Ereignisse haben drei Funktionen:

addListener(listener)

Fügt diesem Ereignis einen Listener hinzu.

removeListener(listener)

Beendet das Lauschen dieses Ereignisses. Das listener-Argument ist der Listener, der entfernt werden soll.

hasListener(listener)

Überprüft, ob mindestens ein Listener für dieses Ereignis registriert ist. Gibt true zurück, wenn es lauscht, sonst false.

listener

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

message

object. Die Nachricht. Dies ist ein serialisierbares Objekt (siehe Data cloning algorithm).

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 message zu senden. Die Funktion nimmt ein Argument: jedes serialisierbare Objekt (siehe Data cloning algorithm). Dieses Argument wird an den Nachrichtenabsender zurückgegeben.

Wenn Sie mehr als einen onMessage()-Listener im gleichen Dokument haben, 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 der folgenden Optionen:

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

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

  Hinweis: Promise als Rückgabewert wird in Chrome nicht unterstützt, bis Chrome Bug 1185241 behoben ist. Alternativ geben Sie true zurück und verwenden Sie sendResponse.

Die listener-Funktion kann entweder ein Boolean oder ein Promise zurückgeben.

Hinweis: Wenn Sie eine asynchrone Funktion an addListener() übergeben, gibt der Listener für jede empfangene Nachricht ein Promise zurück, was andere Listener daran hindert zu antworten:

js

// Machen Sie das nicht
browser.runtime.onMessage.addListener(async (data, sender) => {
  if (data.type === "handle_me") {
    return "done";
  }
});

Angenommen, Sie möchten, dass der Listener nur auf Nachrichten eines bestimmten Typs reagiert. In diesem Fall müssen Sie den Listener als nicht asynchrone Funktion definieren und nur für die Nachrichten ein Promise zurückgeben, auf die der Listener reagieren soll — und sonst false oder undefined zurückgeben:

js

browser.runtime.onMessage.addListener((data, sender) => {
  if (data.type === "handle_me") {
    return Promise.resolve("done");
  }
  return false;
});

Dieses Inhalts-Skript horcht auf Klick-Ereignisse auf der Webseite. Wenn der Klick auf einen Link erfolgt, sendet es eine Nachricht mit der Ziel-URL an die Hintergrundseite:

// content-script.js

window.addEventListener("click", notifyExtension);

function notifyExtension(e) {
  if (e.target.tagName !== "A") {
    return;
  }
  browser.runtime.sendMessage({ url: e.target.href });
}

Das Hintergrund-Skript horcht auf diese Nachrichten und zeigt eine Benachrichtigung mit der notifications API an:

// background-script.js

browser.runtime.onMessage.addListener(notify);

function notify(message) {
  browser.notifications.create({
    type: "basic",
    iconUrl: browser.extension.getURL("link.png"),
    title: "You clicked a link!",
    message: message.url,
  });
}

Dieses Inhalts-Skript sendet eine Nachricht an das Hintergrund-Skript, wenn der Benutzer auf die Seite klickt. Es protokolliert auch jede vom Hintergrund-Skript gesendete Antwort:

// content-script.js

function handleResponse(message) {
  console.log(`background script sent a response: ${message.response}`);
}

function handleError(error) {
  console.log(`Error: ${error}`);
}

function sendMessage(e) {
  const sending = browser.runtime.sendMessage({
    content: "message from the content script",
  });
  sending.then(handleResponse, handleError);
}

window.addEventListener("click", sendMessage);

Hier ist eine Version des entsprechenden Hintergrund-Skripts, das eine Antwort synchron aus dem Listener sendet:

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  sendResponse({ response: "response from background script" });
}

browser.runtime.onMessage.addListener(handleMessage);

Und hier ist eine andere Version, die Promise.resolve() verwendet:

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  return Promise.resolve({ response: "response from background script" });
}

browser.runtime.onMessage.addListener(handleMessage);

Hier ist eine alternative Version des Hintergrund-Skripts aus dem vorherigen Beispiel. Es sendet eine Antwort asynchron, nachdem der Listener zurückgekehrt ist. Beachten Sie return true; im Listener: Dies teilt dem Browser mit, dass Sie beabsichtigen, das sendResponse-Argument nach der Rückkehr des Listeners zu verwenden.

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  setTimeout(() => {
    sendResponse({ response: "async response from background script" });
  }, 1000);
  return true;
}

browser.runtime.onMessage.addListener(handleMessage);

Dieses Inhalts-Skript sucht den ersten <a>-Link auf der Seite und sendet eine Nachricht, die fragt, ob der Standort des Links als Lesezeichen gespeichert ist. Es erwartet eine booleanische Antwort (true, wenn der Standort als Lesezeichen gespeichert ist, sonst false):

// content-script.js

const firstLink = document.querySelector("a");

function handleResponse(isBookmarked) {
  if (isBookmarked) {
    firstLink.classList.add("bookmarked");
  }
}

browser.runtime
  .sendMessage({
    url: firstLink.href,
  })
  .then(handleResponse);

Hier ist das Hintergrund-Skript. Es verwendet bookmarks.search(), um zu überprüfen, ob der Link als Lesezeichen gespeichert ist, was ein Promise zurückgibt:

// background-script.js

function isBookmarked(message, sender, response) {
  return browser.bookmarks
    .search({
      url: message.url,
    })
    .then((results) => results.length > 0);
}

browser.runtime.onMessage.addListener(isBookmarked);

Wenn der asynchrone Handler kein Promise zurückgibt, können Sie explizit ein Promise konstruieren. Dieses eher gekünstelte Beispiel sendet eine Antwort nach einer Verzögerung von 1 Sekunde unter Verwendung von setTimeout():

// background-script.js

function handleMessage(request, sender, sendResponse) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ response: "async response from background script" });
    }, 1000);
  });
}

browser.runtime.onMessage.addListener(handleMessage);

• beastify
• content-script-register
• cookie-bg-picker
• devtools-panels
• export-helpers
• find-across-tabs
• imagify
• mocha-client-tests
• notify-link-clicks-i18n
• store-collected-images
• user-script-register
• userScripts-mv3
• webpack-modules