userScripts

Verwenden Sie diese API, um Benutzerskripte zu registrieren, Drittanbieterskripte, die entwickelt wurden, um Webseiten zu manipulieren oder neue Funktionen bereitzustellen. Durch das Registrieren eines Benutzerskripts wird der Browser angewiesen, das Skript an Seiten anzufügen, 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 zur API, die in Firefox mit Manifest V2 verwendet werden kann.

Diese API bietet Möglichkeiten, ähnlich der scripting, jedoch mit Funktionen, die für die Verarbeitung von Drittanbieterskripten geeignet sind.

Berechtigungen

Um diese API zu verwenden, benötigen Sie die Berechtigung userScripts und host_permissions für Websites, auf denen Sie Skripte ausführen möchten. Der Ansatz zum Aktivieren des Einsatzes dieser API variiert jedoch zwischen den Browsern:

In Firefox ist userScripts eine nur optionale Berechtigung, die im Schlüssel optional_permissions des Manifests erklärt wird. Ihre Erweiterung muss prüfen, ob die Berechtigung gewährt wurde, indem sie die Verfügbarkeit des userScripts API-Namespace überprüft oder permissions.contains() verwendet und, falls nicht, die Berechtigung mit permissions.request() anfordert.
In Chrome ist userScripts eine während der Installation angeforderte Berechtigung, die im permissions Manifest-Schlüssel erklärt wird. Benutzer müssen jedoch die chrome://extensions/-Benutzeroberfläche verwenden, um die Nutzung der API zu aktivieren.

Ausführungswelten

Wenn ein Benutzerskript registriert, aktualisiert oder ausgeführt wird (mit userScripts.register(), userScripts.update() und userScripts.execute() jeweils), kann Ihre Erweiterung es so einstellen, dass es in einer isolierten USER_SCRIPT Welt oder der MAIN Welt läuft.

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 Umgebung für Inhaltsskripte, außer dass USER_SCRIPT Welten nicht auf Erweiterungs-APIs zugreifen können.

Benutzerskripte können eine USER_SCRIPT Welt teilen oder sich in einer USER_SCRIPT Welt 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 mit userScripts.configureWorld() zu konfigurieren.

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

Diese Ausführungswelt-Werte sind in ExecutionWorld definiert.

Nachrichtenübermittlung

Wie Inhaltsskripte und andere Erweiterungsskripte kommunizieren Benutzerskripte mit anderen Teilen einer Erweiterung über Nachrichten mit runtime.sendMessage() und runtime.connect(). Erweiterungen empfangen jedoch Nachrichten über die speziellen runtime.onUserScriptMessage und runtime.onUserScriptConnect. Spezielle Handler werden verwendet, da sie die Identifizierung von Nachrichten von Benutzerskripten erleichtern, die ein weniger vertrauenswürdiger Kontext sind.

Um Messaging-APIs zu aktivieren, rufen Sie userScripts.configureWorld() mit dem Argument messaging auf, das auf true gesetzt ist, bevor Sie ein Benutzerskript registrieren.

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

Erweiterungs-Updates

Wenn eine Erweiterung aktualisiert wird, werden Benutzerskripte gelöscht. Um Skripte wiederherzustellen, fügen Sie Code zu dem runtime.onInstalled Ereignishandler der Erweiterung hinzu, der auf den Grund "update" reagiert.

Typen

userScripts.ExecutionWorld: Die Ausführungsumgebung für ein mit execute(), register() oder update() injiziertes Skript.
userScripts.RegisteredUserScript: Ein object, das von getScripts() zurückgegeben wird und registrierte Benutzerskripte darstellt und als Eingabe für register() und update() verwendet wird.
userScripts.ScriptSource: Der Code oder eine Dateiquelle für ein Benutzerskript, das in execute() und RegisteredUserScript verwendet wird.
userScripts.UserScriptFilter: Eine Liste der von getScripts() oder unregister() zu verarbeitenden Benutzerskripte.
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 die von der Erweiterung registrierten Benutzerskripte zurück.
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 der Erweiterung auf.
userScripts.update(): Aktualisiert die von der Erweiterung registrierten Benutzerskripte.
userScripts.execute(): Injiiziert ein Benutzerskript in einen Zielkontext.

Beispielerweiterungen

userScripts-mv3

Browser-Kompatibilität

Siehe auch

browser.scripting

Help improve MDN

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden