Diese Seite wurde von der Cloud Translation API übersetzt.

chrome.runtime

Beschreibung

Mit der chrome.runtime API können Sie den Service Worker abrufen, Details zum Manifest zurückgeben sowie auf Ereignisse im Lebenszyklus der Erweiterung warten und darauf reagieren. Sie können diese API auch verwenden, um den relativen Pfad von URLs in voll qualifizierte URLs zu konvertieren.

Die meisten Mitglieder dieser API benötigen keine Berechtigungen. Diese Berechtigung ist für connectNative(), sendNativeMessage() und onNativeConnect erforderlich.

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

manifest.json:

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

Konzepte und Nutzung

Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Bereichen, die von Ihren Erweiterungen verwendet werden können:

Nachrichtenweitergabe: Die Erweiterung kann über die folgenden Methoden und Ereignisse in verschiedenen Kontexten mit anderen Erweiterungen kommunizieren: connect(), onConnect, onConnectExternal, sendMessage(), onMessage und onMessageExternal. Außerdem kann die Erweiterung mithilfe von connectNative() und sendNativeMessage() Nachrichten an native Anwendungen auf dem Gerät des Nutzers weiterleiten.

Auf Erweiterungs- und Plattformmetadaten zugreifen: Mit diesen Methoden können Sie mehrere bestimmte Metadaten zur Erweiterung und Plattform abrufen. Zu dieser Kategorie gehören getManifest() und getPlatformInfo().
Erweiterungslebenszyklus und Optionen verwalten: Mit diesen Eigenschaften kannst du einige Metavorgänge für die 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().
Hilfsprogramme: Diese Methoden bieten Dienstfunktionen, z. B. die Konvertierung interner Ressourcendarstellungen in externe Formate. Zu dieser Kategorie gehören unter anderem getURL().
Dienstprogramme im Kioskmodus: Diese Methoden sind nur unter ChromeOS verfügbar und dienen hauptsächlich zur Unterstützung von Kiosk-Implementierungen. Zu dieser Kategorie gehören restart() und restartAfterDelay()`.

Verhalten der entpackten Erweiterung

Beim Neuladen einer entpackten Erweiterung wird dies als Update behandelt. Das bedeutet, dass das Ereignis chrome.runtime.onInstalled mit dem Grund "update" ausgelöst wird. Dies gilt auch, wenn die Erweiterung mit chrome.runtime.reload() neu geladen wird.

Anwendungsfälle

Einer Webseite ein Bild hinzufügen

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

In diesem Beispiel fügt die Erweiterung logo.png der Seite hinzu, auf der das Inhaltsskript eingeschleust wird. Dazu wird runtime.getURL() verwendet, um eine voll qualifizierte URL zu erstellen. Zuerst muss das Asset jedoch im Manifest als über das Web zugä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 von einem Inhaltsskript an den Service Worker senden

Im Allgemeinen benötigen die Inhaltsskripte einer Erweiterung Daten, die von einem anderen Teil der Erweiterung verwaltet werden, z. B. vom Service Worker. Ähnlich wie zwei Browserfenster, die auf derselben Webseite geöffnet werden, können diese beiden Kontexte nicht direkt auf die Werte der jeweils anderen zugreifen. Stattdessen kann die Erweiterung die Nachrichtenübergabe verwenden, um eine Koordinierung in diesen verschiedenen Kontexten zu ermöglichen.

In diesem Beispiel benötigt das Inhaltsskript einige Daten vom Service Worker der Erweiterung, um die UI zu initialisieren. Zum Abrufen dieser Daten übergibt er die vom Entwickler definierte get-user-data-Nachricht an den Service Worker und antwortet mit einer Kopie der Nutzerinformationen.

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 verwenden Umfragen nach der Deinstallation, um herauszufinden, wie die Erweiterung ihren Nutzern noch mehr Vorteile bieten und die Nutzerbindung verbessern kann. 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

Weitere Runtime API-Beispiele finden Sie in der Demo „Manifest V3 – Web Accessible Resources“.

Typen

ContextFilter

Chrome 114 und höher

Ein Filter für den Abgleich mit bestimmten Erweiterungskontexten. Übereinstimmende Kontexte müssen mit allen angegebenen Filtern übereinstimmen. Jeder nicht angegebene Filter entspricht allen verfügbaren Kontexten. Daher stimmt ein Filter von „{}“ mit allen verfügbaren Kontexten überein.

Attribute

contextIds

string[] optional
contextTypes

ContextType[] optional
documentIds

string[] optional
documentOrigins

string[] optional
documentUrls

string[] optional
frameIds

nummer[] optional
inkognito

Boolescher Wert optional
tabIds

nummer[] optional
windowIds

nummer[] optional

ContextType

Chrome 114 und höher

Enum

"TAB"
Gibt den Kontexttyp als Tab an

"POPUP"
Gibt den Kontexttyp als Pop-up-Fenster für die 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.

ExtensionContext

Chrome 114 und höher

Ein Kontext, der Erweiterungsinhalte hostet.

Attribute

contextId

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 mit diesem Kontext verknüpfte Dokument oder nicht definiert, wenn dieser Kontext nicht in einem Dokument gehostet wird.
documentOrigin

String optional

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

String optional

Die URL des Dokuments, das mit diesem Kontext verknüpft ist, oder nicht definiert, 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 Skriptkontext, 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, das die Verbindung aufgebaut hat, als der Port erstellt wurde. Beachten Sie, dass sich der Lebenszyklusstatus des Dokuments seit dem Erstellen des Ports möglicherweise geändert hat.
frameId

Nummer optional

Der Frame, der die Verbindung hergestellt hat. 0 für Top-Level-Frames, positiv für untergeordnete Frames Wird nur festgelegt, wenn tab festgelegt ist.
id

String optional

Die ID der Erweiterung, die die Verbindung hergestellt hat, falls vorhanden.
nativeApplication

String optional

Chrome 74 und höher

Der Name der nativen Anwendung, die die Verbindung hergestellt hat, falls vorhanden.
Ursprung

String optional

Chrome 80 oder höher

Der Ursprung der Seite oder des Frames, über den die Verbindung hergestellt wurde. Sie kann von der URL-Eigenschaft abweichen (z.B. about:blank) oder undurchsichtig sein (z.B. iFrames in einer Sandbox). Dies ist hilfreich, um festzustellen, ob der Ursprung vertrauenswürdig ist, wenn wir dies nicht sofort anhand der URL feststellen können.
Tabulatortaste optional

Das tabs.Tab, das die Verbindung hergestellt hat, falls vorhanden. Diese Eigenschaft ist nur vorhanden, wenn die Verbindung über einen Tab geöffnet wurde (einschließlich Content-Scripts), und nur dann, wenn der Empfänger eine Erweiterung und keine App ist.
tlsChannelId

String optional

Die TLS-Kanal-ID der Seite oder des Frames, über die die Verbindung hergestellt wurde, falls von der Erweiterung angefordert und verfügbar.
url

String optional

Die URL der Seite oder des Frames, die bzw. der die Verbindung geöffnet hat. Wenn sich der Absender in einem iFrame befindet, ist dies die iFrame-URL und nicht die URL der Seite, auf der sie gehostet wird.

OnInstalledReason

Chrome 44 und höher

Der Grund, aus dem dieses Ereignis ausgelöst wird.

Enum

"install"
Gibt den Grund des Ereignisses als Installation an.

"update"
Gibt den Ereignisgrund als Erweiterungsupdate 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 44 und höher

Der Grund, aus dem das Ereignis gesendet wird. „app_update“ wird verwendet, wenn ein Neustart erforderlich ist, da die Anwendung auf eine neuere Version aktualisiert wird. „os_update“ wird verwendet, wenn ein Neustart erforderlich ist, da der Browser bzw. das Betriebssystem auf eine neuere Version aktualisiert wird. „Regelmäßig“ wird verwendet, wenn das System länger als die in der Unternehmensrichtlinie festgelegte zulässige Betriebszeit ausgeführt wird.

Enum

"app_update"
Gibt den Grund des Ereignisses als App-Update an.

"os_update"
Gibt den Ereignisgrund als Update des Betriebssystems an.

"periodic"
Gibt den Grund des Ereignisses als regelmäßigen Neustart der App an.

PlatformArch

Chrome 44 und höher

Die Prozessorarchitektur der Maschine.

Enum

"arm"
Gibt die Prozessorarchitektur als Verzweigung 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 der Maschine.
nacl_arch

PlatformNaclArch

Native Clientarchitektur. Dies kann auf einigen Plattformen von „arch“ abweichen.
os

PlatformOs

Das Betriebssystem, auf dem Chrome ausgeführt wird.

PlatformNaclArch

Chrome 44 und höher

Native Clientarchitektur. Dies kann auf einigen Plattformen von „arch“ abweichen.

Enum

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

Das Betriebssystem, auf 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 Betriebssystem Fuchsia an.

Port

Ein Objekt, das die 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 der Port vom anderen Ende getrennt wird runtime.lastError kann festgelegt werden, wenn der Port durch einen Fehler getrennt wurde. Wenn der Port über Verbindung trennen geschlossen wird, wird dieses Ereignis nur am anderen Ende ausgelöst. Dieses Ereignis wird höchstens einmal ausgelöst (siehe auch Portlebensdauer).

Die Funktion onDisconnect.addListener 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 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

Diese Eigenschaft ist nur an Ports vorhanden, die an onConnect-, onConnectExternal-/ onConnectNative-Listener übergeben werden.
Verknüpfung aufheben

void

Trennen Sie sofort den Anschluss. Wenn Sie disconnect() über einen bereits getrennten Port aufrufen, hat dies keine Auswirkungen. Wenn ein Port getrennt wird, werden keine neuen Ereignisse an diesen Port gesendet.

Die Funktion disconnect sieht so aus:
```
()=> {...}
```
postMessage

void

Senden Sie eine Nachricht an das andere Ende des Ports. Wenn der Port getrennt wird, wird ein Fehler ausgegeben.

Die Funktion postMessage sieht so aus:
```
(message: any)=> {...}
```
- Nachricht
  
  Beliebig
  
  Chrome 52 und höher
  
  Die zu sendende Nachricht. Dieses Objekt muss JSON-fähig sein.

RequestUpdateCheckStatus

Chrome 44 und höher

Ergebnis der Updateprüfung.

Enum

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

"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 nicht definiert. Dies wird nur im Bereich des Callbacks dieser Funktion definiert. Wenn ein Fehler erzeugt wird, aber innerhalb des Callbacks nicht auf runtime.lastError zugegriffen wird, wird in der Konsole eine Meldung protokolliert, in der die API-Funktion aufgelistet wird, die den Fehler verursacht hat. Bei API-Funktionen, die Promise 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,
)

Versuche, Hörer innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder anderer Erweiterungen/Apps zu verbinden. Das ist nützlich für Inhaltsskripte, die eine Verbindung zu den Erweiterungsprozessen, der Kommunikation zwischen Apps und Erweiterungen und Webnachrichten herstellen. Dabei 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, mit der eine Verbindung hergestellt werden soll. Wenn nicht angegeben, wird versucht, eine Verbindung mit Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn für Webnachrichten Nachrichten von einer Webseite gesendet werden.
connectInfo

Objekt optional
- includeTlsChannelId
  
  Boolescher Wert optional
  
  Gibt an, ob die TLS-Kanal-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.

Rückgaben

Port

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 Native Messaging.

Parameter

Anwendung

String

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

Rückgaben

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-Fensterobjekt für die Hintergrundseite ab, die in der aktuellen Erweiterung/App ausgeführt wird. Wenn die Hintergrundseite eine Ereignisseite ist, sorgt das System dafür, dass sie geladen wird, bevor der Callback 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-Fensterobjekt für die Hintergrundseite.

Rückgaben

Promise<Window|undefined>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getContexts()

Promise Chrome 116+ 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 zum Suchen übereinstimmender Kontexte. 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
```
- contexts
  
  ExtensionContext[]
  
  Die übereinstimmenden Kontexte, falls vorhanden.

