userScripts
Verwenden Sie diese API, um Benutzerskripte zu registrieren, Drittanbieter-Skripte, die entwickelt wurden, um Webseiten zu manipulieren oder neue Funktionen bereitzustellen. Das Registrieren eines Benutzerskripts weist den Browser an, das Skript an 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), um Informationen über die API zu erhalten, die in Firefox mit Manifest V2 verwendet werden kann.
Diese API bietet ähnliche Funktionen wie scripting, jedoch mit Eigenschaften, die für den Umgang mit Drittanbieter-Skripten geeignet sind.
Berechtigungen
Um diese API zu verwenden, 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 nur optionale Berechtigung, die im Schlüsseloptional_permissionsdes Manifests deklariert wird. Ihre Erweiterung muss prüfen, ob die Berechtigung gewährt wurde, indem die Verfügbarkeit desuserScriptsAPI-Namensraums geprüft wird oderpermissions.contains()verwendet wird, und, falls nicht, diese mitpermissions.request()anfordern. - in Chrome ist
userScriptseine bei der Installation angeforderte Berechtigung, die im Schlüsselpermissionsdes Manifests deklariert wird. Es ist jedoch erforderlich, dass die Benutzer diechrome://extensions/Benutzeroberfläche verwenden, um die Nutzung der API zu aktivieren.
Ausführungsumgebungen
Wenn ein Benutzerskript registriert oder aktualisiert wird (mithilfe von userScripts.register() oder userScripts.update()), kann Ihre Erweiterung es so einstellen, 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 einer Host-Seite oder anderen Erweiterungen nicht zugänglich ist. Diese Isolation ähnelt einer Content-Skript-Umgebung, außer dass USER_SCRIPT-Welten keinen Zugriff auf Erweiterungs-APIs haben.
Benutzerskripte können sich eine USER_SCRIPT-Welt teilen oder sich durch das Setzen der worldId-Eigenschaft von RegisteredUserScript in einer USER_SCRIPT-Welt isolieren. Die API ermöglicht es einer Erweiterung, eine Content-Sicherheitsrichtlinie (CSP) für eine USER_SCRIPT-Welt mithilfe von userScripts.configureWorld() zu konfigurieren.
In der MAIN-Welt können Host-Seiten und andere Erweiterungen die ausgeführten Benutzerskripte sehen und darauf zugreifen. Die worldId-Eigenschaft wird für MAIN-Welten nicht unterstützt.
Diese Ausführungswelt-Werte sind in ExecutionWorld definiert.
Nachrichtenübermittlung
Wie Inhalts-Skripte und andere Erweiterungs-Skripte kommunizieren Benutzerskripte mit anderen Teilen einer Erweiterung über Nachrichten unter Verwendung von runtime.sendMessage() und runtime.connect(). Erweiterungen empfangen jedoch Nachrichten über die dedizierten runtime.onUserScriptMessage und runtime.onUserScriptConnect. Dedizierte Handler machen es einfacher, Nachrichten von Benutzerskripten 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 auf, bevor Sie ein Benutzerskript registrieren.
browser.userScripts.configureWorld({
messaging: true,
});
Erweiterungsupdates
Wenn eine Erweiterung aktualisiert wird, werden Benutzerskripte 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()oderuserScripts.update()injiziert wird. userScripts.RegisteredUserScript-
Ein
object, das durchgetScripts()zurückgegeben wird, das registrierte Benutzerskripte darstellt und als Eingabe fürregister()undupdate()verwendet wird. userScripts.ScriptSource-
Der Code oder eine Dateiquelle für ein Benutzerskript.
userScripts.UserScriptFilter-
Eine Liste von Benutzerskripten, die durch
userScripts.getScripts()oderuserScripts.unregister()verarbeitet werden soll. 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 Benutzerskripte zurück, die von der Erweiterung registriert wurden.
userScripts.getWorldConfigurations()-
Gibt alle registrierten Weltkonfigurationen der Erweiterung zurück.
userScripts.register()-
Registriert Benutzerskripte 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 Benutzerskripten auf, die von der Erweiterung registriert wurden.
userScripts.update()-
Aktualisiert Benutzerskripte, die von der Erweiterung registriert wurden.
userScripts.execute()-
Injektziert ein Benutzerskript in einen Zielkontext.