chrome.runtime

Beschreibung

Verwenden Sie die chrome.runtime API, um den Service Worker abzurufen, Details zum Manifest zurückzugeben und auf Ereignisse im Erweiterungslebenszyklus zu warten und darauf zu reagieren. Sie können diese API auch verwenden, um den relativen Pfad von URLs in voll qualifizierte URLs umzuwandeln.

Übersicht

Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Funktionsbereichen, die Ihre Erweiterungen nutzen können:

Nachrichtenweitergabe
Ihre Erweiterung kann mit verschiedenen Kontexten innerhalb Ihrer Erweiterung und auch mit anderen Erweiterungen über die folgenden Methoden und Ereignisse kommunizieren: connect(), onConnect, onConnectExternal, sendMessage(), onMessage und onMessageExternal. Außerdem kann Ihre Erweiterung Nachrichten mithilfe von connectNative() und sendNativeMessage() an native Anwendungen auf dem Gerät des Nutzers weitergeben.
Auf Erweiterungs- und Plattformmetadaten zugreifen
Mit diesen Methoden können Sie mehrere spezifische Metadaten zur Erweiterung und zur Plattform abrufen. Zu den Methoden in dieser Kategorie gehören getManifest() und getPlatformInfo().
Lebenszyklus und Optionen von Erweiterungen verwalten
Über diese Eigenschaften können Sie einige Metavorgänge auf der Erweiterung ausführen und die Seite mit den Optionen aufrufen. Zu den Methoden und Ereignissen in dieser Kategorie gehören onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() und setUninstallURL().
Dienstprogramme
Diese Methoden bieten einen Nutzen wie die Konvertierung interner Ressourcendarstellungen in externen Formaten. Zu den Methoden in dieser Kategorie gehört getURL().
Dienstprogramme für den Kioskmodus
Diese Methoden sind nur unter ChromeOS verfügbar und dienen hauptsächlich zur Unterstützung von Kioskimplementierungen. Zu dieser Kategorie gehören: restart und restartAfterDelay.

Berechtigungen

Für die meisten Methoden der Runtime API ist mit Ausnahme von keine Berechtigung erforderlich. sendNativeMessage und connectNative, erfordern die Berechtigung nativeMessaging.

Manifest

Das folgende Beispiel zeigt, wie die Berechtigung nativeMessaging im Manifest deklariert wird:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Anwendungsfälle

Einer Webseite ein Bild hinzufügen

Damit eine Webseite auf ein Asset zugreifen kann, das in einer anderen Domain gehostet wird, muss die vollständige URL der Ressource angegeben werden (z.B. <img src="https://example.com/logo.png">). Dasselbe gilt, wenn Sie ein Erweiterungs-Asset einer Webseite. Die beiden Unterschiede bestehen darin, dass die Assets der Erweiterung als Web- zugängliche Ressourcen und in der Regel Inhaltsskripte dafür verantwortlich sind, Erweiterungs-Assets.

In diesem Beispiel fügt die Erweiterung logo.png der Seite hinzu, auf der die Inhalte Skript wird in dieses Skript eingeschleust. Dazu wird runtime.getURL() verwendet, um ein vollständig qualifizierte URL. Zuerst muss das Asset im Manifest als webzugängliche Ressource deklariert werden.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Daten vom Service Worker an ein Inhaltsskript senden

Es ist üblich, dass die Inhaltsscripts einer Erweiterung Daten benötigen, die von einem anderen Teil der Erweiterung verwaltet werden, z. B. vom Dienst-Worker. Ähnlich wie zwei Browserfenster, die zur selben Webseite geöffnet werden, zwei Kontexte können nicht direkt auf die Werte des jeweils anderen zugreifen. Stattdessen kann die Erweiterung die Übermittlung von Nachrichten verwenden, um sich in diesen verschiedenen Kontexten zu koordinieren.

In diesem Beispiel benötigt das Inhaltsskript einige Daten vom Dienst-Worker der Erweiterung, um die Benutzeroberfläche zu initialisieren. Zum Abrufen dieser Daten wird eine get-user-data-Nachricht an den Service Worker übergeben. antwortet er mit einer Kopie der Informationen der Nutzenden.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

