devtools.inspectedWindow.eval()
Führt JavaScript in dem Fenster aus, mit dem die Entwicklertools verbunden sind.
Dies ähnelt der Verwendung von tabs.executeScript(), um ein Content Script einzubinden, unterscheidet sich jedoch in zwei wesentlichen Punkten:
Erstens kann das JavaScript spezielle Befehle verwenden, die Browser üblicherweise in der Konsole ihrer Entwicklertools bereitstellen: Beispielsweise können Sie mit „$0“ auf das im Inspector ausgewählte Element verweisen.
Zweitens kann das ausgeführte JavaScript alle Änderungen sehen, die von Skripten vorgenommen wurden, die die Seite geladen hat. Content Scripts sehen die Seite dagegen so, wie sie ohne geladene Seitenskripte aussehen würde. Beachten Sie jedoch, dass die Isolation von Content Scripts eine bewusste Sicherheitsmaßnahme ist. Sie soll verhindern, dass bösartige oder nicht kooperierende Webseiten WebExtensions-APIs durch das Neudefinieren von DOM-Funktionen und -Eigenschaften beeinflussen oder unterlaufen. Seien Sie daher besonders vorsichtig, wenn Sie diesen Schutz durch die Verwendung von eval() aufheben, und verwenden Sie Content Scripts, sofern Sie eval() nicht benötigen.
Das Skript wird standardmäßig im Hauptframe der Seite ausgewertet. Es muss einen Wert ergeben, der als JSON dargestellt werden kann. Beispielsweise darf das Ergebnis weder eine Funktion noch ein Objekt sein, das Funktionen enthält. Standardmäßig hat das Skript keinen Zugriff auf Content Scripts, die in die Seite eingebunden sind.
Sie können eval() nicht in privilegierten Browserfenstern wie „about:addons“ aufrufen.
In Firefox 153 und höher muss der Benutzer der Erweiterung Zugriff auf das Dateischema gewährt haben, damit eval() für eine file://-URL aufgerufen werden kann. Ohne diese Berechtigung wird das Promise mit einem Fehler zurückgewiesen. Mit extension.isAllowedFileSchemeAccess() können Sie prüfen, ob der Benutzer der Erweiterung diese Berechtigung erteilt hat.
Optional können Sie einen options-Parameter übergeben, um das Skript in einem anderen Frame oder im Kontext eingebundener Content Scripts auszuwerten. Beachten Sie, dass Firefox den options-Parameter noch nicht unterstützt.
Die Funktion eval() gibt ein Promise zurück, das mit dem Ergebnis der Skriptauswertung oder mit einem Fehler erfüllt wird.
Hilfsfunktionen
Das Skript erhält Zugriff auf mehrere Objekte, die dem eingebundenen Skript die Interaktion mit den Entwicklertools ermöglichen. Die folgenden Hilfsfunktionen werden derzeit unterstützt:
Syntax
let evaluating = browser.devtools.inspectedWindow.eval(
expression, // string
options // object
)
Parameter
expression-
string. Der auszuwertende JavaScript-Ausdruck. Der Ausdruck muss ein Objekt ergeben, das als JSON dargestellt werden kann, andernfalls wird eine Ausnahme ausgelöst. Beispielsweise darfexpressionkeine Funktion ergeben. optionsOptional-
object. Optionen für die Funktion:contextSecurityOriginOptional-
string. Wertet den Ausdruck im Kontext eines Content Scripts aus, das von einer anderen Erweiterung eingebunden wurde und dessen Herkunft mit dem hier angegebenen Wert übereinstimmt. Dies hat Vorrang voruseContentScriptContext. frameURLOptional-
string. Die URL des Frames, in dem der Ausdruck ausgewertet werden soll. Wenn Sie diesen Wert weglassen, wird der Ausdruck im Hauptframe des Fensters ausgewertet. scriptExecutionContextOptional-
string. Wertet den Ausdruck im Kontext eines Content Scripts einer Erweiterung aus, das mit der angegebenen Herkunft übereinstimmt. Wenn dieser Wert angegeben ist, hatscriptExecutionContextVorrang vor der EinstellungtruefüruseContentScriptContext. useContentScriptContextOptional-
boolean. Wenntrue, wird der Ausdruck im Kontext eines beliebigen Content Scripts ausgewertet, das diese Erweiterung in die Seite eingebunden hat. Wenn Sie diese Option setzen, muss die Erweiterung tatsächlich Content Scripts in die Seite eingebunden haben. Andernfalls wird ein Devtools-Fehler ausgelöst.
Rückgabewert
Ein Promise, das mit einem array aus zwei Elementen erfüllt wird.
Wenn kein Fehler aufgetreten ist, enthält Element 0 das Ergebnis der Auswertung des Ausdrucks und Element 1 den Wert undefined.
Wenn ein Fehler aufgetreten ist, enthält Element 0 den Wert undefined und Element 1 ein Objekt mit Einzelheiten zum Fehler. Dabei werden zwei Arten von Fehlern unterschieden:
-
Fehler bei der Auswertung des JavaScripts (beispielsweise Syntaxfehler im Ausdruck). In diesem Fall enthält Element 1:
- eine boolesche Eigenschaft
isExceptionmit dem Werttrue - eine String-Eigenschaft
valuemit weiteren Einzelheiten.
- eine boolesche Eigenschaft
-
andere Fehler (beispielsweise ein Ausdruck, der ein Objekt ergibt, das nicht als JSON dargestellt werden kann). In diesem Fall enthält Element 1:
- eine boolesche Eigenschaft
isErrormit dem Werttrue - eine String-Eigenschaft
codemit einem Fehlercode.
- eine boolesche Eigenschaft
Beispiele
Dieses Beispiel prüft, ob jQuery im untersuchten Fenster definiert ist, und protokolliert das Ergebnis. In einem Content Script würde dies nicht funktionieren, da das Content Script jQuery nicht sehen könnte, selbst wenn es definiert wäre.
function handleError(error) {
if (error.isError) {
console.log(`DevTools error: ${error.code}`);
} else {
console.log(`JavaScript error: ${error.value}`);
}
}
function handleResult(result) {
console.log(result);
if (result[0] !== undefined) {
console.log(`jQuery: ${result[0]}`);
} else if (result[1]) {
handleError(result[1]);
}
}
const checkJQuery = "typeof jQuery !== 'undefined'";
evalButton.addEventListener("click", () => {
browser.devtools.inspectedWindow.eval(checkJQuery).then(handleResult);
});
Beispiele für Hilfsfunktionen
Dieses Beispiel verwendet die Hilfsfunktion $0, um die Hintergrundfarbe des Elements festzulegen, das derzeit im Inspector ausgewählt ist:
const evalButton = document.querySelector("#reddinate");
const evalString = "$0.style.backgroundColor = 'red'";
function handleError(error) {
if (error.isError) {
console.log(`DevTools error: ${error.code}`);
} else {
console.log(`JavaScript error: ${error.value}`);
}
}
function handleResult(result) {
if (result[1]) {
handleError(result[1]);
}
}
evalButton.addEventListener("click", () => {
browser.devtools.inspectedWindow.eval(evalString).then(handleResult);
});
Dieses Beispiel verwendet die Hilfsfunktion inspect(), um das erste <h1>-Element auf der Seite auszuwählen:
const inspectButton = document.querySelector("#inspect");
const inspectString = "inspect(document.querySelector('h1'))";
function handleError(error) {
if (error.isError) {
console.log(`DevTools error: ${error.code}`);
} else {
console.log(`JavaScript error: ${error.value}`);
}
}
function handleResult(result) {
if (result[1]) {
handleError(result[1]);
}
}
inspectButton.addEventListener("click", () => {
browser.devtools.inspectedWindow.eval(inspectString).then(handleResult);
});
Browser-Kompatibilität
Hinweis:
Diese API basiert auf der chrome.devtools-API von Chromium.