chrome.runtime

Beschreibung

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

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 Verwendung

Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Bereichen, in denen Ihre Erweiterungen kann Folgendes verwenden:

Nachrichtenweitergabe
Ihre Erweiterung kann mithilfe folgender Methoden und Ereignisse mit verschiedenen Kontexten innerhalb Ihrer Erweiterung und auch mit anderen Erweiterungen kommunizieren: connect(), onConnect onConnectExternal sendMessage(), onMessage und onMessageExternal Außerdem kann Ihre Erweiterung mithilfe von connectNative() und sendNativeMessage()
Auf Erweiterungs- und Plattformmetadaten zugreifen
Mit diesen Methoden können Sie mehrere spezifische Metadaten zur Erweiterung sowie zum Plattform. Zu dieser Kategorie gehören: getManifest() und getPlatformInfo()
Lebenszyklus und Optionen von Erweiterungen verwalten
Über diese Eigenschaften können Sie einige Metavorgänge auf der Erweiterung ausführen und die Seite mit den Optionen aufrufen. Methoden und Ereignisse in dieser Kategorie umfassen onInstalled, onStartup openOptionsPage() reload() requestUpdateCheck() und setUninstallURL().
Hilfsprogramme
Diese Methoden bieten einen Nutzen wie die Konvertierung interner Ressourcendarstellungen in externen Formaten. Zu dieser Kategorie gehören: 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

Wenn eine entpackte Erweiterung neu geladen wird, wird dies als Update behandelt. Das bedeutet, dass der Das Ereignis chrome.runtime.onInstalled wird mit dem Grund "update" ausgelöst. Dieses beinhaltet, wenn die Erweiterung mit chrome.runtime.reload() neu geladen wird.

Anwendungsfälle

Einer Webseite ein Bild hinzufügen

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

In diesem Beispiel fügt die Erweiterung logo.png der Seite hinzu, auf der die Inhalte Skript wird in dieses Skript eingefügt. Dazu wird runtime.getURL() verwendet, um ein vollständig qualifizierte URL. Zuerst muss das Asset jedoch als über das Web zugängliche Ressource im Manifest 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

Es ist üblich, dass für die Inhaltsskripte einer Erweiterung Daten von einem anderen Teil der Erweiterung verwaltet werden müssen. wie der Service Worker. Ähnlich wie zwei Browserfenster, die auf derselben Webseite geöffnet werden, zwei Kontexte können nicht direkt auf die Werte des jeweils anderen zugreifen. Stattdessen kann die Erweiterung message übergeben, um sie in diesen verschiedenen Kontexten zu koordinieren.

In diesem Beispiel benötigt das Inhaltsskript einige Daten vom Service Worker der Erweiterung, die Benutzeroberfläche zu initialisieren. Zum Abrufen dieser Daten wird die vom Entwickler definierte get-user-data-Nachricht übergeben. 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

Bei vielen Erweiterungen werden Umfragen nach der Deinstallation durchgeführt, um herauszufinden, und die Nutzerbindung zu verbessern. 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 Beispiele zur Runtime API finden Sie in der Demo zu Manifest V3 – Web Accessible Resources.

Typen

ContextFilter

Chrome 114 oder höher

Ein Filter für den Abgleich mit bestimmten Erweiterungskontexten. Kontexte müssen mit allen angegebenen Filtern übereinstimmen. Jeder nicht angegebene Filter stimmt mit allen verfügbaren Kontexten überein. Somit stimmt der Filter '{}' 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 nicht sichtbares Dokument an.

"SIDE_PANEL"
Gibt den Kontexttyp als Seitenleiste an.

ExtensionContext

Chrome 114 und höher

Ein Kontext, in dem Erweiterungsinhalte gehostet werden.