background.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Feedback zur Deinstallation einholen

Viele Erweiterungen nutzen Umfragen nach der Deinstallation, um herauszufinden, wie die Erweiterung die Nutzer besser unterstützen und die Bindung verbessern könnte. Das folgende Beispiel zeigt, wie diese Funktion hinzugefügt wird.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Beispiele für Erweiterungen

Weitere Beispiele für die Runtime API finden Sie in der Demo „Manifest V3 – Webzugriff auf Ressourcen“.

Typen

ContextFilter

Chrome 114 und höher

Ein Filter, der mit bestimmten Erweiterungskontexten abgeglichen wird. Kontexte müssen mit allen angegebenen Filtern übereinstimmen. Jeder nicht angegebene Filter stimmt mit allen verfügbaren Kontexten überein. Ein Filter mit dem Wert „{}“ stimmt also mit allen verfügbaren Kontexten überein.

Attribute

  • contextIds

    string[] optional

  • contextTypes

    ContextType[] optional

  • documentIds

    string[] optional

  • documentOrigins

    string[] optional

  • documentUrls

    string[] optional

  • frameIds

    number[] optional

  • Inkognito

    Boolescher Wert optional

  • tabIds

    number[] optional

  • windowIds

    number[] optional

ContextType

Chrome 114 und höher

Enum

TAB 
Definiert den Kontexttyp als Tab

"POPUP"
Gibt den Kontexttyp als Pop-up-Fenster der Erweiterung an

BACKGROUND
Gibt den Kontexttyp als Service Worker an.

"OFFSCREEN_DOCUMENT"
Gibt den Kontexttyp als nicht sichtbares Dokument an.

SIDE_PANEL
Gibt den Kontexttyp als Seitenleiste an.

„DEVELOPER_TOOLS“
Gibt den Kontexttyp als Entwicklertools an.

ExtensionContext

Chrome 114 und höher

Ein Kontext, in dem Erweiterungsinhalte gehostet werden.

Attribute

  • Kontext-ID

    String

    Eine eindeutige Kennung für diesen Kontext

  • contextType

    ContextType

    Die Art des Kontexts, dem dieser entspricht.

  • documentId

    String optional

    Eine UUID für das Dokument, das mit diesem Kontext verknüpft ist, oder „undefiniert“, wenn dieser Kontext nicht in einem Dokument gehostet wird.

  • documentOrigin

    String optional

    Der Ursprung des Dokuments, das mit diesem Kontext verknüpft ist, oder „undefiniert“, wenn der Kontext nicht in einem Dokument gehostet wird.

  • documentUrl

    String optional

    Die URL des Dokuments, das mit diesem Kontext verknüpft ist, oder „undefiniert“, wenn der Kontext nicht in einem Dokument gehostet wird.

  • frameId

    Zahl

    Die ID des Frames für diesen Kontext oder -1, wenn dieser Kontext nicht in einem Frame gehostet wird.

  • inkognito

    boolean

    Gibt an, ob der Kontext einem Inkognitoprofil zugeordnet ist.

  • tabId

    Zahl

    Die ID des Tabs für diesen Kontext oder -1, wenn dieser Kontext nicht auf einem Tab gehostet wird.

  • windowId

    Zahl

    Die ID des Fensters für diesen Kontext oder -1, wenn dieser Kontext nicht in einem Fenster gehostet wird.

MessageSender

Ein Objekt, das Informationen zum Skriptkontext enthält, der eine Nachricht oder Anfrage gesendet hat.

