userScripts
Verwenden Sie diese API, um benutzerdefinierte Skripte zu registrieren, also Drittanbieterskripte, die dazu gedacht sind, Webseiten zu manipulieren oder neue Funktionen bereitzustellen. Die Registrierung eines Benutzer-Skripts weist den Browser an, das Skript auf Seiten anzuhängen, die den während der Registrierung angegebenen URL-Mustern entsprechen.
Hinweis:
Dies ist die Dokumentation für die neue API-Version, die in Firefox für Manifest V3 verfügbar ist. Siehe userScripts (legacy) für Informationen über die API-Version, die in Firefox mit Manifest V2 verwendet werden kann.
Diese API bietet ähnliche Funktionen wie scripting, jedoch mit Merkmalen, die für die Handhabung von Drittanbieterskripten geeignet sind.
Berechtigungen
Um diese API zu nutzen, benötigen Sie die Berechtigung userScripts und host_permissions für die Websites, auf denen Sie Skripte ausführen möchten. Der Ansatz zur Aktivierung der Nutzung dieser API variiert jedoch zwischen den Browsern:
- In Firefox ist
userScriptseine ausschließlich optionale Berechtigung, die imoptional_permissions-Manifest-Schlüssel deklariert wird. Ihre Erweiterung muss überprüfen, ob die Berechtigung erteilt wurde, indem sie die Verfügbarkeit desuserScripts-API-Namespace überprüft oderpermissions.contains()verwendet und, falls nicht, diese mitpermissions.request()anfordert. - In Chrome ist
userScriptseine zur Installationszeit angeforderte Berechtigung, die impermissions-Manifest-Schlüssel deklariert wird. Nutzer müssen jedoch diechrome://extensions/-Benutzeroberfläche nutzen, um die Nutzung der API zu aktivieren.
Ausführungswelten
Wenn ein Benutzer-Skript registriert, aktualisiert oder ausgeführt wird (mithilfe von userScripts.register(), userScripts.update() und userScripts.execute() jeweils), kann Ihre Erweiterung festlegen, dass es in einer isolierten USER_SCRIPT-Welt oder 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 Isolation ähnelt einer Content-Skript-Umgebung, außer dass USER_SCRIPT-Welten nicht auf Erweiterungs-APIs zugreifen können.
Benutzer-Skripte können eine USER_SCRIPT-Welt teilen oder sich in einer solchen isolieren, indem sie die worldId-Eigenschaft von RegisteredUserScript setzen. Die API ermöglicht es einer Erweiterung, eine Content Security Policy (CSP) für eine USER_SCRIPT-Welt mithilfe von 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 Ausführungswelten sind definiert in ExecutionWorld.
Nachrichtenübermittlung
Wie Content-Skripte und andere Erweiterungs-Skripte kommunizieren Benutzer-Skripte mit anderen Teilen einer Erweiterung mit Nachrichten, die runtime.sendMessage() und runtime.connect() verwenden. Allerdings empfangen Erweiterungen Nachrichten über die dedizierten runtime.onUserScriptMessage und runtime.onUserScriptConnect. Dedizierte Handler werden verwendet, da sie es einfacher machen, Nachrichten von Benutzer-Skripten zu identifizieren, die in einem weniger vertrauenswürdigen Kontext ausgeführt werden.
Um Messaging-APIs zu aktivieren, rufen Sie userScripts.configureWorld() mit dem Argument messaging auf true gesetzt auf, 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 zum runtime.onInstalled-Event-Handler der Erweiterung hinzu, der auf den Grund "update" reagiert.
Typen
userScripts.ExecutionWorld-
Die Ausführungsumgebung für ein Skript, das mit
execute(),register()oderupdate()injiziert wird. userScripts.RegisteredUserScript-
Ein
object, das vongetScripts()zurückgegeben wird und registrierte Benutzer-Skripte repräsentiert und als Eingabe fürregister()undupdate()verwendet wird. userScripts.ScriptSource-
Der Code oder eine Dateiquelle für ein Benutzer-Skript, das in
execute()undRegisteredUserScriptverwendet wird. userScripts.UserScriptFilter-
Eine Liste von Benutzer-Skripten, die von
getScripts()oderunregister()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()-
Injektet ein Benutzer-Skript in einen Zielkontext.