Attribute

  • Kontext-ID

    String

    Eine eindeutige Kennung für diesen Kontext

  • contextType

    ContextType

    Die Art des Kontexts, dem dieser entspricht.

  • documentId

    String optional

    Eine UUID für das Dokument, das mit diesem Kontext verknüpft ist, oder 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 der Kontext nicht in einem Frame gehostet wird.

  • Inkognito

    boolean

    Gibt an, ob der Kontext einem Inkognitoprofil zugeordnet ist.

  • tabId

    Zahl

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

  • windowId

    Zahl

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

MessageSender

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

Attribute

  • documentId

    String optional

    Chrome 106 und höher

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

  • documentLifecycle

    String optional

    Chrome 106 und höher

    Der Lebenszyklus des Dokuments, in dem die Verbindung geöffnet wurde, als der Port erstellt wurde. Beachten Sie, dass sich der Lebenszyklusstatus des Dokuments seit der Erstellung des Ports möglicherweise geändert hat.

  • frameId

    Zahl optional

    Der Frame, der die Verbindung geöffnet hat. 0 für Frames auf oberster Ebene, positiv für untergeordnete Frames. Dies wird nur festgelegt, wenn tab festgelegt ist.

  • id

    String optional

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

  • nativeApplication

    String optional

    Chrome 74 und höher

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

  • origin

    String optional

    Chrome (ab Version 80)

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

  • Tabulatortaste

    Tabulatortaste optional

    Die tabs.Tab, über die die Verbindung hergestellt wurde, falls vorhanden. Diese Property ist nur vorhanden, wenn die Verbindung über einen Tab (einschließlich Content-Scripts) hergestellt wurde, und nur, wenn es sich beim Empfänger um eine Erweiterung und nicht um eine App handelt.

  • tlsChannelId

    String optional

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

  • URL

    String optional

    Die URL der Seite oder des Frames, über die bzw. den die Verbindung hergestellt wurde. Wenn sich der Sender in einem iFrame befindet, ist dies die URL des iFrames und nicht die URL der Seite, auf der es gehostet wird.

OnInstalledReason

Chrome (ab Version 44)

Der Grund, warum dieses Ereignis gesendet wird.

Enum

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

"update"
Gibt den Grund des Ereignisses als Erweiterungsupdate an.

&quot;chrome_update&quot;
Gibt den Grund des Ereignisses als Chrome-Update an.

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

OnRestartRequiredReason

Chrome (ab Version 44)

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

Enum

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

&quot;os_update&quot;
Gibt den Grund des Ereignisses als Update des Betriebssystems an.

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

PlatformArch

Chrome (ab Version 44)

Die Prozessorarchitektur der Maschine.

Enum

"arm"
Gibt die Prozessarchitektur als Verzweigung an.

"arm64"
Gibt die Prozessarchitektur als arm64 an.

"x86-32"
Gibt die Prozessarchitektur als x86-32 an.

"x86-64"
Gibt die Prozessarchitektur als x86-64 an.

"mips"
Gibt die Verarbeitungsarchitektur 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

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

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

PlatformNaclArch

Chrome (ab Version 44)

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

Enum

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

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

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

"mips"
Gibt die Architektur des nativen Clients als Mips an.

"mips64"
Gibt die native Clientarchitektur als mips64 an.

PlatformOs

Chrome (ab Version 44)

Das Betriebssystem, auf dem Chrome ausgeführt wird.

Enum

"mac"
Gibt das Betriebssystem macOS an.

"win"
Gibt das Windows-Betriebssystem an.

"android"
Gibt das Android-Betriebssystem an.

"cros"
Gibt das Chrome-Betriebssystem an.

"linux"
Gibt das Betriebssystem Linux an.

&quot;openbsd&quot;
Gibt das OpenBSD-Betriebssystem an.

"fuchsia"
Gibt das Betriebssystem Fuchsia an.

Port