Attribute

  • documentId

    String optional

    Chrome 106 und höher

    Eine UUID des Dokuments, das die Verbindung geöffnet hat.

  • documentLifecycle

    String optional

    Chrome 106 und höher

    Der Lebenszyklus des Dokuments, über das die Verbindung geöffnet wurde, zum Zeitpunkt der Erstellung des Ports. Der Lebenszyklusstatus des Dokuments kann sich seit der Porterstellung geändert haben.

  • frameId

    number optional

    Der Frame, über den die Verbindung geöffnet wurde. „0“ für Frames der obersten Ebene, positiv für untergeordnete Frames. Dieser Wert wird nur festgelegt, wenn tab festgelegt ist.

  • id

    String optional

    Die ID der Erweiterung, über die die Verbindung hergestellt wurde (sofern vorhanden).

  • nativeApplication

    String optional

    Chrome 74 und höher

    Der Name der nativen Anwendung, die die Verbindung geöffnet hat, falls vorhanden.

  • origin

    String optional

    Chrome 80 und höher

    Der Ursprung der Seite oder des Frames, über den die Verbindung geöffnet wurde. Sie kann von der URL-Eigenschaft abweichen (z. B. about:blank) oder undurchsichtig sein (z. B. iFrames in Sandboxes). Dies ist nützlich, um festzustellen, ob der Ursprung vertrauenswürdig ist, wenn wir dies nicht sofort anhand der URL erkennen können.

  • Tabulatortaste

    Tabulatortaste optional

    Die tabs.Tab, über die die Verbindung geöffnet wurde (falls vorhanden). Dieses Attribut ist nur vorhanden, wenn die Verbindung über einen Tab geöffnet wurde (einschließlich Inhaltsscripts) und nur, wenn der Empfänger eine Erweiterung und keine App ist.

  • tlsChannelId

    String optional

    Die TLS-Channel-ID der Seite oder des Frames, über die bzw. den die Verbindung geöffnet wurde, sofern von der Erweiterung angefordert und verfügbar.

  • URL

    String optional

    Die URL der Seite oder des Frames, über die bzw. den die Verbindung hergestellt wurde. Wenn sich der Absender in einem Iframe befindet, ist dies die URL des Iframes und nicht die URL der Seite, auf der er gehostet wird.

OnInstalledReason

Chrome 44 und höher

Der Grund, warum dieses Ereignis gesendet wird.

Enum

„install“
Gibt den Grund für das Ereignis als Installation an.

„update“
Gibt den Grund für das Ereignis als Erweiterungsaktualisierung an.

„chrome_update“
Gibt den Ereignisgrund als Chrome-Update an.

"shared_module_update"
Gibt den Grund des Ereignisses als Update für ein freigegebenes Modul an.

OnRestartRequiredReason

Chrome (ab Version 44)

Der Grund, warum das Ereignis gesendet wird. „app_update“ wird verwendet, wenn ein Neustart erforderlich ist, weil die Anwendung auf eine neuere Version aktualisiert wird. „os_update“ wird verwendet, wenn ein Neustart erforderlich ist, da der Browser/Betriebssystem auf eine neuere Version aktualisiert wird. 'periodic' [periodisch] wird verwendet, wenn das System länger als die in der Unternehmensrichtlinie festgelegte zulässige Betriebszeit ausgeführt wird.

Enum

„app_update“
Gibt den Ereignisgrund als Update der App an.

"os_update"
Gibt den Grund des Ereignisses als Update des Betriebssystems an.

"periodic"
Gibt als Grund für das Ereignis einen regelmäßigen Neustart der App an.

PlatformArch

Chrome (ab Version 44)

Die Prozessorarchitektur des Computers.

Enum

arm
Gibt die Prozessorarchitektur als „arm“ an.

arm64
Gibt die Prozessorarchitektur als arm64 an.

„x86-32“
Gibt die Prozessorarchitektur als x86-32 an.

„x86-64“
Gibt die Prozessorarchitektur als x86-64 an.

„mips“
Gibt die Prozessorarchitektur als mips an.

„mips64“
Gibt die Prozessorarchitektur als mips64 an.

PlatformInfo

Ein Objekt mit Informationen zur aktuellen Plattform.

Attribute

  • Bogen

    PlatformArch

    Die Prozessorarchitektur des Computers.

  • nacl_arch

    PlatformNaclArch

    Die native Clientarchitektur. Auf einigen Plattformen kann dies vom Bogen abweichen.

  • Das Betriebssystem, auf dem Chrome ausgeführt wird.

PlatformNaclArch

Chrome 44 und höher

