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 Berechtigung "scripting"
sowie die Berechtigung für die URL des Ziels haben, entweder als Host-Berechtigung oder mit der activeTab-Berechtigung. Beachten Sie, dass einige spezielle Seiten diese Berechtigung nicht zulassen, einschließlich Leseransicht, Quelltextanzeige und PDF-Viewer-Seiten.
In Firefox und Safari kann bei teilweiser fehlender Host-Berechtigung eine erfolgreiche Ausführung (mit den Teilergebnissen im aufgelösten Promise) erfolgen. In Chrome verhindert jede fehlende Berechtigung jegliche Ausführung (siehe Issue 1325114).
Die Skripte, die Sie injizieren, werden Inhaltsskripte 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 zu injizierende Skript beschreibt. Es enthält folgende Eigenschaften:
args
Optional-
Ein Array von Argumenten, das in die Funktion überführt werden soll. Dies ist nur gültig, wenn der Parameter
func
angegeben ist. Die Argumente müssen JSON-serialisierbar sein. files
Optional-
array
vonstring
. Ein Array von Pfaden zu den einzufügenden JS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau eines vonfiles
undfunc
angegeben werden. func
Optional-
function
. Eine JavaScript-Funktion, die eingefügt werden soll. Diese Funktion wird serialisiert und dann zur Injektion deserialisiert. Dies bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Es muss genau eines vonfiles
undfunc
angegeben werden. injectImmediately
Optional-
boolean
. Gibt an, ob die Injektion in das Ziel so schnell wie möglich ausgelöst wird, aber nicht unbedingt vor dem Seitenladen. target
-
scripting.InjectionTarget
. Details, die das Ziel spezifizieren, in das das Skript injiziert werden soll. world
Optional-
scripting.ExecutionWorld
. Die Ausführungsumgebung, in der ein Skript ausgeführt wird.
Rückgabewert
Ein Promise
, das mit einem Array von InjectionResult
-Objekten erfüllt wird, welche das Ergebnis des injizierten Skripts in jedem injizierten Frame darstellen.
Das Promise wird abgelehnt, wenn die Injektion fehlschlägt, z. B. wenn das Injektionsziel ungültig ist. Wenn die Skriptausführung begonnen hat, wird ihr Ergebnis im Ergebnis eingeschlossen, unabhängig davon, ob sie erfolgreich war (als result
) oder nicht erfolgreich (als error
).
Jedes InjectionResult
-Objekt hat folgende Eigenschaften:
frameId
-
number
. Die Frame-ID, die mit der Injektion verbunden 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. In der Regel handelt es sich um ein Fehlerobjekt mit einer Nachrichten-Eigenschaft, aber es könnte jeder Wert sein (einschließlich einfacher Datentypen undundefined
).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 eine try-catch-Anweisung gewickelt 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 sehen würden, wenn Sie das Skript in der Web-Konsole ausführen (nicht jede console.log()
Ausgabe). Betrachten Sie zum Beispiel ein Skript wie dieses:
let foo = "my result";
foo;
Hier enthält das Ergebnisse-Array die Zeichenkette "my result
" als Element.
Das Ergebnis des Skripts muss ein strukturiert klonbarer Wert in Firefox oder ein JSON-serialisierbarer Wert in Chrome sein. Der Artikel über Chrome-Inkompatibilitäten diskutiert diesen Unterschied ausführlicher im Abschnitt Daten-Klonierungsalgorithmus.
Beispiele
Dieses Beispiel führt ein einzeiliges 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 (im Erweiterungspaket enthalten) namens "content-script.js"
aus. Das Skript wird im aktiven Tab ausgeführt. Das Skript wird in Unterfenstern und im 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
BCD tables only load in the browser
Hinweis: Diese API basiert auf der chrome.scripting
API von Chromium.