Diese Seite wurde von der Cloud Translation API übersetzt.

chrome.runtime

Beschreibung

Mit der chrome.runtime API können Sie den Dienst-Worker abrufen, Details zum Manifest zurückgeben und auf Ereignisse im Erweiterungszyklus warten und darauf 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 hergestellt 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 Grund für das Ereignis 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.
os

PlatformOs

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

Ereignis<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
```
  - Port
    
    Port
onMessage

Ereignis<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.

Ausgabe

Port

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.

Ausgabe

Port

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.

Ausgabe

Promise<Window | undefined>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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
```
- contexts
  
  ExtensionContext[]
  
  Die übereinstimmenden Kontexte, falls vorhanden.

Ausgabe

Promise<ExtensionContext[]>

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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.

Ausgabe

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

Ausgabe

Promise<DirectoryEntry>

Chrome 122 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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
```
- platformInfo
  
  PlatformInfo

Ausgabe

Promise<PlatformInfo>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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.

Ausgabe

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

Ausgabe

Promise<void>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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.
  - Status
    
    RequestUpdateCheckStatus
    
    Ergebnis der Update-Prüfung.
  - Version
    
    String optional
    
    Wenn ein Update verfügbar ist, enthält diese Spalte die Version des verfügbaren Updates.

Ausgabe

Promise<object>

Chrome 109 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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
```

Ausgabe

Promise<void>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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/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.

Ausgabe

Promise<any>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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.

Ausgabe

Promise<any>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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 bei 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
```

Ausgabe

Promise<void>

Chrome 99 und höher

Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. 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
```
- Port
  
  Port

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
```
- Port
  
  Port

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
```
- Port
  
  Port

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.
  - reason
    
    OnInstalledReason
    
    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

callback

Funktion

Der Parameter callback sieht so aus:
```
(reason: OnRestartRequiredReason) => void
```
- reason
  
  OnRestartRequiredReason

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
```
- Port
  
  Port

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