Die native Clientarchitektur. Auf einigen Plattformen kann dies vom Bogen abweichen.

Enum

"arm"
Gibt die Architektur des nativen Clients als Verzweigung an.

"x86-32"
Gibt die native Clientarchitektur als x86-32 an.

„x86-64“
Gibt die native Clientarchitektur als x86-64 an.

„mips“
Gibt die native Clientarchitektur als mips an.

„mips64“
Gibt die native Clientarchitektur als mips64 an.

PlatformOs

Chrome (ab Version 44)

Das Betriebssystem, unter dem Chrome ausgeführt wird.

Enum

mac
Gibt das macOS-Betriebssystem an.

"win"
Gibt das Windows-Betriebssystem an.

"android"
Gibt das Android-Betriebssystem an.

„cros“
Gibt das Chrome-Betriebssystem an.

"linux"
Gibt das Betriebssystem Linux an.

"openbsd"
Gibt das OpenBSD-Betriebssystem an.

„fuchsia“
Gibt das Fuchsia-Betriebssystem an.

Port

Ein Objekt, das eine bidirektionale Kommunikation mit anderen Seiten ermöglicht. Weitere Informationen finden Sie unter Langlebige Verbindungen.

Attribute

  • name

    String

    Der Name des Ports, wie im Aufruf von runtime.connect angegeben.

  • onDisconnect

    Event<functionvoidvoid>

    Wird ausgelöst, wenn die Verbindung des Anschlusses zu den anderen Enden getrennt wird. runtime.lastError kann festgelegt werden, wenn der Port aufgrund eines Fehlers getrennt wurde. Wenn der Port über disconnect geschlossen wird, wird dieses Ereignis nur am anderen Ende ausgelöst. Dieses Ereignis wird höchstens einmal ausgelöst (siehe auch Port-Lebensdauer).

    Die Funktion onDisconnect.addListener sieht so aus: 

    (callback: function) => {...}

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    Dieses Ereignis wird ausgelöst, wenn postMessage vom anderen Ende des Ports aufgerufen wird.

    Die Funktion onMessage.addListener sieht so aus: 

    (callback: function) => {...}

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

      (message: any, port: Port) => void

      • Nachricht

        beliebig

      • Port

        Port

  • Absender

    MessageSender optional

    Dieses Attribut ist nur an Ports vorhanden, die an onConnect-, onConnectExternal- und onConnectNative-Listener übergeben werden.

  • Verknüpfung aufheben

    voidm

    Trennen Sie den Anschluss sofort. Wenn Sie disconnect() für einen Port aufrufen, der bereits getrennt ist, hat das keine Auswirkungen. Wenn eine Verbindung zu einem Port getrennt wird, werden keine neuen Ereignisse an diesen Port gesendet.

    Die disconnect-Funktion sieht so aus: 

    () => {...}

  • postMessage

    voidm

    Senden Sie eine Nachricht an das andere Ende des Ports. Wenn die Verbindung zum Anschluss getrennt ist, wird ein Fehler ausgegeben.

    Die postMessage-Funktion sieht so aus: 

    (message: any) => {...}

    • Nachricht

      beliebig

      Chrome 52 und höher

      Die zu sendende Nachricht. Dieses Objekt sollte JSON-fähig sein.

RequestUpdateCheckStatus

Chrome 44 und höher

Ergebnis der Update-Prüfung.

Enum

„throttled“
Gibt an, dass die Statusprüfung gedrosselt wurde. Dies kann nach wiederholten Prüfungen innerhalb kurzer Zeit geschehen.

"no_update"
Gibt an, dass keine Updates zur Installation verfügbar sind.

„update_available“
Gibt an, dass ein Update zur Installation verfügbar ist.

Attribute

id

Die ID der Erweiterung/App.

Typ

String

lastError

