Beschreibung
Verwenden Sie die chrome.scripting
API, um Skripts in verschiedenen Kontexten auszuführen.
Berechtigungen
scripting
Verfügbarkeit
Manifest
Um die chrome.scripting
API zu verwenden, deklarieren Sie die Berechtigung "scripting"
im Manifest sowie die Hostberechtigungen für die Seiten, in die Skripts eingefügt werden sollen. Verwenden Sie den Schlüssel "host_permissions"
oder die Berechtigung "activeTab"
, die temporäre Hostberechtigungen gewährt. Im folgenden Beispiel wird die Berechtigung „activeTab“ verwendet.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Konzepte und Nutzung
Sie können die chrome.scripting
API verwenden, um JavaScript und CSS in Websites einzufügen. Dies ähnelt der Verwendung von Inhaltsskripts. Wenn Sie jedoch den chrome.scripting
-Namespace verwenden, können Erweiterungen Entscheidungen zur Laufzeit treffen.
Injektionsziele
Mit dem Parameter target
können Sie ein Ziel angeben, in das JavaScript oder CSS eingeschleust werden sollen.
Das einzige Pflichtfeld ist tabId
. Standardmäßig wird eine Injektion im Hauptframe des angegebenen Tabs ausgeführt.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Wenn Sie in allen Frames des angegebenen Tabs ausgeführt werden sollen, können Sie den booleschen Wert allFrames
auf true
festlegen.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Sie können die Informationen auch in bestimmte Frames eines Tabs einschleusen, indem Sie einzelne Frame-IDs angeben. Weitere Informationen zu Frame-IDs findest du unter chrome.webNavigation
API.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Eingeschleuster Code
Erweiterungen können den einzuführenden Code entweder über eine externe Datei oder eine Laufzeitvariable angeben.
Files
Dateien werden als Strings angegeben, die sich auf das Stammverzeichnis der Erweiterung beziehen. Mit dem folgenden Code wird die Datei script.js
in den Hauptframe des Tabs eingefügt.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Laufzeitfunktionen
Wenn Sie JavaScript mit scripting.executeScript()
einschleusen, können Sie angeben, dass anstelle einer Datei eine Funktion ausgeführt werden soll. Diese Funktion sollte eine Funktionsvariable sein, die für den aktuellen Erweiterungskontext verfügbar ist.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Sie können das Problem umgehen, indem Sie das Attribut args
verwenden:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Laufzeitstrings
Beim Einfügen von CSS in eine Seite kannst du auch einen String angeben, der in der css
-Eigenschaft verwendet werden soll. Diese Option ist nur für scripting.insertCSS()
verfügbar. Sie können keinen String mit scripting.executeScript()
ausführen.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Ergebnisse verarbeiten
Die Ergebnisse der Ausführung von JavaScript werden an die Erweiterung übergeben. Pro Frame wird ein einzelnes Ergebnis zurückgegeben. Der Hauptframe ist garantiert der erste Index im resultierenden Array. Alle anderen Frames befinden sich in einer nicht deterministischen Reihenfolge.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
gibt keine Ergebnisse zurück.
Promise-Objekte
Wenn der resultierende Wert der Skriptausführung ein Promise ist, wartet Chrome darauf, dass das Versprechen erfüllt ist, und gibt den resultierenden Wert zurück.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Beispiele
Registrierung aller Skripts für dynamische Inhalte aufheben
Das folgende Snippet enthält eine Funktion, die die Registrierung aller Skripts für dynamische Inhalte aufhebt, die von der Erweiterung zuvor registriert wurden.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Wenn Sie die chrome.scripting
API testen möchten, installieren Sie das Scripting-Beispiel aus dem Repository für Chrome-Erweiterungsbeispiele.
Typen
ContentScriptFilter
Attribute
-
ids
string[] optional
Wenn angegeben, gibt
getRegisteredContentScripts
nur Skripts mit einer ID zurück, die in dieser Liste angegeben ist.
CSSInjection
Attribute
-
css
String optional
Ein String mit dem zu injizierenden CSS-Code. Es muss genau eines der Attribute
files
odercss
angegeben werden. -
Dateien
string[] optional
Der Pfad der einzufügenden CSS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau eines der Attribute
files
odercss
angegeben werden. -
Ursprung
StyleOrigin optional
Der Stilursprung für die Injektion. Die Standardeinstellung ist
'AUTHOR'
. -
target
Details zum Festlegen des Ziels, in das die CSS eingefügt werden soll
ExecutionWorld
Die JavaScript-Welt, in der ein Skript ausgeführt werden kann.
Enum
"ISOLATED"
Gibt die isolierte Welt an, also die Ausführungsumgebung, die nur für diese Erweiterung verfügbar ist.
"MAIN"
Gibt die Hauptwelt des DOM an, also die Ausführungsumgebung, die gemeinsam mit dem JavaScript der Hostseite verwendet wird.
InjectionResult
Attribute
-
documentId
String
Chrome 106 oder höherDas mit der Injektion verknüpfte Dokument.
-
frameId
Zahl
Chrome 90 oder höherDer mit der Injektion verknüpfte Frame.
-
Ergebnis
Beliebig optional
Das Ergebnis der Skriptausführung.
InjectionTarget
Attribute
-
allFrames
Boolescher Wert optional
Gibt an, ob das Skript in alle Frames auf dem Tab eingeschleust werden soll. Die Standardeinstellung ist "false". Dieser Wert darf nicht „true“ sein, wenn
frameIds
angegeben ist. -
documentIds
string[] optional
Chrome 106 oder höherDie IDs bestimmter documentIds, in die eingeschleust werden soll. Dieser Parameter darf nicht festgelegt werden, wenn
frameIds
festgelegt ist. -
frameIds
nummer[] optional
Die IDs bestimmter Frames, in die eingefügt werden soll.
-
tabId
Zahl
Die ID des Tabs, in den eingeschleust werden soll.
RegisteredContentScript
Attribute
-
allFrames
Boolescher Wert optional
Wenn „true“ angegeben wird, 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.
-
css
string[] optional
Die Liste der CSS-Dateien, die in übereinstimmende Seiten eingeschleust werden sollen. Diese werden in der Reihenfolge eingeschleust, in der sie in diesem Array erscheinen, bevor ein DOM für die Seite erstellt oder angezeigt wird.
-
excludeMatches
string[] optional
Schließt Seiten aus, auf denen dieses Inhaltsskript andernfalls eingeschleust werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.
-
id
String
Die ID des Inhaltsskripts, das im API-Aufruf angegeben wurde. Darf nicht mit einem „_“ beginnen, da es als Präfix für generierte Script-IDs reserviert ist.
-
js
string[] optional
Die Liste der JavaScript-Dateien, die in übereinstimmende Seiten eingeschleust werden sollen. Diese werden in der Reihenfolge eingeschleust, in der sie in diesem Array erscheinen.
-
matchOriginAsFallback
Boolescher Wert optional
Chrome 119 und höherGibt an, ob das Skript in Frames eingeschleust werden kann, deren URL ein nicht unterstütztes Schema enthält, insbesondere: about:, data:, blob: oder filesystem:. In diesen Fällen wird der Ursprung der URL überprüft, um festzustellen, ob das Skript eingeschleust werden sollte. Wenn der Ursprung
null
ist (wie bei „Data: URLs“), ist der verwendete Ursprung entweder der Frame, der den aktuellen Frame erstellt hat, oder der Frame, der die Navigation zu diesem Frame initiiert hat. Beachten Sie, dass dies möglicherweise nicht der übergeordnete Frame ist. -
Übereinstimmungen
string[] optional
Gibt an, auf welche Seiten dieses Inhaltsskript eingeschleust wird. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster. Muss für
registerContentScripts
angegeben werden. -
persistAcrossSessions
Boolescher Wert optional
Gibt an, ob dieses Inhaltsskript auch in zukünftigen Sitzungen erhalten bleiben soll. Die Standardeinstellung ist "true".
-
runAt
RunAt optional
Gibt an, wann JavaScript-Dateien in die Webseite eingeschleust werden. Der bevorzugte und Standardwert ist
document_idle
. -
welt
ExecutionWorld optional
Chrome 102 und höherDie JavaScript-„World“, in der das Script ausgeführt wird. Die Standardeinstellung ist
ISOLATED
.
ScriptInjection
Attribute
-
args
Beliebig[] optional
Chrome 92 und höherDie Argumente, die an die angegebene Funktion übergeben werden sollen. Dies ist nur gültig, wenn der Parameter
func
angegeben ist. Diese Argumente müssen JSON-serialisierbar sein. -
Dateien
string[] optional
Der Pfad der einzuführenden JS- oder CSS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau entweder
files
oderfunc
angegeben werden. -
injectImmediately
Boolescher Wert optional
Chrome 102 und höherGibt an, ob die Injektion im Ziel so schnell wie möglich ausgelöst werden soll. Dies ist keine Garantie dafür, dass die Seite vor dem Laden der Seite eingefügt wird, da die Seite möglicherweise bereits geladen wurde, als das Skript das Ziel erreicht hat.
-
target
Details zum Festlegen des Ziels, in das das Skript eingeschleust werden soll
-
welt
ExecutionWorld optional
Chrome 95 oder höherDie JavaScript-„World“, in der das Script ausgeführt wird. Die Standardeinstellung ist
ISOLATED
. -
func
void optional
Chrome 92 und höherEine zu injizierende JavaScript-Funktion. Diese Funktion wird seriell und dann für die Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Es muss genau entweder
files
oderfunc
angegeben werden.Die Funktion
func
sieht so aus:() => {...}
StyleOrigin
Der Ursprung einer Stiländerung. Weitere Informationen finden Sie unter Stilursprünge.
Enum
"AUTHOR"
Methoden
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Ein Skript wird in einen Zielkontext eingefügt. Standardmäßig wird das Skript um document_idle
oder sofort ausgeführt, wenn die Seite bereits geladen wurde. Wenn das Attribut injectImmediately
festgelegt ist, wird das Skript ohne Warten eingefügt, auch wenn die Seite noch nicht vollständig geladen ist. Wenn das Skript ein Promise auswertet, wartet der Browser, bis das Versprechen erfüllt ist, und gibt den resultierenden Wert zurück.
Parameters
-
Injektion
Details des Skripts, das eingefügt werden soll.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(results: InjectionResult[]) => void
-
Ergebnisse
-
Rückgaben
-
Promise<InjectionResult[]>
Chrome 90 oder höherPromise-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.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Gibt alle dynamisch registrierten Inhaltsskripte für diese Erweiterung zurück, die dem angegebenen Filter entsprechen.
Parameters
-
Filter
ContentScriptFilter optional
Ein Objekt zum Filtern der dynamisch registrierten Skripts der Erweiterung.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(scripts: RegisteredContentScript[]) => void
-
Skripts
-
Rückgaben
-
Promise<RegisteredContentScript[]>
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.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Fügt ein CSS-Stylesheet in einen Zielkontext ein. Wenn mehrere Frames angegeben sind, werden fehlgeschlagene Injektionen ignoriert.
Parameters
-
Injektion
Die Details der einzufügenden Stile.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Chrome 90 oder höherPromise-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.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Registriert ein oder mehrere Inhaltsskripte für diese Erweiterung.
Parameters
-
Skripts
Enthält eine Liste der zu registrierenden Skripts. Wenn beim Parsen oder der Dateivalidierung Fehler auftreten oder die angegebenen IDs bereits vorhanden sind, werden keine Skripts registriert.
-
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.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Entfernt ein CSS-Stylesheet, das zuvor von dieser Erweiterung aus einem Zielkontext eingefügt wurde.
Parameters
-
Injektion
Die Details der zu entfernenden Stile. Die Eigenschaften
css
,files
undorigin
müssen genau mit dem durchinsertCSS
eingefügten Stylesheet übereinstimmen. Der Versuch, ein nicht vorhandenes Stylesheet zu entfernen, ist vertretbar. -
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.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Hebt die Registrierung von Inhaltsskripts für diese Erweiterung auf.
Parameters
-
Filter
ContentScriptFilter optional
Wenn angegeben, wird nur die Registrierung von Skripts mit dynamischen Inhalten aufgehoben, die dem Filter entsprechen. Andernfalls sind alle Skripts für dynamische Inhalte der Erweiterung nicht registriert.
-
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.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Aktualisiert ein oder mehrere Inhaltsskripte für diese Erweiterung.
Parameters
-
Skripts
Enthält eine Liste der zu aktualisierenden Skripts. 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.