Rückgaben

Promise<ExtensionContext[]>

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback ü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.

Rückgaben

Objekt

Die Manifestdetails.

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

Rückgaben

Promise<DirectoryEntry>

Chrome 122 und höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

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

Rückgaben

Promise<PlatformInfo>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getURL()

chrome.runtime.getURL(
  path: string,
)

Wandelt einen relativen Pfad innerhalb eines Installationsverzeichnisses für Apps/Erweiterungen in eine voll qualifizierte URL um.

Parameter

Pfad

String

Ein Pfad zu einer Ressource innerhalb einer App/Erweiterung, der relativ zum Installationsverzeichnis ausgedrückt wird.

Rückgaben

String

Die voll qualifizierte URL zur Ressource.

openOptionsPage()

Versprechen

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

Öffnen Sie, falls möglich, die Seite mit den Erweiterungsoptionen.

Das genaue Verhalten hängt möglicherweise 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 Ihres Manifests ab oder davon, was Chrome derzeit unterstützt. Beispielsweise kann die Seite in einem neuen Tab, unter chrome://extensions oder in einer App geöffnet werden oder es wird einfach eine offene Optionsseite angezeigt. Die Aufruferseite wird dadurch nicht neu geladen.

Wenn Ihre Erweiterung keine Optionsseite angibt oder Chrome aus einem anderen Grund keine Option erstellt, wird für den Callback lastError festgelegt.

