userScripts.register() (Legacy)

Warnung: Dies ist die Dokumentation für die veraltete userScripts-API. Sie ist in Firefox für Manifest V2 verfügbar. Für Funktionen, die mit User-Skripten in Manifest V3 arbeiten, siehe die neue userScripts-API.

Diese Methode ermöglicht es, User-Skripte von den Seiten einer Erweiterung (wie der Hintergrundseite) aus zu registrieren.

Diese Methode ist der contentScripts.register()-API-Methode sehr ähnlich (zum Beispiel geben beide ein Promise zurück, das auf ein API-Objekt mit einer unregister()-Methode zum Deregistrieren des Skripts aufgelöst wird). Es gibt jedoch Unterschiede in den unterstützten Optionen.

Diese Methode ist asynchron und gibt ein Promise zurück.

Syntax

js
const registeredUserScript = await browser.userScripts.register(
  userScriptOptions       // object
);
// …
await registeredUserScript.unregister();

Parameter

userScriptOptions

object. Repräsentiert die zu registrierenden User-Skripte. Es hat eine ähnliche Syntax wie contentScripts.register().

Das UserScriptOptions-Objekt hat folgende Eigenschaften:

scriptMetadata Optional

Ein JSON-Objekt, das beliebige Metadateneigenschaften enthält, die den registrierten User-Skripten zugeordnet sind. Diese Eigenschaften müssen jedoch serialisierbar sein, damit sie mit dem strukturierten Klon-Algorithmus kompatibel sind. Diese Metadaten werden verwendet, um Details vom Skript an das API-Skript zu übermitteln, beispielsweise Details zu einem Subset der APIs, die vom API-Skript injiziert werden sollen. Die API selbst verwendet diese Metadaten jedoch nicht.

allFrames Optional

Entspricht all_frames im Schlüssel content_scripts.

cookieStoreId Optional

Ein Array von Cookie-Store-ID-Strings oder ein String, der eine Cookie-Store-ID enthält. Registriert das User-Skript in den Tabs, die zu den Cookie-Store-IDs gehören. Dies ermöglicht es, Skripte für alle Standard- oder nicht-kontextuellen Identitäten von Tabs, für private Tabs (wenn die Erweiterung im privaten Modus aktiviert ist), Tabs einer kontextuellen Identität oder eine Kombination dieser zu registrieren.

excludeGlobs Optional

Entspricht exclude_globs im Schlüssel content_scripts.

excludeMatches Optional

Entspricht exclude_matches im Schlüssel content_scripts.

includeGlobs Optional

Entspricht include_globs im Schlüssel content_scripts.

js

Ein Array von Objekten. Jedes Objekt hat entweder eine Eigenschaft namens file, die eine URL enthält (beginnend vom manifest.json der Erweiterung und zeigend auf eine JavaScript-Datei zum Registrieren), oder eine Eigenschaft namens code, die JavaScript-Code enthält, der registriert werden soll.

matchAboutBlank Optional

Entspricht match_about_blank im Schlüssel content_scripts.

matches

Entspricht matches im Schlüssel content_scripts. Die in matches bereitgestellten URL-Muster müssen durch die in der Manifestdatei definierten Host-Berechtigungen im permission-Eigenschaft aktiviert oder vom Benutzer aus der Liste der optional_permissions aktiviert werden. Wenn beispielsweise matches https://mozilla.org/a enthält, wird das Skript nur registriert, wenn die Host-Berechtigungen beispielsweise https://mozilla.org/* enthalten. Wenn das URL-Muster nicht aktiviert ist, schlägt der Registrierungsvorgang mit der Fehlermeldung "Permission denied to register a user script for ORIGIN" fehl.

runAt Optional

Entspricht run_at im Schlüssel content_scripts.

Im Gegensatz zu den Optionen für Content-Skripte hat das userScriptOptions-Objekt keine CSS-Eigenschaft. Verwenden Sie contentScripts.register(), um Stylesheets dynamisch zu registrieren und abzumelden.

Rückgabewert

Ein Promise, der mit einem RegisteredUserScript-Objekt aufgelöst wird, das zum Deregistrieren der User-Skripte verwendet wird.

Hinweis: User-Skripte werden abgemeldet, wenn die zugehörige Erweiterungsseite (von der die User-Skripte registriert wurden) entladen wird. Sie sollten daher User-Skripte von einer Erweiterungsseite aus registrieren, die mindestens so lange besteht, wie Sie möchten, dass die User-Skripte registriert bleiben.

Browser-Kompatibilität

Siehe auch