scripting.executeScript()
Fügt ein Skript in einen Zielkontext ein. Das Skript wird standardmäßig bei document_idle
ausgeführt.
Hinweis: Diese Methode ist in Manifest V3 oder höher in Chrome und Firefox 101 verfügbar. In Safari und Firefox 102+ ist diese Methode auch in Manifest V2 verfügbar.
Um diese API zu verwenden, müssen Sie die "scripting"
Berechtigung sowie eine Berechtigung für die URL des Ziels haben, entweder explizit als Host-Berechtigung oder mit der activeTab-Berechtigung. Beachten Sie, dass einige spezielle Seiten diese Berechtigung nicht zulassen, einschließlich Leseansicht, Quelltextansicht und PDF-Viewer-Seiten.
In Firefox und Safari kann ein teilweiser Mangel an Host-Berechtigungen zu einer erfolgreichen Ausführung führen (mit den Teilergebnissen im gelösten Promise). In Chrome verhindert jede fehlende Berechtigung, dass eine Ausführung stattfindet (siehe Issue 1325114).
Die Skripte, die Sie einfügen, werden Inhalts-Skripte genannt.
Dies ist eine asynchrone Funktion, die ein Promise
zurückgibt.
Syntax
let results = await browser.scripting.executeScript(
details // object
)
Parameter
details
-
Ein Objekt, das das einzufügende Skript beschreibt. Es enthält folgende Eigenschaften:
args
Optional-
Ein Array von Argumenten, die in die Funktion übergeben werden. Dies ist nur gültig, wenn der
func
-Parameter angegeben ist. Die Argumente müssen JSON-serialisierbar sein. files
Optional-
array
vonstring
. Ein Array von Pfaden der einzufügenden JS-Dateien relativ zum Stammverzeichnis der Erweiterung. Genau eine vonfiles
undfunc
muss angegeben werden. func
Optional-
function
. Eine JavaScript-Funktion, die eingefügt werden soll. Diese Funktion wird serialisiert und dann zum Einfügen deserialisiert. Das bedeutet, dass gebundene Parameter und der Ausführungskontext verloren gehen. Genau eine vonfiles
undfunc
muss angegeben werden. injectImmediately
Optional-
boolean
. Ob die Einfügung ins Ziel so schnell wie möglich ausgelöst wird, aber nicht unbedingt vor dem Laden der Seite. target
-
scripting.InjectionTarget
. Details, die das Ziel spezifizieren, in das das Skript eingefügt werden soll. world
Optional-
scripting.ExecutionWorld
. Die Ausführungsumgebung für ein Skript, in der es ausgeführt werden soll.
Rückgabewert
Ein Promise
, das mit einem Array von InjectionResult
-Objekten erfüllt wird, die das Ergebnis des eingefügten Skripts in jedem eingefügten Frame darstellen.
Das Promise wird abgelehnt, wenn die Einfügung fehlschlägt, z. B. wenn das Einfügungsziel ungültig ist. Wenn die Skriptausführung begonnen hat, ist ihr Ergebnis im Ergebnis enthalten, ob erfolgreich (als result
) oder erfolglos (als error
).
Jedes InjectionResult
-Objekt hat folgende Eigenschaften:
frameId
-
number
. Die Frame-ID, die mit der Einfügung verknüpft ist. result
Optional-
any
. Das Ergebnis der Skriptausführung. error
Optional-
any
. Wenn ein Fehler auftritt, enthält es den Wert, den das Skript geworfen oder mit dem es abgelehnt wurde. Typischerweise ist dies ein Fehlerobjekt mit einer Nachrichteneigenschaft, aber es könnte jeder Wert sein (einschließlich primitiver Werte und undefined).Chrome unterstützt die
error
-Eigenschaft noch nicht (siehe Issue 1271527: Propagate errors from scripting.executeScript to InjectionResult). Als Alternative können Laufzeitfehler abgefangen werden, indem der auszuführende Code in einer try-catch-Anweisung gewrappt wird. Nicht abgefangene Fehler werden auch in der Konsole des Ziel-Tabs gemeldet.
Das Ergebnis des Skripts ist die zuletzt ausgewertete Anweisung, was den Ergebnissen ähnelt, die Sie erhalten würden, wenn Sie das Skript in der Web-Konsole ausführen (nicht die Ausgabe von console.log()
). Zum Beispiel, betrachten Sie ein Skript wie dieses:
let foo = "my result";
foo;
Hier enthält das Ergebnisse-Array die Zeichenkette "my result"
als Element.
Das Skriptergebnis muss in Firefox ein strukturiert kopierbarer Wert oder in Chrome ein JSON-serialisierbarer Wert sein. Der Artikel Chrome-Inkompatibilitäten behandelt diesen Unterschied ausführlicher im Abschnitt Datenklon-Algorithmus.
Beispiele
Dieses Beispiel führt einen einzeiligen Code-Snippet im aktiven Tab aus:
browser.action.onClicked.addListener(async (tab) => {
try {
await browser.scripting.executeScript({
target: {
tabId: tab.id,
},
func: () => {
document.body.style.border = "5px solid green";
},
});
} catch (err) {
console.error(`failed to execute script: ${err}`);
}
});
Dieses Beispiel führt ein Skript aus einer Datei aus (die mit der Erweiterung verpackt ist) namens "content-script.js"
. Das Skript wird im aktiven Tab ausgeführt. Das Skript wird in Unterrahmen und dem Hauptdokument ausgeführt:
browser.action.onClicked.addListener(async (tab) => {
try {
await browser.scripting.executeScript({
target: {
tabId: tab.id,
allFrames: true,
},
files: ["content-script.js"],
});
} catch (err) {
console.error(`failed to execute script: ${err}`);
}
});
Browser-Kompatibilität
Hinweis:
Diese API basiert auf der chrome.scripting
API von Chromium.