chrome.userScripts

Beschreibung

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

Berechtigungen

userScripts

Wenn Sie die chrome.userScripts API verwenden möchten, fügen Sie Ihrer manifest.json-Datei die Berechtigung "userScripts" und den Websites, auf denen Sie Scripts ausführen möchten, 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. Scripts werden entweder von Nutzern erstellt oder aus einem Script-Repository oder einer Nutzerscript-Erweiterung heruntergeladen.

Entwicklermodus für Erweiterungsnutzer

Als Erweiterungs-Entwickler 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 es jeder andere Teil einer Erweiterung tun würde. 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 Erweiterungs-Dienstworker 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.

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

    Ausschlüsse von Seiten, 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 Wildcard-Muster für Seiten an, in die dieses Nutzerscript eingefügt werden soll.

  • 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

    Ausstehend

    Gibt die ID der Welt an, in der das Script ausgeführt werden soll. Nur gültig, wenn world fehlt oder USER_SCRIPT ist. Wenn Sie diesen Parameter weglassen, wird das Script in der Standard-Script-Welt des Nutzers ausgeführt. 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.

WorldProperties

Attribute

  • csp

    String optional

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

  • Messaging

    boolescher Wert optional

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

  • worldId

    String optional

    Ausstehend

    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 vorangehenden 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 beide nicht 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 beide nicht für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getWorldConfigurations()

Promise Ausstehend
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 beide nicht 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 beide nicht für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

resetWorldConfiguration()

Promise Ausstehend
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 beide nicht 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 beide nicht 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 Dateiüberprüfung Fehler auftreten oder die angegebenen IDs nicht zu einem vollständig registrierten Script gehören, 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.