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.
Überblick
Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Funktionsbereichen, die von Ihren Erweiterungen verwendet werden können:
- Nachrichtenweitergabe
- Die Erweiterung kann über diese Methoden und Ereignisse in verschiedenen Kontexten innerhalb der Erweiterung sowie mit anderen Erweiterungen kommunizieren: connect(), onConnect, onConnectExternal, sendMessage(), onMessage und onMessageExternal. Darüber hinaus kann Ihre Erweiterung Nachrichten mithilfe von connectNative() und sendNativeMessage() an native Anwendungen auf dem Gerät des Nutzers weitergeben.
- Auf Erweiterungs- und Plattformmetadaten zugreifen
- Mit diesen Methoden können Sie mehrere 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ört 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.
Berechtigungen
Für die meisten Methoden in der Runtime API ist keine Berechtigung erforderlich, mit Ausnahme von sendNativeMessage und connectNative, für die die Berechtigung nativeMessaging
erforderlich ist.
Manifest
Das folgende Beispiel zeigt, wie die Berechtigung nativeMessaging
im Manifest deklariert wird:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Anwendungsfälle
Einer Webseite ein Bild hinzufügen
Damit eine Webseite auf ein 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 vom Service Worker an ein Inhaltsskript 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 eine 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);
});
background.js:
// Example of a simple user data object
const user = {
username: 'demo-user'
};
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
// 2. A page requested user data, respond with a copy of `user`
if (message === 'get-user-data') {
sendResponse(user);
}
});
Feedback zur Deinstallation einholen
Viele Erweiterungen 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 für Erweiterungen
Weitere Runtime API-Beispiele finden Sie in der Demo „Manifest V3 – Web Accessible Resources“.
Typen
ContextFilter
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
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
Ein Kontext, der Erweiterungsinhalte hostet.
Attribute
-
contextId
String
Eine eindeutige Kennung für diesen Kontext
-
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 oder höherEine UUID des Dokuments, das die Verbindung geöffnet hat.
-
documentLifecycle
String optional
Chrome 106 oder höherDer 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öherDer Name der nativen Anwendung, die die Verbindung hergestellt hat, falls vorhanden.
-
Ursprung
String optional
Chrome 80 oder höherDer 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
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
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
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
Die Prozessorarchitektur der Maschine.
-
nacl_arch
Native Clientarchitektur. Dies kann auf einigen Plattformen von „arch“ abweichen.
-
os
Das Betriebssystem, auf dem Chrome ausgeführt wird.
PlatformNaclArch
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
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 disconnect 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) => {...}
-
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) => {...}
-
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öherDie zu sendende Nachricht. Dieses Objekt muss JSON-fähig sein.
-
RequestUpdateCheckStatus
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ückgabe
-
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ückgabe
-
Port, über den Nachrichten mit der Anwendung gesendet und empfangen werden können
getBackgroundPage()
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ückgabe
-
Promise<Window | undefined>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Ruft Informationen zu aktiven Kontexten ab, die mit dieser Erweiterung verknüpft sind
Parameter
-
Filter
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
Die übereinstimmenden Kontexte, falls vorhanden.
-
Rückgabe
-
Promise<ExtensionContext[]>
Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
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ückgabe
-
Objekt
Die Manifestdetails.
getPackageDirectoryEntry()
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ückgabe
-
Promise<DirectoryEntry>
Chrome 122 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getPlatformInfo()
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
-
Rückgabe
-
Promise<PlatformInfo>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
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ückgabe
-
String
Die voll qualifizierte URL zur Ressource.
openOptionsPage()
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ückgabe
-
Promise<void>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
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()
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öherRequestUpdateCheckResult-Objekt, das den Status der Updateprüfung und Details zum Ergebnis enthält, falls ein Update verfügbar ist
-
status
Ergebnis der Updateprüfung.
-
Version
String optional
Wenn ein Update verfügbar ist, enthält es die Version des verfügbaren Updates.
-
-
Rückgabe
-
Promise<object>
Chrome 109 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
restart()
chrome.runtime.restart()
Starten Sie das ChromeOS-Gerät neu, wenn die App im Kioskmodus ausgeführt wird. Andernfalls ist es wirkungslos.
restartAfterDelay()
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ückgabe
-
Promise<void>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
sendMessage()
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öherDer 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ückgabe
-
Versprechen<any>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
sendNativeMessage()
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öherDer 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ückgabe
-
Versprechen<any>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setUninstallURL()
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öherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
Veranstaltungen
onBrowserUpdateAvailable
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
-
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
-
onConnectNative
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
-
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
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
-
sendResponse
Funktion
Der Parameter
sendResponse
sieht so aus:() => void
-
Gibt zurück
Boolescher Wert | nicht definiert
-
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
-
sendResponse
Funktion
Der Parameter
sendResponse
sieht so aus:() => void
-
Gibt zurück
Boolescher Wert | nicht definiert
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Wird ausgelöst, wenn eine App oder das Gerät, auf dem sie ausgeführt wird, neu gestartet werden muss Die App sollte 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
-
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.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
-
onUserScriptMessage
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
-
sendResponse
Funktion
Der Parameter
sendResponse
sieht so aus:() => void
-
Gibt zurück
Boolescher Wert | nicht definiert
-