Parameter

callback

Funktion optional

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

Rückgaben

Promise<void>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback ü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()

Versprechen

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

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

Wichtig: Für die meisten Erweiterungen/Apps sollte diese Methode nicht verwendet werden, da Chrome bereits alle paar Stunden automatische Prüfungen durchführt und Sie auf das runtime.onUpdateAvailable-Ereignis warten können, ohne requestUpdateCheck aufzurufen.

Diese Methode eignet sich nur für den Aufruf in sehr seltenen Fällen, z. B. wenn Ihre Erweiterung mit einem Backend-Dienst kommuniziert, der Backend-Dienst festgestellt hat, dass die Version der Clienterweiterung sehr veraltet ist und Sie einen Nutzer zur Aktualisierung auffordern möchten. Die meisten anderen Verwendungen von requestUpdateCheck, etwa ein bedingungsloser Aufruf basierend auf einem sich wiederholenden Timer, dienen wahrscheinlich nur dazu, Client-, Netzwerk- und Serverressourcen zu verschwenden.

Hinweis: Wenn sie mit einem Callback aufgerufen wird, gibt diese Funktion nicht ein Objekt zurück, sondern gibt die beiden Eigenschaften als separate Argumente zurück, die an den Callback übergeben werden.

Parameter

callback

Funktion optional

