chrome.userScripts

Beschreibung

Verwenden Sie die userScripts API, um Nutzerskripts im Kontext von Nutzerskripts auszuführen.

Berechtigungen

userScripts

Wenn Sie die chrome.userScripts API verwenden möchten, fügen Sie der Datei „manifest.json“ die Berechtigung "userScripts" und für Websites, auf denen Sie Skripts 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 Nutzung

Ein Nutzerskript ist Code, der in eine Webseite eingeschleust wird, um ihr Aussehen oder Verhalten zu ändern. Skripts werden entweder von Nutzern erstellt oder aus einem Skript-Repository oder einer Nutzerskripterweiterung heruntergeladen.

Entwicklermodus für Nutzer der Erweiterung

Als Entwickler von Erweiterungen haben Sie in Ihrer Chrome-Installation bereits den Entwicklermodus aktiviert. Bei Nutzerskripterweiterungen müssen Ihre Nutzer außerdem den Entwicklermodus aktivieren. Nachfolgend finden Sie 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 sind standardmäßig nicht verlinkbar.

  2. Aktivieren Sie den Entwicklermodus, indem Sie auf die Ein/Aus-Schaltfläche 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 ausgibt. 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 Inhaltsskripte können in einer isolierten Welt oder auf 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 Inhaltsskripte für die Hostseite oder die Nutzer- und Inhaltsskripte anderer Erweiterungen nicht sichtbar. Auf der Hauptwelt ausgeführte Skripts sind für Hostseiten und andere Erweiterungen zugänglich und für Hostseiten und andere Erweiterungen sichtbar. Um die Welt auszuwählen, geben Sie beim Anrufen von userScripts.register() "USER_SCRIPT" oder "MAIN" weiter.

Rufen Sie userScripts.configureWorld() auf, um eine Sicherheitsrichtlinie für Inhalte für die Welt von USER_SCRIPT zu konfigurieren:

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

Werbebotschaften

Wie bei Inhaltsskripts und nicht sichtbaren Dokumenten kommunizieren Nutzerskripts mit anderen Teilen einer Erweiterung über Nachrichten. Das heißt, sie können runtime.sendMessage() und runtime.connect() wie jeder andere Teil einer Erweiterung aufrufen. Sie werden jedoch mithilfe spezieller Event-Handler empfangen (sie verwenden also weder onMessage noch onConnect). Diese Handler heißen runtime.onUserScriptMessage und runtime.onUserScriptConnect. Dedizierte Handler erleichtern die Erkennung von Nachrichten von Nutzerskripts, da diese ein weniger vertrauenswürdiger Kontext sind.

Bevor Sie eine Nachricht senden, müssen Sie configureWorld() aufrufen und das Argument messaging auf true setzen. Die Argumente csp und messaging können gleichzeitig übergeben werden.

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

Updates zu Erweiterungen

Nutzerskripts werden gelöscht, wenn eine Erweiterung aktualisiert wird. Sie können sie wieder hinzufügen, indem Sie Code im runtime.onInstalled-Event-Handler im Erweiterungsdienst-Worker ausführen. Sie antworten nur auf den Grund ("update"), der an den Callback für den Termin übergeben wurde.

Beispiel

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

Skript registrieren

Das folgende Beispiel zeigt einen einfachen Aufruf von register(). Das erste Argument ist ein Array von Objekten, mit denen die zu registrierenden Skripts definiert werden. Es gibt mehr Optionen als hier dargestellt.

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

Typen

ExecutionWorld

Die JavaScript-Welt, in der ein Nutzerskript ausgeführt werden kann.

Enum

"MAIN"
Gibt die Ausführungsumgebung des DOM an, also die Ausführungsumgebung, die gemeinsam mit dem JavaScript der Hostseite verwendet wird.

"USER_Script"
Gibt die Ausführungsumgebung an, die für Nutzerskripts spezifisch und von der CSP der Seite ausgenommen ist.

RegisteredUserScript

Attribute

  • allFrames

    Boolescher Wert optional

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

  • excludeGlobs

    string[] optional

    Gibt Platzhaltermuster für Seiten an, auf denen dieses Nutzerskript NICHT eingeschleust wird.

  • excludeMatches

    string[] optional

    Schließt Seiten aus, auf denen dieses Nutzerskript andernfalls eingeschleust werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

  • id

    String

    Die ID des im API-Aufruf angegebenen Nutzerskripts. Diese Property darf nicht mit einem „_“ beginnen, da sie als Präfix für generierte Script-IDs reserviert ist.

  • includeGlobs

    string[] optional

    Gibt Platzhaltermuster für Seiten an, auf denen dieses Nutzerskript eingeschleust wird.

  • Die Liste der ScriptSource-Objekte, die die Quellen von Skripts definieren, die in übereinstimmende Seiten eingefügt werden sollen.

  • Übereinstimmungen

    string[] optional

    Gibt an, auf welche Seiten dieses Nutzerskript eingeschleust wird. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster. Dieses Attribut muss für ${ref:register} angegeben werden.

  • runAt

    RunAt optional

    Gibt an, wann JavaScript-Dateien in die Webseite eingeschleust werden. Der bevorzugte und Standardwert ist document_idle.

  • welt

    ExecutionWorld optional

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

ScriptSource

Attribute

  • Code

    String optional

    String mit dem zu injizierenden JavaScript-Code. Es muss genau entweder file oder code angegeben werden.

  • Datei

    String optional

    Der Pfad der JavaScript-Datei, die relativ zum Stammverzeichnis der Erweiterung eingefügt werden soll. Es muss genau entweder file oder code angegeben werden.

UserScriptFilter

Attribute

  • ids

    string[] optional

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

WorldProperties

Attribute

  • CSP

    String optional

    Gibt den weltweiten CSP an. Die Standardeinstellung ist das World CSP (`ISOLATED`).

  • Nachrichtenfunktion; Messaging (context-sensitive!)

    Boolescher Wert optional

    Gibt an, ob Messaging-APIs verfügbar gemacht werden. Der Standardwert ist false.

Methoden

configureWorld()

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

Konfiguriert die Ausführungsumgebung `USER_SCRIPT`.

Parameter

  • Properties

    WorldProperties

    Enthält die Weltkonfiguration des Nutzerskripts.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

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

getScripts()

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

Gibt alle dynamisch registrierten Nutzerskripts für diese Erweiterung zurück

Parameter

Rückgaben

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

register()

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

Registriert ein oder mehrere Nutzerskripts für diese Erweiterung.

Parameter

  • Enthält eine Liste mit Nutzerskripts, die registriert werden sollen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

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

unregister()

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

Hebt die Registrierung aller dynamisch registrierten Nutzerskripts für diese Erweiterung auf

Parameter

  • Filter

    UserScriptFilter optional

    Wenn angegeben, hebt diese Methode nur die Registrierung der entsprechenden Nutzerskripts auf.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

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

update()

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

Aktualisiert ein oder mehrere Nutzerskripts für diese Erweiterung.

Parameter

  • Enthält eine Liste der Nutzerskripts, die aktualisiert werden sollen. Eine Eigenschaft wird nur für das vorhandene Skript aktualisiert, wenn sie in diesem Objekt angegeben ist. Falls beim Parsen/der Dateiüberprüfung des Skripts Fehler auftreten oder die angegebenen IDs keinem vollständig registrierten Skript entsprechen, werden keine Skripts aktualisiert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

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