browser.userScripts

Beschreibung

Verwenden Sie die userScripts API, um Nutzerscripts im Kontext von Nutzerscripts auszuführen.

Berechtigungen

userScripts

Wenn Sie die User Scripts API (browser.userScripts) verwenden möchten, fügen Sie die Berechtigung "userScripts" in Ihre manifest.json-Datei ein und "host_permissions" für Websites, auf denen Sie Scripts ausführen möchten.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Verfügbarkeit

Chrome 120+ browser.* seit Chrome 148 MV3+

Konzepte und Verwendung

Ein Userscript ist ein Code-Snippet, das in eine Webseite eingefügt wird, um deren Darstellung oder Verhalten zu ändern. Im Gegensatz zu anderen Erweiterungsfunktionen wie Inhaltsskripts und der browser.scripting API können Sie mit der User Scripts API beliebigen Code ausführen. Diese API ist für Erweiterungen erforderlich, die vom Nutzer bereitgestellte Skripts ausführen, die nicht als Teil des Erweiterungspakets bereitgestellt werden können.

Verwendung der userScripts API aktivieren

Nachdem Ihre Erweiterung die Berechtigung zur Verwendung der userScripts API erhalten hat, müssen Nutzer eine bestimmte Einstellung aktivieren, damit Ihre Erweiterung die API verwenden kann. Die erforderliche Einstellung und das Verhalten der API, wenn sie deaktiviert ist, variieren je nach Chrome-Version.

Mit der folgenden Prüfung können Sie feststellen, welche Einstellung der Nutzer aktivieren muss, z. B. beim Onboarding neuer Nutzer:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

In den folgenden Abschnitten werden die verschiedenen Schalter und ihre Aktivierung beschrieben.

Chrome-Versionen vor 138 (Umschaltfläche für den Entwicklermodus)

Als Entwickler von Erweiterungen haben Sie den Entwicklermodus in Ihrer Chrome-Installation bereits aktiviert. Ihre Nutzer müssen außerdem den Entwicklermodus aktivieren.

Sie können die folgende Anleitung kopieren und in die Dokumentation Ihrer Erweiterung einfügen, damit Ihre Nutzer sie sehen können.

1. Rufen Sie die Seite „Erweiterungen“ auf, indem Sie chrome://extensions in einem neuen Tab eingeben. (chrome://-URLs können nicht verlinkt werden.)