Wird mit einer Fehlermeldung ausgefüllt, wenn der Aufruf einer API-Funktion fehlschlägt. Andernfalls ist der Wert nicht definiert. Dies wird nur im Rahmen des Callbacks dieser Funktion definiert. Wenn ein Fehler erzeugt wird, aber nicht innerhalb des Callbacks auf runtime.lastError zugegriffen wird, wird eine Meldung in der Konsole protokolliert, in der die API-Funktion aufgelistet ist, die den Fehler verursacht hat. API-Funktionen, die Promis zurückgeben, legen diese Eigenschaft nicht fest.

Typ

Objekt

Attribute

  • Nachricht

    String optional

    Details zum aufgetretenen Fehler.

Methoden

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

Versucht, Listener innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder anderer Erweiterungen oder Apps zu verbinden. Das ist nützlich für Inhaltsscripts, die eine Verbindung zu ihren Erweiterungsprozessen herstellen, für die Kommunikation zwischen Apps/Erweiterungen und für Web-Messaging. Hinweis: Es wird keine Verbindung zu Listenern in einem Inhaltsskript hergestellt. Erweiterungen können über tabs.connect eine Verbindung zu Inhaltsskripten herstellen, die in Tabs eingebettet sind.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, zu der eine Verbindung hergestellt werden soll. Wird dieser Parameter nicht angegeben, wird versucht, eine Verbindung zu Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn Nachrichten über eine Webseite für Webnachrichten gesendet werden.

  • connectInfo

    object optional

    • includeTlsChannelId

      Boolescher Wert optional

      Gibt an, ob die TLS-Channel-ID für Prozesse, die auf das Verbindungsereignis warten, an onConnectExternal übergeben wird.

    • name

      String optional

      Wird für Prozesse, die das Verbindungsereignis überwachen, an onConnect übergeben.

Gibt Folgendes zurück:

  • Port, über den Nachrichten gesendet und empfangen werden können. Das Ereignis onDisconnect des Ports wird ausgelöst, wenn die Erweiterung nicht vorhanden ist.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Stellt eine Verbindung zu einer nativen Anwendung auf dem Hostcomputer her. Für diese Methode ist die Berechtigung "nativeMessaging" erforderlich. Weitere Informationen finden Sie unter Natives Messaging.

Parameter

  • Anwendung

    String

    Der Name der registrierten Anwendung, zu der eine Verbindung hergestellt werden soll.

Gibt Folgendes zurück:

  • Port, über den Nachrichten mit der Anwendung gesendet und empfangen werden können

getBackgroundPage()

Versprechen Nur Vordergrund 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Ruft das JavaScript-Objekt „window“ für die Hintergrundseite ab, die in der aktuellen Erweiterung/App ausgeführt wird. Wenn es sich bei der Hintergrundseite um eine Ereignisseite handelt, sorgt das System dafür, dass sie geladen wird, bevor der Rückruf aufgerufen wird. Wenn keine Hintergrundseite vorhanden ist, wird ein Fehler festgelegt.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Fenster optional

      Das JavaScript-Objekt „window“ für die Hintergrundseite.

Gibt Folgendes zurück:

  • Promise<Window | undefined>

    Chrome 99 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getContexts()

Versprechen Chrome 116 und höher MV3+ 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Ruft Informationen zu aktiven Kontexten ab, die mit dieser Erweiterung verknüpft sind.

Parameter

  • Filter

    ContextFilter

    Ein Filter, mit dem übereinstimmende Kontexte gefunden werden. Ein Kontext stimmt überein, wenn er mit allen angegebenen Feldern im Filter übereinstimmt. Jedes nicht angegebene Feld im Filter stimmt mit allen Kontexten überein.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (contexts: ExtensionContext[]) => void

Gibt Folgendes zurück:

  • Promise<ExtensionContext[]>

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getManifest()

chrome.runtime.getManifest()

Gibt Details zur App oder Erweiterung aus dem Manifest zurück. Das zurückgegebene Objekt ist eine Serialisierung der vollständigen Manifestdatei.

Gibt Folgendes zurück:

  • Objekt

    Die Manifest-Details.

getPackageDirectoryEntry()

Versprechen Nur im Vordergrund 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Gibt einen DirectoryEntry für das Paketverzeichnis zurück.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Gibt Folgendes zurück:

  • Promise<DirectoryEntry> (Verzeichniseintrag)

    Chrome 122 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getPlatformInfo()

