userScripts

Berechtigungen

Um diese API zu verwenden, benötigen Sie die userScripts Berechtigung und host_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 ist userScripts eine nur optionale Berechtigung, die im Manifest Key optional_permissions erklärt wird. Ihr Add-on muss prüfen, ob die Berechtigung erteilt wurde, indem es die Verfügbarkeit des userScripts API-Namespace überprüft oder permissions.contains() verwendet und sie, falls nicht, mit permissions.request() anfordert.
• In Chrome ist userScripts eine zur Installationszeit angeforderte Berechtigung, die im permissions Manifest Key erklärt wird. Um jedoch die Nutzung der API zu ermöglichen, müssen Benutzer die Entwicklerumgebung in Chrome einschalten.

Ausführungswelten

Wenn ein Benutzer-Skript registriert oder aktualisiert wird (mittels userScripts.register() oder userScripts.update()), kann Ihr Add-on festlegen, dass es in einer isolierten USER_SCRIPT Welt oder in der MAIN Welt ausgeführt wird.

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

Benutzer-Skripte können sich eine USER_SCRIPT-Welt teilen oder sich in einer eigenen USER_SCRIPT Welt isolieren, indem sie die worldId Eigenschaft von RegisteredUserScript setzen. Die API ermöglicht einer Erweiterung, eine Content-Sicherheitsrichtlinie (CSP) für eine USER_SCRIPT Welt mittels userScripts.configureWorld() zu konfigurieren.

In der MAIN Welt können Host-Seiten und andere Erweiterungen laufende Benutzer-Skripte sehen und darauf zugreifen. Die worldId Eigenschaft wird für MAIN Welten nicht unterstützt.

Diese Werte der Ausführungswelten sind in ExecutionWorld definiert.

Nachrichtenübermittlung

Wie Inhalts-Skripte und andere Erweiterungs-Skripte kommunizieren Benutzer-Skripte mit anderen Teilen einer Erweiterung durch Nachrichten mittels runtime.sendMessage() und runtime.connect(). Erweiterungen empfangen jedoch Nachrichten mit den dedizierten runtime.onUserScriptMessage und runtime.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 Sie userScripts.configureWorld() mit dem Argument messaging auf true 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 den runtime.onInstalled Ereignishandler der Erweiterung ein, der auf den Grund "update" reagiert.

Typen

userScripts.ExecutionWorld

Die Ausführungsumgebung für ein Skript, das mit userScripts.register() oder userScripts.update() injiziert wird.

userScripts.RegisteredUserScript

Ein object, das von getScripts() zurückgegeben wird, das registrierte Benutzer-Skripte darstellt und als Eingabe für register() und update() verwendet wird.

userScripts.ScriptSource

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

userScripts.UserScriptFilter

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

userScripts.WorldProperties

Die Konfiguration einer USER_SCRIPT Ausführungsumgebung.

Methoden

userScripts.configureWorld()

Konfiguriert eine USER_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 registrierte USER_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