Der Parameter callback sieht so aus:
```
(result: object)=>void
```
- Ergebnis
  
  Objekt
  
  Chrome 109 und höher
  
  RequestUpdateCheckResult-Objekt, das den Status der Updateprüfung und Details zum Ergebnis enthält, falls ein Update verfügbar ist
  - status
    
    RequestUpdateCheckStatus
    
    Ergebnis der Updateprüfung.
  - Version
    
    String optional
    
    Wenn ein Update verfügbar ist, enthält es die Version des verfügbaren Updates.

Rückgaben

Promise<object>

Chrome 109 und höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Versprechen Chrome 53 oder höher

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Starten Sie das ChromeOS-Gerät neu, wenn die App nach den angegebenen Sekunden im Kioskmodus ausgeführt wird. Wird sie vor Ablauf der Zeit noch einmal aufgerufen, verzögert sich der Neustart. Wenn der Aufruf mit dem Wert -1 erfolgt, wird der Neustart abgebrochen. Im Nicht-Kiosk-Modus ist dies ein neutraler Vorgang. 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 abzubrechen.
callback

Funktion optional

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

Rückgaben

Promise<void>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

sendMessage()

Versprechen

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

Sendet eine einzelne Nachricht an Event-Listener innerhalb Ihrer Erweiterung oder einer anderen Erweiterung/App. Ähnlich wie bei runtime.connect, wird aber nur eine Nachricht mit einer optionalen Antwort gesendet. Wenn Sie das Ereignis an Ihre Erweiterung senden, wird das runtime.onMessage-Ereignis in jedem Frame der Erweiterung ausgelöst (außer im Frame des Absenders) oder runtime.onMessageExternal, falls eine andere Erweiterung verwendet wird. Beachten Sie, dass Erweiterungen mit dieser Methode keine Nachrichten an Inhaltsskripte senden können. Verwenden Sie tabs.sendMessage, um Nachrichten an Content-Skripts zu senden.

Parameter

extensionId

String optional

Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Wenn keine Nachricht angegeben ist, wird sie an Ihre eigene Erweiterung oder App gesendet. Dies ist erforderlich, wenn Nachrichten von einer Webseite für Webnachrichten gesendet werden.
Nachricht

Beliebig

