chrome.runtime

Beschreibung

Verwenden Sie die chrome.runtime API, um den Dienst-Worker abzurufen, Details zum Manifest zurückzugeben und auf Ereignisse im Lebenszyklus der Erweiterung zu warten und darauf zu reagieren. Mit dieser API können Sie auch den relativen Pfad von URLs in vollständig qualifizierte URLs umwandeln.

Für die meisten Mitglieder dieser API sind keine Berechtigungen erforderlich. Diese Berechtigung ist für connectNative(), sendNativeMessage() und onNativeConnect erforderlich.

Im folgenden Beispiel wird gezeigt, wie die Berechtigung "nativeMessaging" im Manifest deklariert wird:

manifest.json:

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

Konzepte und Verwendung

Die Runtime API bietet Methoden zur Unterstützung verschiedener Bereiche, die Ihre Erweiterungen nutzen können:

Nachrichtenübertragung
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 Apps 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
Mit diesen Properties können Sie einige Meta-Vorgänge für die Erweiterung ausführen und die Seite mit den Optionen anzeigen. Zu den Methoden und Ereignissen in dieser Kategorie gehören onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() und setUninstallURL().
Dienstprogramme
Diese Methoden bieten Funktionen wie die Umwandlung interner Ressourcendarstellungen in externe Formate. 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 den Methoden in dieser Kategorie gehören restart() und restartAfterDelay()`.

Verhalten der entpackten Erweiterung

Wenn eine entpackte Erweiterung erneut geladen wird, wird dies als Update behandelt. Das bedeutet, dass das Ereignis chrome.runtime.onInstalled mit dem Grund "update" ausgelöst wird. Das gilt auch, wenn die Erweiterung mit chrome.runtime.reload() aktualisiert wird.

Anwendungsfälle

Bild auf einer Webseite einfügen

Damit eine Webseite auf ein Asset zugreifen kann, das auf einer anderen Domain gehostet wird, muss die vollständige URL der Ressource angegeben werden (z.B. <img src="https://example.com/logo.png">). Das gilt auch für das Einfügen eines Erweiterungs-Assets auf einer Webseite. Die beiden Unterschiede sind, dass die Assets der Erweiterung als über das Web zugängliche Ressourcen freigegeben werden müssen und dass in der Regel Inhaltsscripts für das Einfügen von Erweiterungs-Assets verantwortlich sind.

In diesem Beispiel fügt die Erweiterung der Seite, in die das Inhaltsscript eingefügt wird, logo.png hinzu, indem mit runtime.getURL() eine vollständig qualifizierte URL erstellt wird. 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 aus einem Inhaltsskript an den Dienst-Worker 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 bei zwei Browserfenstern, die auf dieselbe Webseite zugreifen, können diese beiden Kontexte 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. Um diese Daten abzurufen, gibt er die vom Entwickler definierte get-user-data-Nachricht an den Service Worker weiter, der mit einer Kopie der Nutzerinformationen antwortet.

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);
});

service-worker.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 Sie diese Funktion hinzufügen.

background.js:

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

Beispiele

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. Übereinstimmende Kontexte müssen mit allen angegebenen Filtern übereinstimmen. Nicht angegebene Filter stimmen 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
Gibt den Kontexttyp als Tab an

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 Offscreen-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

    Der Typ des Kontexts, dem dies 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 mit einem Inkognitoprofil verknüpft 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 mit Informationen zum Scriptkontext, über den eine Nachricht oder Anfrage gesendet wurde.

Attribute

  • documentId

    String optional

    Chrome 106 und höher

    Eine UUID des Dokuments, über das die Verbindung geöffnet wurde.

  • documentLifecycle

    String optional

    Chrome 106 und höher

    Der Lebenszyklus des Dokuments, das die Verbindung geöffnet hat, 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, die die Verbindung geöffnet hat (falls 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 die bzw. 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). Das ist hilfreich, um zu ermitteln, ob der Ursprung vertrauenswürdig ist, wenn wir das nicht sofort anhand der URL erkennen können.

  • Tabulatortaste

    Tab 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 geöffnet 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 Ereignisgrund als Aktualisierung eines freigegebenen Moduls an.

OnRestartRequiredReason

Chrome 44 und höher

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, weil der Browser/das Betriebssystem auf eine neuere Version aktualisiert wird. „periodisch“ wird verwendet, wenn das System länger als die in der Unternehmensrichtlinie festgelegte zulässige Uptime ausgeführt wird.

Enum

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

„os_update“
Gibt den Ereignisgrund als Update des Betriebssystems an.

„periodic“
Gibt den Grund für das Ereignis als regelmäßigen Neustart der App an.

PlatformArch

Chrome 44 und höher

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. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

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

PlatformNaclArch

Chrome 44 und höher

Die native Clientarchitektur. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

Enum

arm
Gibt die native Clientarchitektur als „arm“ 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 44 und höher

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 Linux-Betriebssystem 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 wird möglicherweise gesetzt, wenn die Verbindung zum Anschluss aufgrund eines Fehlers getrennt wurde. Wenn der Anschluss ü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 onDisconnect.addListener-Funktion 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 onMessage.addListener-Funktion 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

    Diese Eigenschaft ist nur auf Ports vorhanden, die an die Listener onConnect, onConnectExternal oder onConnectNative übergeben werden.

  • Verknüpfung aufheben

    void

    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

    void

    Senden Sie eine Nachricht an das andere Ende des Anschlusses. 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 Nachricht, die gesendet werden soll. 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. Das kann nach wiederholten Prüfungen innerhalb kurzer Zeit passieren.

„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. Dieser wird nur im Rahmen des Callbacks dieser Funktion definiert. Wenn ein Fehler auftritt, aber innerhalb des Rückrufs nicht auf runtime.lastError zugegriffen wird, wird in der Console eine Meldung protokolliert, in der die API-Funktion aufgeführt ist, die den Fehler verursacht hat. Bei API-Funktionen, die Promises zurückgeben, wird diese Eigenschaft nicht festgelegt.

Typ

Objekt

Attribute

  • Nachricht

    String optional

    Details zum aufgetretenen Fehler.

Methoden

connect()

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

Es wird versucht, Listener innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder anderer Erweiterungen/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 Inhaltsscripts herstellen, die in Tabs eingebettet sind.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, mit der eine Verbindung hergestellt werden soll. Wird dieser Parameter nicht angegeben, wird versucht, eine Verbindung zu Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn Nachrichten von einer Webseite für Webmessaging 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 auf das Verbindungsereignis warten, an „onConnect“ übergeben.

Gibt Folgendes zurück:

  • Port, über den Nachrichten gesendet und empfangen werden können. Das Ereignis onDisconnect des Anschlusses 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 im 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

    function 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

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getContexts()

Promise Chrome 116 und höher MV3 und höher 
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

    function optional

    Der Parameter callback sieht so aus: 

    (contexts: ExtensionContext[]) => void

Gibt Folgendes zurück:

  • Promise<ExtensionContext[]>

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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

    function optional

    Der Parameter callback sieht so aus: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Gibt Folgendes zurück:

  • Promise<DirectoryEntry>

    Chrome 122 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getPlatformInfo()

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

Gibt Informationen zur aktuellen Plattform zurück.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (platformInfo: PlatformInfo) => void

Gibt Folgendes zurück:

  • Promise<PlatformInfo>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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()

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

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

Das genaue Verhalten hängt vom Schlüssel options_ui oder options_page Ihres Manifests oder davon ab, was Chrome gerade 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 Seite, von der aus die Verknüpfung aufgerufen wird, wird dadurch nie neu geladen.

Wenn Ihre Erweiterung keine Optionsseite angibt oder Chrome aus einem anderen Grund keine erstellen konnte, wird im Rückruf lastError festgelegt.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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,
)

Erfordert eine sofortige Updateprüfung für diese App/Erweiterung.

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: Wenn diese Funktion mit einem Callback aufgerufen wird, gibt sie anstelle eines Objekts die beiden Eigenschaften als separate Argumente zurück, die an den Callback übergeben werden.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: object) => void

    • Ergebnis

      Objekt

      Chrome 109 und 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 Update-Prü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 in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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, die diese API aufruft, wiederholt aufgerufen werden.

Parameter

  • Sekunden

    Zahl

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

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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 oder 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-Channel-ID für Prozesse, die auf das Verbindungsereignis warten, an „onMessageExternal“ übergeben wird.

  • callback

    function 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 Herstellen einer Verbindung zur Erweiterung ein Fehler auftritt, wird der Rückruf ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Gibt Folgendes zurück:

  • Promise<any>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

sendNativeMessage()

Promise 
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 nativen Messaging-Host übergeben wird.

  • callback

    function 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. Wenn beim Verbinden mit dem nativen Messaging-Host ein Fehler auftritt, wird der Rückruf ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Gibt Folgendes zurück:

  • Promise<any>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

setUninstallURL()

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

Legt die URL fest, die nach der Deinstallation aufgerufen werden soll. So können Sie serverseitige Daten bereinigen, Analysen durchführen und Umfragen 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

    function optional

    Chrome 45 und höher

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 99 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

Ereignisse

onBrowserUpdateAvailable

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

Verwenden Sie 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 von einer anderen Erweiterung (über runtime.connect) oder von einer extern erreichbaren 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 ChromeOS 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. Dieser Wert ist nur vorhanden, wenn „reason“ den Wert „update“ hat.

      • Der Grund, warum dieses Ereignis gesendet wird.

onMessage

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

Wird ausgelöst, wenn eine Nachricht entweder von einem Erweiterungsprozess (über runtime.sendMessage) oder einem Inhaltsskript (über 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 | undefined

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 | undefined

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 alle Fenster so bald wie möglich schließen, damit der Neustart erfolgen kann. Wenn die App nicht reagiert, wird nach Ablauf eines Kulanzzeitraums 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 ein Profil mit dieser Erweiterung zum ersten Mal gestartet wird. Dieses Ereignis wird nicht ausgelöst, wenn ein Inkognitoprofil gestartet wird, auch wenn diese Erweiterung im geteilten Inkognitomodus ausgeführt wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspend

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

Wird kurz vor dem Entladen an die Ereignisseite gesendet. So kann die Erweiterung einige Bereinigungen vornehmen. Da die Seite entladen wird, ist nicht garantiert, dass alle asynchronen Vorgänge, die beim Bearbeiten dieses Ereignisses gestartet wurden, abgeschlossen werden. Wenn vor dem Entladen der Ereignisseite weitere Aktivitäten für die Seite stattfinden, wird das Ereignis „onSuspendCanceled“ gesendet und die Seite wird 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 doch 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, weil 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 aus 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 Nutzerscript 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