chrome.userScripts

Beschreibung

Mit der userScripts API können Sie Nutzerscripts im Kontext „Nutzerscripts“ ausführen.

Berechtigungen

userScripts

Wenn Sie die User Scripts API verwenden möchten, chrome.userScriptsfügen Sie der Datei „manifest.json“ die Berechtigung "userScripts" und für Websites, auf denen Scripts ausgeführt werden sollen, die Berechtigung "host_permissions" hinzu.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Verfügbarkeit

Chrome 120+ MV3+

Konzepte und Verwendung

Ein Nutzerscript ist ein Code-Snippet, das in eine Webseite eingefügt wird, um ihr Aussehen oder Verhalten zu ändern. Im Gegensatz zu anderen Erweiterungsfunktionen wie Inhaltsscripts und der chrome.scripting API können Sie mit der User Scripts API beliebigen Code ausführen. Diese API ist für Erweiterungen erforderlich, in denen vom Nutzer bereitgestellte Scripts ausgeführt werden, die nicht im Rahmen Ihres Erweiterungspakets bereitgestellt werden können.

Entwicklermodus für Erweiterungsnutzer

Als Entwickler von Erweiterungen haben Sie den Entwicklermodus bereits in Ihrer Chrome-Installation aktiviert. Für Nutzerscript-Erweiterungen müssen Ihre Nutzer außerdem den Entwicklermodus aktivieren. Hier ist eine Anleitung, die Sie kopieren und in Ihre eigene Dokumentation einfügen können.

  1. Rufen Sie die Seite „Erweiterungen“ auf, indem Sie in einem neuen Tab chrome://extensions eingeben. chrome://-URLs können nicht verlinkt werden.

  2. Aktivieren Sie den Entwicklermodus, indem Sie auf den Schalter neben Entwicklermodus klicken.

    Auf der Seite „Erweiterungen“

    Seite „Erweiterungen“ (chrome://extensions)

Sie können feststellen, ob der Entwicklermodus aktiviert ist, indem Sie prüfen, ob chrome.userScripts einen Fehler zurückgibt. Beispiel:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

In isolierten Welten arbeiten

Sowohl Nutzer- als auch Inhaltsscripts können in einer separaten Welt oder in der Hauptwelt ausgeführt werden. Eine isolierte Welt ist eine Ausführungsumgebung, auf die eine Hostseite oder andere Erweiterungen nicht zugreifen können. So kann ein Nutzerskript seine JavaScript-Umgebung ändern, ohne dass sich dies auf die Hostseite oder die Nutzer- und Inhaltsscripts anderer Erweiterungen auswirkt. Umgekehrt sind Nutzer- und Inhaltsscripts für die Hostseite oder die Nutzer- und Inhaltsscripts anderer Erweiterungen nicht sichtbar. Scripts, die in der Hauptwelt ausgeführt werden, sind für Hostseiten und andere Erweiterungen zugänglich und für Hostseiten und andere Erweiterungen sichtbar. Wenn du die Welt auswählen möchtest, gib beim Aufruf von userScripts.register() "USER_SCRIPT" oder "MAIN" ein.

Wenn du eine Content Security Policy für die Welt USER_SCRIPT konfigurieren möchtest, ruf userScripts.configureWorld() auf:

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Messaging

Wie Inhaltsscripts und Offscreen-Dokumente kommunizieren auch Nutzerscripts über Nachrichten mit anderen Teilen einer Erweiterung. Das bedeutet, dass sie runtime.sendMessage() und runtime.connect() aufrufen können, wie jeder andere Teil einer Erweiterung. Sie werden jedoch über spezielle Ereignis-Handler empfangen, d. h., es wird nicht onMessage oder onConnect verwendet. Diese Handler heißen runtime.onUserScriptMessage und runtime.onUserScriptConnect. Spezielle Handler erleichtern die Identifizierung von Nachrichten aus Nutzerscripts, die einen weniger vertrauenswürdigen Kontext darstellen.

Bevor du eine Nachricht sendest, musst du configureWorld() mit dem Argument messaging auf true setzen. Sowohl das csp- als auch das messaging-Argument können gleichzeitig übergeben werden.

chrome.userScripts.configureWorld({
  messaging: true
});

Erweiterungsupdates

Nutzerscripts werden gelöscht, wenn eine Erweiterung aktualisiert wird. Sie können sie wieder hinzufügen, indem Sie Code im Ereignishandler runtime.onInstalled im Service Worker der Erweiterung ausführen. Antworten Sie nur auf den "update"Grund, der an den Ereignis-Callback übergeben wurde.

Beispiel

Dieses Beispiel stammt aus dem userScript-Beispiel in unserem Samples-Repository.

Script registrieren

Das folgende Beispiel zeigt einen einfachen Aufruf von register(). Das erste Argument ist ein Array von Objekten, das die zu registrierenden Scripts definiert. Es gibt mehr Optionen als hier angezeigt.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Typen

ExecutionWorld

Die JavaScript-Umgebung, in der ein Nutzerscript ausgeführt wird.

Enum

„MAIN“
Gibt die Ausführungsumgebung des DOM an, die mit dem JavaScript der Hostseite gemeinsam genutzt wird.

USER_SCRIPT
Gibt die Ausführungsumgebung an, die für Nutzerscripts spezifisch ist und vom CSP der Seite ausgenommen ist.

InjectionResult

Ausstehend

Attribute

  • documentId

    String

    Das mit der Injection verknüpfte Dokument.

  • Fehler

    String optional

    Der Fehler, falls vorhanden. error und result schließen sich gegenseitig aus.

  • frameId

    Zahl

    Der Frame, der mit der Injection verknüpft ist.

  • Ergebnis

    beliebig optional

    Das Ergebnis der Scriptausführung.

InjectionTarget

Ausstehend

Attribute

  • allFrames

    boolescher Wert optional

    Gibt an, ob das Script in alle Frames auf dem Tab eingefügt werden soll. Die Standardeinstellung ist "false". Das darf nicht der Fall sein, wenn frameIds angegeben ist.

  • documentIds

    string[] optional

    Die IDs der Dokumente, in die eingefügt werden soll. Dieser darf nicht festgelegt werden, wenn frameIds festgelegt ist.

  • frameIds

    number[] optional

    Die IDs der Frames, in die eingefügt werden soll.

  • tabId

    Zahl

    Die ID des Tabs, in den eingefügt werden soll.

RegisteredUserScript

Attribute

  • allFrames

    boolescher Wert optional

    Wenn „true“ festgelegt ist, wird der Code in alle Frames eingefügt, auch wenn der Frame nicht der oberste Frame auf dem Tab ist. Jeder Frame wird unabhängig auf URL-Anforderungen geprüft. Wenn die URL-Anforderungen nicht erfüllt sind, wird der Frame nicht in untergeordnete Frames eingefügt. Standardmäßig ist „false“ festgelegt, d. h., es wird nur der oberste Frame abgeglichen.

  • excludeGlobs

    string[] optional

    Gibt Platzhaltermuster für Seiten an, in die dieses Nutzerscript NICHT eingefügt werden soll.

  • excludeMatches

    string[] optional

    Schließt Seiten aus, in die dieses Nutzerscript sonst eingefügt würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

  • id

    String

    Die ID des Nutzerscripts, die im API-Aufruf angegeben ist. Diese Eigenschaft darf nicht mit „_“ beginnen, da dies ein Präfix für generierte Script-IDs ist.

  • includeGlobs

    string[] optional

    Gibt Platzhaltermuster für Seiten an, in die dieses Nutzerscript eingefügt wird.

  • js

    ScriptSource[] optional

    Die Liste der ScriptSource-Objekte, die die Quellen der Scripts definieren, die in übereinstimmende Seiten eingefügt werden sollen. Diese Property muss für ${ref:register} angegeben werden. Wenn sie angegeben ist, muss es sich um ein nicht leeres Array handeln.

  • stimmt überein mit

    string[] optional

    Gibt an, in welche Seiten dieses Nutzer-Script eingefügt werden soll. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster. Dieses Attribut muss für ${ref:register} angegeben werden.

  • runAt

    RunAt optional

    Hier wird festgelegt, wann JavaScript-Dateien in die Webseite eingefügt werden. Der bevorzugte und Standardwert ist document_idle.

  • Welt

    ExecutionWorld optional

    Die JavaScript-Ausführungsumgebung, in der das Script ausgeführt werden soll. Der Standardwert ist `USER_SCRIPT`.

  • worldId

    String optional

    Chrome 133 und höher

    Gibt die Welt-ID des Nutzerscripts an, in der es ausgeführt werden soll. Wenn Sie diesen Parameter weglassen, wird das Script in der Standard-Script-Welt des Nutzers ausgeführt. Nur gültig, wenn world fehlt oder USER_SCRIPT ist. Werte mit einem vorangestellten Unterstrich (_) sind reserviert.

ScriptSource

Attribute

  • Code

    String optional

    Ein String, der den einzuschleusenden JavaScript-Code enthält. Es muss genau eine von file oder code angegeben werden.

  • Datei

    String optional

    Der Pfad der einzuschleusenden JavaScript-Datei relativ zum Stammverzeichnis der Erweiterung. Es muss genau eine von file oder code angegeben werden.

UserScriptFilter

Attribute

  • ids

    string[] optional

    getScripts gibt nur Scripts mit den in dieser Liste angegebenen IDs zurück.

UserScriptInjection

Ausstehend

Attribute

  • injectImmediately

    boolescher Wert optional

    Gibt an, ob die Injection so schnell wie möglich im Ziel ausgelöst werden soll. Dies ist jedoch keine Garantie dafür, dass die Injection vor dem Laden der Seite erfolgt, da die Seite möglicherweise bereits geladen wurde, wenn das Script das Ziel erreicht.

  • Liste der ScriptSource-Objekte, die die Quellen der Scripts definieren, die in das Ziel eingefügt werden sollen.

  • Details zum Ziel, in das das Script eingefügt werden soll.

  • Welt

    ExecutionWorld optional

    Die JavaScript-Umgebung, in der das Script ausgeführt werden soll. Der Standardwert ist USER_SCRIPT.

  • worldId

    String optional

    Gibt die ID der Welt an, in der das Nutzerscript ausgeführt werden soll. Wenn Sie diesen Parameter weglassen, wird das Script in der Standard-Script-Welt des Nutzers ausgeführt. Nur gültig, wenn world fehlt oder USER_SCRIPT ist. Werte mit einem vorangestellten Unterstrich (_) sind reserviert.

WorldProperties

Attribute

  • csp

    String optional

    Gibt den Welt-CSP an. Standardmäßig ist die `ISOLATED`-Welt-CSP ausgewählt.

  • Messaging

    boolescher Wert optional

    Gibt an, ob Messaging-APIs freigegeben sind. Der Standardwert ist false.

  • worldId

    String optional

    Chrome 133 und höher

    Gibt die ID der zu aktualisierenden Nutzerscript-Welt an. Wenn nicht angegeben, werden die Eigenschaften der Standard-Script-Welt des Nutzers aktualisiert. Werte mit einem vorangestellten Unterstrich (_) sind reserviert.

Methoden

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Konfiguriert die `USER_SCRIPT`-Ausführungsumgebung.

Parameter

  • Properties

    WorldProperties

    Enthält die Weltkonfiguration des Nutzerscripts.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

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

execute()

Promise Ausstehend
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

Ein Script wird in einen Zielkontext eingefügt. Standardmäßig wird das Script bei document_idle ausgeführt oder sofort, wenn die Seite bereits geladen wurde. Wenn die Property injectImmediately festgelegt ist, wird das Script ohne Wartezeit eingefügt, auch wenn die Seite noch nicht vollständig geladen ist. Wenn das Script zu einem Versprechen führt, wartet der Browser, bis das Versprechen erfüllt ist, und gibt den resultierenden Wert zurück.

Parameter

Ausgabe

  • Promise<InjectionResult[]>

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

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Gibt alle dynamisch registrierten Nutzerscripts für diese Erweiterung zurück.

Parameter

  • Filter

    UserScriptFilter optional

    Wenn diese Methode angegeben ist, werden nur die Nutzerscripts zurückgegeben, die dem Wert entsprechen.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (scripts: RegisteredUserScript[]) => void

Ausgabe

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

getWorldConfigurations()

Promise Chrome 133 und höher 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Ruft alle registrierten Weltkonfigurationen ab.

Parameter

Ausgabe

  • Promise<WorldProperties[]>

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

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Hiermit werden ein oder mehrere Nutzerscripts für diese Erweiterung registriert.

Parameter

  • Enthält eine Liste der zu registrierenden Nutzerscripts.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

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

resetWorldConfiguration()

Promise Chrome 133 und höher 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Setzt die Konfiguration für eine Nutzerskriptwelt zurück. Für alle Scripts, die in die Welt mit der angegebenen ID eingefügt werden, wird die Standardkonfiguration der Welt verwendet.

Parameter

  • worldId

    String optional

    Die ID der zu zurücksetzenden Script-Welt des Nutzers. Wenn Sie diese Option weglassen, wird die Konfiguration der Standardwelt zurückgesetzt.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

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

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Alle dynamisch registrierten Nutzerscripts für diese Erweiterung werden abgemeldet.

Parameter

  • Filter

    UserScriptFilter optional

    Wenn diese Methode angegeben ist, werden nur die Nutzerscripts deregistriert, die mit ihr übereinstimmen.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

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

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Aktualisiert ein oder mehrere Nutzerscripts für diese Erweiterung.

Parameter

  • Enthält eine Liste der zu aktualisierenden Nutzerscripts. Eine Property wird nur für das vorhandene Script aktualisiert, wenn sie in diesem Objekt angegeben ist. Wenn beim Parsen des Scripts oder bei der Dateivalidierung Fehler auftreten oder die angegebenen IDs nicht einem vollständig registrierten Script entsprechen, werden keine Scripts aktualisiert.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

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