Versprechen 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

Gibt Informationen zur aktuellen Plattform zurück.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (platformInfo: PlatformInfo) => void

Gibt Folgendes zurück:

  • Promise <PlatformInfo>

    Chrome 99 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getURL()

chrome.runtime.getURL(
  path: string,
)

Konvertiert einen relativen Pfad in einem Installationsverzeichnis einer App/Erweiterung in eine vollständig qualifizierte URL.

Parameter

  • Pfad

    String

    Ein Pfad zu einer Ressource innerhalb einer App/Erweiterung, relativ zum Installationsverzeichnis.

Gibt Folgendes zurück:

  • String

    Die vollständig qualifizierte URL zur Ressource.

openOptionsPage()

Versprechen 
chrome.runtime.openOptionsPage(
  callback?: function,
)

Öffnen Sie nach Möglichkeit die Seite mit den Optionen Ihrer Erweiterung.

Das genaue Verhalten kann vom [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)- oder [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)-Schlüssel deines Manifests abhängen oder davon, was Chrome derzeit unterstützt. Die Seite kann beispielsweise in einem neuen Tab, unter chrome://extensions, in einer App oder einfach nur auf eine geöffnete Optionsseite fokussiert werden. Die Aufruferseite wird nie aktualisiert.

Wenn für Ihre Erweiterung keine Optionsseite deklariert ist oder Chrome aus einem anderen Grund keine Seite erstellt hat, wird für den Callback lastError festgelegt.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 99 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

reload()

chrome.runtime.reload()

Die App oder Erweiterung wird neu geladen. Diese Methode wird im Kioskmodus nicht unterstützt. Verwenden Sie für den Kioskmodus die Methode „chrome.runtime.restart()“.

requestUpdateCheck()

Promise 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Fordert die sofortige Prüfung auf Updates für diese App/Erweiterung an.

Wichtig: Die meisten Erweiterungen und Apps sollten diese Methode nicht verwenden, da Chrome bereits alle paar Stunden automatische Prüfungen durchführt. Sie können auf das Ereignis runtime.onUpdateAvailable warten, ohne requestUpdateCheck aufrufen zu müssen.

Diese Methode sollte nur in sehr begrenzten Fällen aufgerufen werden, z. B. wenn Ihre Erweiterung mit einem Backend-Dienst kommuniziert und der Backend-Dienst festgestellt hat, dass die Version der Clienterweiterung sehr veraltet ist und Sie einen Nutzer zum Aktualisieren auffordern möchten. Die meisten anderen Verwendungen von requestUpdateCheck, z. B. ein bedingungsloser Aufruf basierend auf einem sich wiederholenden Timer, führen wahrscheinlich nur dazu, dass Client-, Netzwerk- und Serverressourcen verschwendet werden.

Hinweis: Bei Aufruf mit einem Callback gibt diese Funktion die beiden Eigenschaften als separate Argumente an die Callback-Funktion zurück, anstatt ein Objekt zurückzugeben.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: object) => void

    • Ergebnis

      Objekt

      Chrome 109 oder höher

      Das Objekt „RequestUpdateCheckResult“ enthält den Status der Updateprüfung und alle Details zum Ergebnis, falls ein Update verfügbar ist.

      • Ergebnis der Updateprüfung

      • Version

        String optional

        Wenn ein Update verfügbar ist, enthält diese Spalte die Version des verfügbaren Updates.

Gibt Folgendes zurück:

  • Promise<object>

    Chrome 109 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

restart()

chrome.runtime.restart()

Starten Sie das ChromeOS-Gerät neu, wenn die App im Kioskmodus ausgeführt wird. Andernfalls passiert nichts.

restartAfterDelay()

Promise Chrome 53 und höher 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Starten Sie das ChromeOS-Gerät neu, wenn die App nach der angegebenen Zeit im Kioskmodus ausgeführt wird. Wenn der Befehl vor Ablauf der Zeit noch einmal aufgerufen wird, wird der Neustart verzögert. Wenn der Befehl mit dem Wert „-1“ aufgerufen wird, wird der Neustart abgebrochen. Im nicht-Kioskmodus ist sie nicht aktiv. Sie darf nur von der ersten Erweiterung wiederholt aufgerufen werden, um diese API aufzurufen.