Ein -Objekt, das die Zwei-Wege-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 Anschluss von den anderen Enden getrennt ist. runtime.lastError kann festgelegt werden, wenn der Port aufgrund eines Fehlers getrennt wurde. Wenn der Port über disconnect geschlossen wird, wird dieses Ereignis nur am anderen Ende ausgelöst. Dieses Ereignis wird höchstens einmal ausgelöst (siehe auch Portlebensdauer).

    Die Funktion onDisconnect.addListener sieht so aus: 

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

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

      (port: Port) => void

  • 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

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

  • Verknüpfung aufheben

    voidm

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

    Die Funktion disconnect sieht so aus: 

    () => {...}

  • postMessage

    voidm

    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 sollte JSON-fähig sein.

RequestUpdateCheckStatus

Chrome (ab Version 44)

Ergebnis der Updateprüfung

Enum

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

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

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

Attribute

id

Die ID der Erweiterung/App.

Typ

String

lastError

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

Typ

Objekt

Attribute

  • Nachricht

    String optional

    Details zum aufgetretenen Fehler.

Methoden

connect()

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

Versucht, Listener innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder anderer Erweiterungen/Apps zu verbinden. Dies ist nützlich für Inhaltsskripte, die eine Verbindung zu den zugehörigen Erweiterungsprozessen, die Kommunikation zwischen Apps und Erweiterungen sowie Webnachrichten herstellen. Dadurch wird keine Verbindung zu einem Listener in einem Content-Skript hergestellt. Erweiterungen können über tabs.connect eine Verbindung zu Inhaltsskripten herstellen, die in Tabs eingebettet sind.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, zu der eine Verbindung hergestellt werden soll. Wenn nichts angegeben ist, wird versucht, eine Verbindung mit Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn Nachrichten über eine Webseite für Webnachrichten gesendet werden.

  • connectInfo

    Objekt (optional)

    • includeTlsChannelId

      Boolescher Wert optional

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

    • Name

      String optional

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

Returns

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

Parameter

  • Anwendung

    String

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

Returns

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

getBackgroundPage()

<ph type="x-smartling-placeholder"></ph> Versprechen Nur Vordergrund 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Ruft das JavaScript-Fenster ab -Objekt für die Hintergrundseite, 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 ist, 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-"Fenster" -Objekt für die Hintergrundseite.

Returns

  • Promise&lt;Window | nicht definiert>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getContexts()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 116 und höher MV3+ 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

Parameter

  • Filter

    ContextFilter

    Ein Filter 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

Returns

  • Promise&lt;ExtensionContext[]&gt;

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das 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.

Returns

  • Objekt

    Manifestdetails.

getPackageDirectoryEntry()

<ph type="x-smartling-placeholder"></ph> Versprechen Nur 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

Returns

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getPlatformInfo()

<ph type="x-smartling-placeholder"></ph> 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

Returns

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Parameter

  • Pfad

    String

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

Returns

  • String

    Die voll qualifizierte URL zur Ressource.

openOptionsPage()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.runtime.openOptionsPage(
  callback?: function,
)

Öffnen Sie nach Möglichkeit die Optionsseite der Erweiterung.

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

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das 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()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

Wichtig: Bei den meisten Erweiterungen oder Apps sollte diese Methode nicht verwendet werden, da Chrome bereits alle paar Stunden automatische Prüfungen durchführt. Sie können auf das runtime.onUpdateAvailable-Ereignis warten, ohne requestUpdateCheck aufrufen zu müssen.

Diese Methode eignet sich nur für den Aufruf in sehr wenigen Fällen, z. B. wenn Ihre Erweiterung mit einem Back-End-Dienst kommuniziert und der Back-End-Dienst festgestellt hat, dass die Version der Clienterweiterung sehr veraltet ist und Sie den Nutzer zum Aktualisieren auffordern möchten. Die meisten anderen Verwendungen von requestUpdateCheck, z. B. der bedingungslose Aufruf eines sich wiederholenden Timers, dienen wahrscheinlich nur dazu, Client-, Netzwerk- und Serverressourcen zu verschwenden.

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: object) => void

    • Ergebnis

      Objekt

      Chrome 109 oder höher

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

      • Ergebnis der Updateprüfung

      • Version

        String optional

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

