Verwenden Sie diese API, um Benutzer-Skripte zu registrieren. Dies sind Drittanbieter-Skripte, die dazu ausgelegt sind, Webseiten zu manipulieren oder neue Funktionen bereitzustellen. Die Registrierung eines Benutzer-Skriptes weist den Browser an, das Skript an Seiten anzuhängen, die den bei der Registrierung angegebenen URL-Mustern entsprechen.

Diese API bietet ähnliche Funktionen wiescripting aber mit Merkmalen, die für die Handhabung von Drittanbieter-Skripten geeignet sind.

Berechtigungen

Um diese API zu verwenden, benötigen Sie dieuserScripts Berechtigung undhost_permissions für die Seiten, auf denen Sie Skripte ausführen möchten. Der Ansatz zur Aktivierung der Nutzung dieser API variiert jedoch zwischen den Browsern:

• In Firefox istuserScripts einenur optionale Berechtigung, die im Manifest Keyoptional_permissions erklärt wird. Ihr Add-on muss prüfen, ob die Berechtigung erteilt wurde, indem es die Verfügbarkeit desuserScripts API-Namespace überprüft oderpermissions.contains() verwendet und sie, falls nicht, mitpermissions.request() anfordert.
• In Chrome istuserScripts eine zur Installationszeit angeforderte Berechtigung, die impermissions Manifest Key erklärt wird. Um jedoch die Nutzung der API zu ermöglichen, müssen Benutzerdie Entwicklerumgebung in Chrome einschalten.

Ausführungswelten

Wenn ein Benutzer-Skript registriert oder aktualisiert wird (mittelsuserScripts.register() oderuserScripts.update()), kann Ihr Add-on festlegen, dass es in einer isoliertenUSER_SCRIPT Welt oder in derMAIN Welt ausgeführt wird.

EineUSER_SCRIPT Welt bietet eine isolierte Ausführungsumgebung, die für eine Host-Seite oder andere Erweiterungen nicht zugänglich ist. Diese Isolierung ähnelt einerContent-Skript-Umgebung, außer dassUSER_SCRIPT Welten keinen Zugang zu Erweiterungs-APIs haben.

Benutzer-Skripte können sich eineUSER_SCRIPT-Welt teilen oder sich in einer eigenenUSER_SCRIPT Welt isolieren, indem sie dieworldId Eigenschaft vonRegisteredUserScript setzen. Die API ermöglicht einer Erweiterung, eine Content-Sicherheitsrichtlinie (CSP) für eineUSER_SCRIPT Welt mittelsuserScripts.configureWorld() zu konfigurieren.

In derMAIN Welt können Host-Seiten und andere Erweiterungen laufende Benutzer-Skripte sehen und darauf zugreifen. DieworldId Eigenschaft wird fürMAIN Welten nicht unterstützt.

Diese Werte der Ausführungswelten sind inExecutionWorld definiert.

Nachrichtenübermittlung

Wie Inhalts-Skripte und andere Erweiterungs-Skripte kommunizieren Benutzer-Skripte mit anderen Teilen einer Erweiterung durch Nachrichten mittelsruntime.sendMessage() undruntime.connect(). Erweiterungen empfangen jedoch Nachrichten mit den dediziertenruntime.onUserScriptMessage undruntime.onUserScriptConnect. Dedizierte Handler werden verwendet, da sie es erleichtern, Nachrichten von Benutzer-Skripten zu identifizieren, die ein weniger vertrauenswürdiger Kontext sind.

Um Messaging-APIs zu aktivieren, rufen SieuserScripts.configureWorld() mit dem Argumentmessaging auftrue gesetzt, bevor Sie ein Benutzer-Skript registrieren.

browser.userScripts.configureWorld({  messaging: true,});

Erweiterungs-Updates

Wenn eine Erweiterung aktualisiert wird, werden Benutzer-Skripte gelöscht. Um Skripte wiederherzustellen, fügen Sie Code in denruntime.onInstalled Ereignishandler der Erweiterung ein, der auf den Grund"update" reagiert.

Typen

userScripts.ExecutionWorld

Die Ausführungsumgebung für ein Skript, das mituserScripts.register()oderuserScripts.update() injiziert wird.

userScripts.RegisteredUserScript

Einobject, das vongetScripts() zurückgegeben wird, das registrierte Benutzer-Skripte darstellt und als Eingabe fürregister() undupdate() verwendet wird.

userScripts.ScriptSource

Der Code oder eine Datei-Quelle für ein Benutzer-Skript.

userScripts.UserScriptFilter

Eine Liste von Benutzer-Skripten, die vonuserScripts.getScripts() oderuserScripts.unregister() verarbeitet werden sollen.

userScripts.WorldProperties

Die Konfiguration einerUSER_SCRIPT Ausführungsumgebung.

Methoden

userScripts.configureWorld()

Konfiguriert eineUSER_SCRIPT Ausführungsumgebung für die Erweiterung.

userScripts.getScripts()

Gibt von der Erweiterung registrierte Benutzer-Skripte zurück.

userScripts.getWorldConfigurations()

Gibt alle registrierten Weltkonfigurationen der Erweiterung zurück.

userScripts.register()

Registriert Benutzer-Skripte für die Erweiterung.

userScripts.resetWorldConfiguration()

Setzt die Konfiguration für eine von der Erweiterung registrierteUSER_SCRIPT Welt zurück.

userScripts.unregister()

Hebt die Registrierung von Benutzer-Skripten auf, die von der Erweiterung registriert wurden.

userScripts.update()

Aktualisiert von der Erweiterung registrierte Benutzer-Skripte.

userScripts.execute()

Injektiert ein Benutzer-Skript in einen Zielkontext.

Beispielerweiterungen

• userScripts-mv3

Browser-Kompatibilität

Siehe auch

• browser.scripting