Parameter

  • Sekunden

    Zahl

    Wartezeit in Sekunden, bevor das Gerät neu gestartet wird, oder -1, um einen geplanten Neustart abzusagen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 99 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

sendMessage()

Promise 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Sendet eine einzelne Nachricht an Ereignis-Listener in Ihrer Erweiterung oder einer anderen Erweiterung/App. Ähnlich wie runtime.connect, wird jedoch nur eine einzelne Nachricht mit einer optionalen Antwort gesendet. Wenn die Daten an Ihre Erweiterung gesendet werden, wird das Ereignis runtime.onMessage in jedem Frame Ihrer Erweiterung ausgelöst (außer im Frame des Absenders) oder runtime.onMessageExternal, wenn es sich um eine andere Erweiterung handelt. Erweiterungen können mit dieser Methode keine Nachrichten an Inhalts-Scripts senden. Verwenden Sie tabs.sendMessage, um Nachrichten an Inhaltsscripts zu senden.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Wenn Sie diese Option weglassen, wird die Nachricht an Ihre eigene Erweiterung/App gesendet. Sie ist erforderlich, wenn Sie Nachrichten von einer Webseite für Webmessaging senden.

  • Nachricht

    beliebig

    Die Nachricht, die gesendet werden soll. Diese Nachricht sollte ein JSON-Objekt sein.

  • Optionen

    object optional

    • includeTlsChannelId

      boolescher Wert optional

      Gibt an, ob die TLS-Kanal-ID für Prozesse, die das Verbindungsereignis überwachen, an onMessageExternal übergeben wird.

  • callback

    Funktion optional

    Chrome 99 und höher

    Der Parameter callback sieht so aus: 

    (response: any) => void

    • Antwort

      beliebig

      Das JSON-Antwortobjekt, das vom Handler der Nachricht gesendet wird. Wenn beim Verbinden mit der Erweiterung ein Fehler auftritt, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Gibt Folgendes zurück:

  • Versprechen<beliebig>

    Chrome 99 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

sendNativeMessage()

Versprechen 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Eine einzelne Nachricht an eine native Anwendung senden. Für diese Methode ist die Berechtigung "nativeMessaging" erforderlich.

Parameter

  • Anwendung

    String

    Der Name des Hosts für natives Messaging.

  • Nachricht

    Objekt

    Die Nachricht, die an den Host für natives Messaging übergeben wird.

  • callback

    Funktion optional

    Chrome 99 und höher

    Der Parameter callback sieht so aus: 

    (response: any) => void

    • Antwort

      beliebig

      Die Antwortnachricht, die vom Host für natives Messaging gesendet wird. Tritt beim Herstellen einer Verbindung zum nativen Messaging-Host ein Fehler auf, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Gibt Folgendes zurück:

  • Versprechen<beliebig>

    Chrome 99 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setUninstallURL()

Versprechen 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Legt die URL fest, die nach der Deinstallation aufgerufen werden soll. Dies kann verwendet werden, um serverseitige Daten zu bereinigen, Analysen durchzuführen und Umfragen zu implementieren. Maximal 1.023 Zeichen.

Parameter

  • URL

    String

    URL, die nach der Deinstallation der Erweiterung geöffnet werden soll. Diese URL muss ein http:- oder https:-Schema haben. Legen Sie einen leeren String fest, damit bei der Deinstallation kein neuer Tab geöffnet wird.

  • callback

    Funktion optional

    Chrome (ab Version 45)

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 99 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onBrowserUpdateAvailable

Eingestellt
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Bitte verwende runtime.onRestartRequired.

Wird ausgelöst, wenn ein Chrome-Update verfügbar ist, aber nicht sofort installiert wird, da ein Browserneustart erforderlich ist.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Verbindung entweder über einen Erweiterungsprozess oder ein Inhaltsskript (über runtime.connect) hergestellt wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Verbindung über eine andere Erweiterung (von runtime.connect) oder eine extern erreichbare Website hergestellt wird

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onConnectNative