2. Aktivieren Sie den Entwicklermodus, indem Sie auf den Schalter neben Entwicklermodus klicken.

   

   Seite „Erweiterungen“ (chrome://extensions)

Hinweis: Wenn der Entwicklermodus nicht aktiviert ist, wird beim Zugriff auf browser.userScripts ein Fehler angezeigt. Anhand dieses Fehlers können Sie die API-Verfügbarkeit ermitteln. Weitere Informationen finden Sie unter API-Verfügbarkeit prüfen.

Chrome-Versionen 138 und höher (Einstellung „Nutzerscripts zulassen“)

Der Ein/Aus-Button Nutzerscripts zulassen befindet sich auf der Detailseite der jeweiligen Erweiterung (z. B. chrome://extensions/?id=IHRE_ERWEITERUNGS_ID).

Sie können die folgende Anleitung kopieren und in die Dokumentation Ihrer Erweiterung für Ihre Nutzer einfügen:

1. Rufen Sie die Seite „Erweiterungen“ auf, indem Sie chrome://extensions in einem neuen Tab eingeben. (chrome://-URLs können nicht verlinkt werden.)
2. Klicken Sie auf der Erweiterungskarte auf den Button „Details“, um ausführliche Informationen zur Erweiterung aufzurufen.
3. Klicken Sie auf den Ein/Aus-Button neben Nutzerskripts zulassen.

Ein-/Ausschalten von „Nutzerscripts zulassen“ (chrome://extensions/?id=abc...)

Hinweis: Wenn die Option Nutzerskripts zulassen nicht aktiviert ist, ist browser.userScripts nicht definiert. Dieser undefinierte Status (ähnlich dem Verhalten anderer APIs) wird nur zurückgesetzt, wenn ein Erweiterungsskriptkontext neu geladen wird. Wenn ein Nutzer beispielsweise den Zugriff widerruft, während dein Service Worker ausgeführt wird, bleibt browser.userScripts definiert. In diesem Szenario wird jedoch beim Versuch, eine der Methoden aufzurufen, ein Fehler ausgegeben.

API-Verfügbarkeit prüfen

Wir empfehlen die folgende Prüfung, um festzustellen, ob die userScripts API aktiviert ist, da sie in allen Chrome-Versionen funktioniert. Bei dieser Prüfung wird versucht, eine browser.userScripts()-Methode aufzurufen, die immer erfolgreich sein sollte, wenn die API verfügbar ist. Wenn dieser Aufruf einen Fehler ausgibt, ist die API nicht verfügbar:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

In isolierten Welten arbeiten

Sowohl Nutzer- als auch Inhaltsskripts können in einer isolierten Welt oder in der Hauptwelt ausgeführt werden. Eine isolierte Welt ist eine Ausführungsumgebung, auf die eine Hostseite oder andere Erweiterungen nicht zugreifen können. So kann ein Nutzerscript seine JavaScript-Umgebung ändern, ohne die Hostseite oder die Nutzer- und Inhaltsscripts anderer Erweiterungen zu beeinträchtigen. Umgekehrt sind Nutzerscripts (und Inhaltsscripts) für die Hostseite oder die Nutzer- und Inhaltsscripts anderer Erweiterungen nicht sichtbar. Scripts, die in der Hauptwelt ausgeführt werden, sind für Hostseiten und andere Erweiterungen zugänglich und sichtbar. Wenn Sie die Welt auswählen möchten, übergeben Sie beim Aufrufen von userScripts.register() den Wert "USER_SCRIPT" oder "MAIN".

Wenn Sie eine Content Security Policy für die USER_SCRIPT-Welt konfigurieren möchten, rufen Sie userScripts.configureWorld() auf:

browser.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Messaging

Wie Inhaltsskripts und Offscreen-Dokumente kommunizieren auch Nutzerscripts mit anderen Teilen einer Erweiterung über Messaging. Das bedeutet, dass sie runtime.sendMessage() und runtime.connect() wie jeder andere Teil einer Erweiterung aufrufen können. Sie werden jedoch über dedizierte Event-Handler empfangen (d. h. sie verwenden nicht onMessage oder onConnect). Diese Handler heißen runtime.onUserScriptMessage und runtime.onUserScriptConnect. Spezielle Handler erleichtern die Identifizierung von Nachrichten aus Nutzerscripts, die einen weniger vertrauenswürdigen Kontext darstellen.

Bevor Sie eine Nachricht senden, müssen Sie configureWorld() aufrufen, wobei das Argument messaging auf true gesetzt ist. Beachten Sie, dass die Argumente csp und messaging gleichzeitig übergeben werden können.

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

Erweiterungsupdates

Nutzerskripts werden gelöscht, wenn eine Erweiterung aktualisiert wird. Sie können sie wieder hinzufügen, indem Sie Code im runtime.onInstalled-Event-Handler im Service Worker der Erweiterung ausführen. Reagieren Sie nur auf den "update"-Grund, der an den Ereignis-Callback übergeben wird.

Beispiel

Dieses Beispiel stammt aus dem userScript-Beispiel in unserem Beispiel-Repository.

Script registrieren

Das folgende Beispiel zeigt einen einfachen Aufruf von register(). Das erste Argument ist ein Array von Objekten, die die zu registrierenden Skripts definieren. Es gibt mehr Optionen als die hier gezeigten.

browser.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Typen

ExecutionWorld

Die JavaScript-Welt, in der ein Nutzerskript ausgeführt werden soll.

Enum

"MAIN"
Gibt die Ausführungsumgebung des DOM an, die mit dem JavaScript der Hostseite geteilt wird.

"USER_SCRIPT"
Gibt die Ausführungsumgebung an, die für Nutzerscripts spezifisch ist und von der CSP der Seite ausgenommen ist.

InjectionResult

Chrome 135 und höher browser.* seit Chrome 148

Attribute

• documentId

  String

  Das mit der Injektion verknüpfte Dokument.

• Fehler

  String optional

  Der Fehler, falls vorhanden. error und result schließen sich gegenseitig aus.

• frameId

  Zahl

  Der mit der Injektion verknüpfte Frame.

• Ergebnis

  any optional

  Das Ergebnis der Skriptausführung.

InjectionTarget

Chrome 135 und höher browser.* seit Chrome 148

Attribute

• allFrames

  Boolesch optional

  Gibt an, ob das Script in alle Frames im Tab eingefügt werden soll. Die Standardeinstellung ist "false". Dies darf nicht „true“ sein, wenn frameIds angegeben ist.

• documentIds

  string[] optional

  Die IDs bestimmter documentIds, in die eingefügt werden soll. Diese darf nicht festgelegt werden, wenn frameIds festgelegt ist.

• frameIds

  number[] optional

  Die IDs bestimmter Frames, in die eingefügt werden soll.

• tabId

  Zahl

  Die ID des Tabs, in den der Code eingefügt werden soll.

RegisteredUserScript

Attribute

• allFrames

  Boolesch optional

  Wenn „true“, wird das Script in alle Frames eingefügt, auch wenn der Frame nicht der oberste Frame im Tab ist. Jeder Frame wird unabhängig auf Anforderungen an URLs geprüft. Wenn die Anforderungen an URLs nicht erfüllt sind, wird das Skript nicht in untergeordnete Frames eingefügt. Die Standardeinstellung ist „false“, d. h., dass nur der oberste Frame abgeglichen wird.

• excludeGlobs

  string[] optional

  Gibt Platzhaltermuster für Seiten an, in die dieses Nutzerskript NICHT eingefügt wird.

• excludeMatches

  string[] optional

  Schließt Seiten aus, in die dieses Nutzerscript sonst eingefügt werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

• id

  String

  Die ID des im API-Aufruf angegebenen Nutzerscripts. Diese Property darf nicht mit einem Unterstrich („_“) beginnen, da dieser als Präfix für generierte Script-IDs reserviert ist.

• includeGlobs

  string[] optional

  Gibt Platzhaltermuster für Seiten an, in die dieses Nutzerscript eingefügt wird.

• js

  ScriptSource[] optional

  Die Liste der ScriptSource-Objekte, die Quellen von Skripts definieren, die in übereinstimmende Seiten eingefügt werden sollen. Diese Property muss für ${ref:register} angegeben werden und muss ein nicht leeres Array sein.

• stimmt überein mit

  string[] optional

  Gibt an, in welche Seiten dieses Nutzerscript eingefügt wird. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster. Dieses Attribut muss für ${ref:register} angegeben werden.

• runAt

  RunAt optional

  Gibt an, wann JavaScript-Dateien in die Webseite eingefügt werden. Der bevorzugte und Standardwert ist document_idle.

• Welt

  ExecutionWorld optional

  Die JavaScript-Ausführungsumgebung, in der das Script ausgeführt werden soll. Der Standardwert ist `USER_SCRIPT`.

• worldId

  String optional

  Chrome 133 und höher browser.* seit Chrome 148

  Gibt die ID der Welt des Nutzerscripts an, in der es ausgeführt werden soll. Wenn nichts angegeben ist, wird das Script in der Standard-Nutzerscript-Welt ausgeführt. Nur gültig, wenn world weggelassen wird oder USER_SCRIPT ist. Werte mit führenden Unterstrichen (_) sind reserviert.

ScriptSource

Attribute

• Code

  String optional

  Ein String, der den einzufügenden JavaScript-Code enthält. Es muss genau eines von file und code angegeben werden.

• Datei

  String optional

  Der Pfad der einzufügenden JavaScript-Datei relativ zum Stammverzeichnis der Erweiterung. Es muss genau eines von file und code angegeben werden.

UserScriptFilter

Attribute

• ids

  string[] optional

  getScripts gibt nur Skripts mit den in dieser Liste angegebenen IDs zurück.

UserScriptInjection

Chrome 135 und höher browser.* seit Chrome 148

Attribute

• injectImmediately

  Boolesch optional

  Gibt an, ob die Injektion im Ziel so schnell wie möglich ausgelöst werden soll. Das ist jedoch keine Garantie dafür, dass die Einfügung vor dem Seitenaufbau erfolgt, da die Seite möglicherweise bereits geladen wurde, wenn das Skript das Ziel erreicht.

• js

  ScriptSource[]

  Die Liste der ScriptSource-Objekte, die Quellen von Skripts definieren, die in das Ziel eingefügt werden sollen.

• Ziel

  InjectionTarget

  Details, die das Ziel angeben, in das das Script eingefügt werden soll.

• Welt

  ExecutionWorld optional

  Die JavaScript-„Welt“, in der das Script ausgeführt werden soll. Der Standardwert ist USER_SCRIPT.

• worldId

  String optional

  Gibt die ID der Welt des Nutzerscripts an, in der es ausgeführt werden soll. Wenn nichts angegeben ist, wird das Script in der Standard-Nutzerscript-Welt ausgeführt. Nur gültig, wenn world weggelassen wird oder USER_SCRIPT ist. Werte mit führenden Unterstrichen (_) sind reserviert.

WorldProperties

Attribute

• csp

  String optional

  Gibt den CSP für die Welt an. Der Standardwert ist der `ISOLATED`-Welt-CSP.

• Messaging

  Boolesch optional

  Gibt an, ob Messaging-APIs verfügbar sind. Der Standardwert ist false.

• worldId

  String optional

  Chrome 133 und höher browser.* seit Chrome 148

  Gibt die ID der spezifischen Nutzerskriptwelt an, die aktualisiert werden soll. Wenn nicht angegeben, werden die Eigenschaften der Standard-Nutzerscriptwelt aktualisiert. Werte mit führenden Unterstrichen (_) sind reserviert.

Methoden

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Konfiguriert die `USER_SCRIPT`-Ausführungsumgebung.

Parameter

• Properties

  WorldProperties

  Enthält die Konfiguration der Welt des Nutzerscripts.

Ausgabe

• Promise<void>

  Promise, das aufgelöst wird, sobald die Welt konfiguriert wurde.

execute()

Chrome 135 und höher browser.* seit Chrome 148

browser.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

Fügt ein Script in einen Zielkontext ein. Standardmäßig wird das Script bei document_idle ausgeführt oder sofort, wenn die Seite bereits geladen wurde. Wenn das Attribut injectImmediately festgelegt ist, wird das Script ohne Wartezeit eingefügt, auch wenn die Seite noch nicht vollständig geladen ist. Wenn das Skript zu einem Promise ausgewertet wird, wartet der Browser, bis das Promise erfüllt ist, und gibt den resultierenden Wert zurück.

Parameter

• Injektion

  UserScriptInjection

Ausgabe

• Promise<InjectionResult[]>

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

Gibt alle dynamisch registrierten Nutzerscripts für diese Erweiterung zurück.

Parameter

• Filter

  UserScriptFilter optional

  Wenn angegeben, gibt diese Methode nur die Nutzerscripts zurück, die mit dem Filter übereinstimmen.

Ausgabe

• Promise<RegisteredUserScript[]>

  Promise, das mit den registrierten Scripts aufgelöst wird. Das Promise wird abgelehnt, wenn ein Fehler auftritt.

getWorldConfigurations()

Chrome 133 und höher browser.* seit Chrome 148

browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Ruft alle registrierten Weltkonfigurationen ab.

Ausgabe

• Promise<WorldProperties[]>

  Promise, das mit den registrierten Weltkonfigurationen aufgelöst wird.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Registriert ein oder mehrere Nutzerscripts für diese Erweiterung.

Parameter

• Skripts

  RegisteredUserScript[]

  Enthält eine Liste der zu registrierenden Nutzerscripts.

Ausgabe

• Promise<void>

  Promise, das aufgelöst wird, sobald die Scripts vollständig registriert wurden. Das Promise wird abgelehnt, wenn ein Fehler auftritt.

resetWorldConfiguration()

Chrome 133 und höher browser.* seit Chrome 148

browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

Setzt die Konfiguration für eine Nutzerscript-Welt zurück. Alle Skripts, die in die Welt mit der angegebenen ID eingefügt werden, verwenden die Standardkonfiguration der Welt.

Parameter

• worldId

  String optional

  Die ID der Nutzerskript-Welt, die zurückgesetzt werden soll. Wenn keine Angabe gemacht wird, wird die Konfiguration der Standardwelt zurückgesetzt.

Ausgabe

• Promise<void>

  Promise, das aufgelöst wird, wenn die Konfiguration zurückgesetzt wird.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

Meldet alle dynamisch registrierten Nutzerscripts für diese Erweiterung ab.

Parameter

• Filter

  UserScriptFilter optional

  Wenn angegeben, werden mit dieser Methode nur die Nutzerscripts abgemeldet, die mit ihr übereinstimmen.

Ausgabe

• Promise<void>

  Promise, das aufgelöst wird, sobald die Registrierung der Scripts vollständig aufgehoben wurde. Das Promise wird abgelehnt, wenn ein Fehler auftritt.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

Aktualisiert ein oder mehrere Nutzerscripts für diese Erweiterung.

Parameter

• Skripts

  RegisteredUserScript[]

  Enthält eine Liste der zu aktualisierenden Nutzerskripts. Eine Property wird für das vorhandene Script nur aktualisiert, wenn sie in diesem Objekt angegeben ist. Wenn beim Parsen des Scripts oder bei der Dateivalidierung Fehler auftreten oder die angegebenen IDs nicht zu einem vollständig registrierten Script gehören, werden keine Scripts aktualisiert.

Ausgabe

• Promise<void>

  Promise, das aufgelöst wird, sobald die Scripts vollständig aktualisiert wurden. Das Promise wird abgelehnt, wenn ein Fehler auftritt.