Beschreibung
Verwenden Sie die userScripts
API, um Nutzerskripts im Kontext von Nutzerskripts auszuführen.
Berechtigungen
userScripts
Wenn Sie die chrome.userScripts
API verwenden möchten, fügen Sie der Datei „manifest.json“ die Berechtigung "userScripts"
und für Websites, auf denen Sie Skripts ausführen möchten, die Berechtigung „"host_permissions"
“ hinzu.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Verfügbarkeit
Konzepte und Nutzung
Ein Nutzerskript ist Code, der in eine Webseite eingeschleust wird, um ihr Aussehen oder Verhalten zu ändern. Skripts werden entweder von Nutzern erstellt oder aus einem Skript-Repository oder einer Nutzerskripterweiterung heruntergeladen.
Entwicklermodus für Nutzer der Erweiterung
Als Entwickler von Erweiterungen haben Sie in Ihrer Chrome-Installation bereits den Entwicklermodus aktiviert. Bei Nutzerskripterweiterungen müssen Ihre Nutzer außerdem den Entwicklermodus aktivieren. Nachfolgend finden Sie eine Anleitung, die Sie kopieren und in Ihre eigene Dokumentation einfügen können.
- Rufen Sie die Seite „Erweiterungen“ auf, indem Sie in einem neuen Tab
chrome://extensions
eingeben.chrome://
-URLs sind standardmäßig nicht verlinkbar. Aktivieren Sie den Entwicklermodus, indem Sie auf die Ein/Aus-Schaltfläche neben Entwicklermodus klicken.
Sie können feststellen, ob der Entwicklermodus aktiviert ist, indem Sie prüfen, ob chrome.userScripts
einen Fehler ausgibt. Beispiel:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
In isolierten Welten arbeiten
Sowohl Nutzer- als auch Inhaltsskripte können in einer isolierten Welt oder auf 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 Nutzerskript seine JavaScript-Umgebung ändern, ohne dass sich dies auf die Hostseite oder die Nutzer- und Inhaltsscripts anderer Erweiterungen auswirkt. Umgekehrt sind Nutzer- und Inhaltsskripte für die Hostseite oder die Nutzer- und Inhaltsskripte anderer Erweiterungen nicht sichtbar. Auf der Hauptwelt ausgeführte Skripts sind für Hostseiten und andere Erweiterungen zugänglich und für Hostseiten und andere Erweiterungen sichtbar. Um die Welt auszuwählen, geben Sie beim Anrufen von userScripts.register()
"USER_SCRIPT"
oder "MAIN"
weiter.
Rufen Sie userScripts.configureWorld()
auf, um eine Sicherheitsrichtlinie für Inhalte für die Welt von USER_SCRIPT
zu konfigurieren:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
Werbebotschaften
Wie bei Inhaltsskripts und nicht sichtbaren Dokumenten kommunizieren Nutzerskripts mit anderen Teilen einer Erweiterung über Nachrichten. Das heißt, sie können runtime.sendMessage()
und runtime.connect()
wie jeder andere Teil einer Erweiterung aufrufen. Sie werden jedoch mithilfe spezieller Event-Handler empfangen (sie verwenden also weder onMessage
noch onConnect
). Diese Handler heißen runtime.onUserScriptMessage
und runtime.onUserScriptConnect
. Dedizierte Handler erleichtern die Erkennung von Nachrichten von Nutzerskripts, da diese ein weniger vertrauenswürdiger Kontext sind.
Bevor Sie eine Nachricht senden, müssen Sie configureWorld()
aufrufen und das Argument messaging
auf true
setzen. Die Argumente csp
und messaging
können gleichzeitig übergeben werden.
chrome.userScripts.configureWorld({
messaging: true
});
Updates zu Erweiterungen
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 Erweiterungsdienst-Worker ausführen. Sie antworten nur auf den Grund ("update"
), der an den Callback für den Termin übergeben wurde.
Beispiel
Dieses Beispiel stammt aus dem userScript-Beispiel in unserem Beispiel-Repository.
Skript registrieren
Das folgende Beispiel zeigt einen einfachen Aufruf von register()
. Das erste Argument ist ein Array von Objekten, mit denen die zu registrierenden Skripts definiert werden. Es gibt mehr Optionen als hier dargestellt.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Typen
ExecutionWorld
Die JavaScript-Welt, in der ein Nutzerskript ausgeführt werden kann.
Enum
"MAIN"
Gibt die Ausführungsumgebung des DOM an, also die Ausführungsumgebung, die gemeinsam mit dem JavaScript der Hostseite verwendet wird.
"USER_Script"
Gibt die Ausführungsumgebung an, die für Nutzerskripts spezifisch und von der CSP der Seite ausgenommen ist.
RegisteredUserScript
Attribute
-
allFrames
Boolescher Wert optional
Wenn „true“ festgelegt ist, wird der Frame in alle Frames eingeschleust, auch wenn der Frame nicht der oberste Frame auf dem Tab ist. Jeder Frame wird unabhängig auf URL-Anforderungen geprüft. Er wird nicht in untergeordnete Frames eingefügt, wenn die URL-Anforderungen nicht erfüllt sind. Die Standardeinstellung ist „false“, d. h., nur der oberste Frame wird abgeglichen.
-
excludeGlobs
string[] optional
Gibt Platzhaltermuster für Seiten an, auf denen dieses Nutzerskript NICHT eingeschleust wird.
-
excludeMatches
string[] optional
Schließt Seiten aus, auf denen dieses Nutzerskript andernfalls eingeschleust werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.
-
id
String
Die ID des im API-Aufruf angegebenen Nutzerskripts. Diese Property darf nicht mit einem „_“ beginnen, da sie als Präfix für generierte Script-IDs reserviert ist.
-
includeGlobs
string[] optional
Gibt Platzhaltermuster für Seiten an, auf denen dieses Nutzerskript eingeschleust wird.
-
js
Die Liste der ScriptSource-Objekte, die die Quellen von Skripts definieren, die in übereinstimmende Seiten eingefügt werden sollen.
-
Übereinstimmungen
string[] optional
Gibt an, auf welche Seiten dieses Nutzerskript eingeschleust 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 eingeschleust werden. Der bevorzugte und Standardwert ist
document_idle
. -
welt
ExecutionWorld optional
Die JavaScript-Ausführungsumgebung, in der das Skript ausgeführt werden soll. Der Standardwert ist
`USER_SCRIPT`
.
ScriptSource
Attribute
-
Code
String optional
String mit dem zu injizierenden JavaScript-Code. Es muss genau entweder
file
odercode
angegeben werden. -
Datei
String optional
Der Pfad der JavaScript-Datei, die relativ zum Stammverzeichnis der Erweiterung eingefügt werden soll. Es muss genau entweder
file
odercode
angegeben werden.
UserScriptFilter
Attribute
-
ids
string[] optional
getScripts
gibt nur Skripts mit den in dieser Liste angegebenen IDs zurück.
WorldProperties
Attribute
-
CSP
String optional
Gibt den weltweiten CSP an. Die Standardeinstellung ist das World CSP (
`ISOLATED`
). -
Nachrichtenfunktion; Messaging (context-sensitive!)
Boolescher Wert optional
Gibt an, ob Messaging-APIs verfügbar gemacht werden. Der Standardwert ist
false
.
Methoden
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Konfiguriert die Ausführungsumgebung `USER_SCRIPT`
.
Parameter
-
Properties
Enthält die Weltkonfiguration des Nutzerskripts.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Gibt alle dynamisch registrierten Nutzerskripts für diese Erweiterung zurück
Parameter
-
Filter
UserScriptFilter optional
Wenn angegeben, gibt diese Methode nur die Nutzerskripts zurück, die mit ihr übereinstimmen.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(scripts: RegisteredUserScript[]) => void
-
Skripts
-
Rückgaben
-
Promise<RegisteredUserScript[]>
Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Registriert ein oder mehrere Nutzerskripts für diese Erweiterung.
Parameter
-
Skripts
Enthält eine Liste mit Nutzerskripts, die registriert werden sollen.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Hebt die Registrierung aller dynamisch registrierten Nutzerskripts für diese Erweiterung auf
Parameter
-
Filter
UserScriptFilter optional
Wenn angegeben, hebt diese Methode nur die Registrierung der entsprechenden Nutzerskripts auf.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Aktualisiert ein oder mehrere Nutzerskripts für diese Erweiterung.
Parameter
-
Skripts
Enthält eine Liste der Nutzerskripts, die aktualisiert werden sollen. Eine Eigenschaft wird nur für das vorhandene Skript aktualisiert, wenn sie in diesem Objekt angegeben ist. Falls beim Parsen/der Dateiüberprüfung des Skripts Fehler auftreten oder die angegebenen IDs keinem vollständig registrierten Skript entsprechen, werden keine Skripts aktualisiert.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.