Chrome 76 und höher 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Verbindung über eine native Anwendung hergestellt wird. Für dieses Ereignis ist die Berechtigung "nativeMessaging" erforderlich. Sie wird nur unter Chrome OS unterstützt.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Erweiterung zum ersten Mal installiert, auf eine neue Version aktualisiert oder Chrome auf eine neue Version aktualisiert wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (details: object) => void

    • Details

      Objekt

      • id

        String optional

        Die ID der importierten freigegebenen Modulerweiterung, die aktualisiert wurde. Dieser Wert ist nur vorhanden, wenn „reason“ „shared_module_update“ ist.

      • previousVersion

        String optional

        Die vorherige Version der Erweiterung, die gerade aktualisiert wurde. Dies ist nur vorhanden, wenn 'Grund' ist „update“.

      • Der Grund, warum dieses Ereignis gesendet wird.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Nachricht über einen Erweiterungsprozess (von runtime.sendMessage) oder ein Content-Script (von tabs.sendMessage) gesendet wird

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | nicht definiert

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Nachricht von einer anderen Erweiterung gesendet wird (über runtime.sendMessage). Kann nicht in einem Inhaltsscript verwendet werden.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | nicht definiert

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine App oder das Gerät, auf dem sie ausgeführt wird, neu gestartet werden muss Die App sollte zum frühestmöglichen Zeitpunkt alle Fenster schließen, damit der Neustart durchgeführt werden kann. Wenn die App nichts unternimmt, wird nach einem Kulanzzeitraum von 24 Stunden ein Neustart erzwungen. Derzeit wird dieses Ereignis nur für ChromeOS-Kiosk-Apps ausgelöst.

Parameter

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Wird ausgelöst, wenn zum ersten Mal ein Profil gestartet wird, in dem diese Erweiterung installiert ist. Dieses Ereignis wird nicht ausgelöst, wenn ein Inkognitoprofil gestartet wird, auch wenn diese Erweiterung im geteilten Modus ausgeführt wird. Inkognitomodus verwenden.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Wird an die Terminseite gesendet, kurz bevor sie entladen wird. So kann die Erweiterung einige Bereinigungen vornehmen. Da die Seite gerade entladen wird, kann nicht garantiert werden, dass die während der Verarbeitung dieses Ereignisses gestarteten asynchronen Vorgänge abgeschlossen werden. Wenn weitere Aktivitäten für die Veranstaltungsseite stattfinden, bevor sie entladen wird, wird das onSuspensionCanceled-Ereignis gesendet und die Seite nicht entladen.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Wird nach onSuspend gesendet, um anzugeben, dass die App nicht entladen wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Wird ausgelöst, wenn ein Update verfügbar ist, aber nicht sofort installiert wird, da die App gerade ausgeführt wird Wenn Sie nichts unternehmen, wird das Update beim nächsten Entladen der Hintergrundseite installiert. Wenn es früher installiert werden soll, können Sie chrome.runtime.reload() explizit aufrufen. Wenn Ihre Erweiterung eine persistente Hintergrundseite verwendet, wird diese natürlich nie entladen. Wenn Sie also nicht manuell chrome.runtime.reload() aufrufen, wird das Update erst beim nächsten Neustart von Chrome installiert. Wenn keine Handler auf dieses Ereignis warten und Ihre Erweiterung eine persistente Hintergrundseite hat, verhält sie sich so, als würde chrome.runtime.reload() als Reaktion auf dieses Ereignis aufgerufen.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (details: object) => void

    • Details

      Objekt

      • Version

        String

        Die Versionsnummer des verfügbaren Updates.

onUserScriptConnect

Chrome 115 und höher MV3 und höher 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Verbindung über ein Nutzerskript dieser Erweiterung hergestellt wird

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onUserScriptMessage

Chrome 115 und höher MV3 und höher 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Nachricht von einem Nutzerskript gesendet wird, das mit derselben Erweiterung verknüpft ist.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | undefined