Returns

  • Promise&lt;object&gt;

    Chrome 109 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das 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 kein Betrieb.

restartAfterDelay()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 53 und höher 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Starten Sie das ChromeOS-Gerät neu, wenn die App im Kioskmodus nach den festgelegten Sekunden ausgeführt wird. Wird vor Ablauf der Zeit noch einmal aufgerufen, verzögert sich der Neustart. Wird der Neustart mit dem Wert „-1“ abgebrochen, wird er abgebrochen. Im Nicht-Kioskmodus ist dies ein operativer Modus. Sie darf nur von der ersten Erweiterung wiederholt aufgerufen werden, um diese API aufzurufen.

Parameter

  • Sekunden

    Zahl

    Wartezeit in Sekunden vor einem Neustart des Geräts oder -1 zum Abbrechen eines geplanten Neustarts.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

sendMessage()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Sendet eine einzelne Nachricht an Ereignis-Listener innerhalb Ihrer Erweiterung oder einer anderen Erweiterung/App. Ähnlich wie runtime.connect, sendet aber nur eine einzelne Nachricht mit einer optionalen Antwort. Beim Senden an die Erweiterung wird das Ereignis runtime.onMessage in jedem Frame der Erweiterung (außer im Frame des Absenders) oder in runtime.onMessageExternal ausgelöst, falls es sich um eine andere Erweiterung handelt. Beachten Sie, dass Erweiterungen mit dieser Methode keine Nachrichten an Inhaltsskripte senden können. Wenn Sie Nachrichten an Inhaltsskripte senden möchten, verwenden Sie tabs.sendMessage.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Ohne Angabe wird die Nachricht an Ihre eigene Erweiterung oder App gesendet. Erforderlich, wenn Nachrichten über eine Webseite für Webnachrichten gesendet werden.

  • Nachricht

    beliebig

    Die zu sendende Nachricht. Diese Nachricht sollte ein JSON-fähiges Objekt sein.

  • 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 und höher

    Der Parameter callback sieht so aus: 

    (response: any) => void

    • Antwort

      beliebig

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

Returns

  • Versprechen<beliebig>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

sendNativeMessage()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

Parameter

  • Anwendung

    String

    Der Name des Hosts für natives Messaging.

  • Nachricht

    Objekt

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

  • callback

    Funktion optional

    Chrome 99 und höher

    Der Parameter callback sieht so aus: 

    (response: any) => void

    • Antwort

      beliebig

      Die vom nativen Nachrichtenhost gesendete Antwortnachricht. Tritt beim Herstellen der Verbindung zum nativen Messaging-Host ein Fehler auf, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Returns

  • Versprechen<beliebig>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

setUninstallURL()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

Parameter

  • URL

    String

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

  • callback

    Funktion optional

    Chrome (ab Version 45)

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Chrome 99 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onBrowserUpdateAvailable

<ph type="x-smartling-placeholder"></ph> Eingestellt
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Bitte verwende runtime.onRestartRequired.

Wird ausgelöst, wenn ein Chrome-Update verfügbar ist, aber nicht sofort installiert wird, da ein Neustart des Browsers 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 Content-Skript (von runtime.connect) hergestellt wird

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onConnectExternal

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onConnectNative

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onInstalled

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

Wird ausgelöst, wenn die Erweiterung zum ersten Mal installiert, auf eine neue Version aktualisiert und Chrome 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. Dies ist nur vorhanden, wenn 'Grund' ist „shared_module_update“.

      • previousVersion

        String optional

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

      • Der Grund, warum dieses Ereignis gesendet wird.

onMessage

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | nicht definiert

onMessageExternal

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | nicht definiert

onRestartRequired

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

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

Parameter

onStartup

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspend

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspendCanceled

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onUpdateAvailable

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

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

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 oder höher MV3+ 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

onUserScriptMessage

Chrome 115 oder höher 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 | nicht definiert