Die zu sendende Nachricht. Diese Nachricht sollte ein Objekt sein, über das eine JSON-Datei übertragen werden kann.
Optionen

Objekt 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 oder höher

Der Parameter callback sieht so aus:
```
(response: any)=>void
```
- Antwort
  
  Beliebig
  
  Das vom Handler der Nachricht gesendete JSON-Antwortobjekt. Wenn beim Herstellen einer Verbindung zur Erweiterung ein Fehler auftritt, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Rückgaben

Versprechen<any>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

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 oder 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 Herstellen einer Verbindung zum nativen Messaging-Host ein Fehler auftritt, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Rückgaben

Versprechen<any>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

setUninstallURL()

Versprechen

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

Legt die URL fest, die bei der Deinstallation aufgerufen werden soll. Damit lassen sich 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

Funktion optional

Chrome 45 und höher

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

Rückgaben

Promise<void>

Chrome 99 oder höher

Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

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 über einen Erweiterungsprozess oder ein Inhaltsskript (von 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 über eine andere Erweiterung (von runtime.connect) oder über eine extern verwendbare 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 von einer nativen 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 oder auf eine neue Version aktualisiert wird

Parameter

callback

Funktion

Der Parameter callback sieht so aus:
```
(details: object)=>void
```
- Details
  
  Objekt
  - id
    
    String optional
    
    Gibt die ID der importierten freigegebenen Modulerweiterung an, die aktualisiert wurde. Dieses Feld ist nur vorhanden, wenn „reason“ den Wert „shared_module_update“ hat.
  - previousVersion
    
    String optional
    
    Gibt die vorherige Version der Erweiterung an, die gerade aktualisiert wurde. Dieses Feld ist nur vorhanden, wenn „reason“ „update“ ist.
  - reason
    
    OnInstalledReason
    
    Der Grund, aus dem dieses Ereignis ausgelöst wird.

onMessage

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

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

onMessageExternal

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

Wird ausgelöst, wenn eine Nachricht von einer anderen Erweiterung gesendet wird (von runtime.sendMessage). Kann nicht in einem Inhaltsskript 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 zum frühestmöglichen Zeitpunkt schließen, damit der Neustart erfolgen kann. Wenn die App nichts unternimmt, wird ein Neustart nach Ablauf eines Kulanzzeitraums von 24 Stunden erzwungen. Derzeit wird dieses Ereignis nur bei Chrome OS-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, in dem diese Erweiterung installiert ist, gestartet wird Dieses Ereignis wird nicht ausgelöst, wenn ein Inkognitoprofil gestartet wird, auch wenn diese Erweiterung im Inkognitomodus „Aufteilen“ ausgeführt wird.

Parameter

callback

Funktion

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

onSuspend

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

Wird an die Veranstaltungsseite gesendet, kurz bevor sie entfernt wird Dies gibt der Erweiterung die Möglichkeit, einige Bereinigungsschritte auszuführen. Da die Seite gerade entladen wird, können asynchrone Vorgänge, die während der Verarbeitung dieses Ereignisses gestartet wurden, nicht zwangsläufig abgeschlossen werden. Wenn vor dem Entfernen weitere Aktivitäten für die Ereignisseite stattfinden, wird das Ereignis onSuspensionCanceled 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 onSuspension 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, weil die App derzeit ausgeführt wird Wenn Sie nichts unternehmen, wird das Update beim nächsten Entladen der Hintergrundseite installiert. Wenn Sie möchten, dass sie früher installiert wird, können Sie explizit chrome.runtime.reload() aufrufen. Wenn Ihre Erweiterung eine persistente Hintergrundseite verwendet, wird die Hintergrundseite selbstverständlich nie entladen. Wenn Sie chrome.runtime.reload() als Reaktion auf dieses Ereignis nicht manuell aufrufen, wird das Update erst beim nächsten Neustart von Chrome selbst installiert. Wenn keine Handler auf dieses Ereignis warten und Ihre Erweiterung eine dauerhafte Hintergrundseite hat, verhält sie sich so, als ob chrome.runtime.reload() als Reaktion auf dieses Ereignis aufgerufen wird.

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+ MV3+

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

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

Parameter

callback

Funktion

Der Parameter callback sieht so aus:
```
(port: Port)=>void
```
- Port
  
  Port

onUserScriptMessage

Chrome 115+ MV3+

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