Beschreibung
Mit der chrome.devtools.inspectedWindow API können Sie mit dem geprüften Fenster interagieren: Rufen Sie die Tab-ID für die geprüfte Seite ab, werten Sie den Code im Kontext des geprüften Fensters aus, laden Sie die Seite neu oder rufen Sie die Liste der Ressourcen auf der Seite ab.
Eine allgemeine Einführung in die Verwendung von Developer Tools APIs finden Sie unter Zusammenfassung der DevTools APIs.
Die tabId-Property enthält die Tab-ID, die Sie mit den chrome.tabs.*
API-Aufrufen verwenden können. Aus Sicherheitsgründen ist die chrome.tabs.* API jedoch nicht für die Erweiterungsseiten der Entwicklertools verfügbar. Sie müssen die Tab-ID an die Hintergrundseite übergeben und die chrome.tabs.* API-Funktionen von dort aus aufrufen.
Mit der Methode reload kann die geprüfte Seite neu geladen werden. Außerdem kann der Aufrufer eine Überschreibung für den User-Agent-String, ein Skript, das beim Seitenaufbau frühzeitig eingefügt wird, oder eine Option zum Erzwingen des Neuladens von im Cache gespeicherten Ressourcen angeben.
Mit dem Aufruf getResources und dem Ereignis onResourceContent können Sie die Liste der Ressourcen (Dokumente, Stylesheets, Skripts, Bilder usw.) auf der geprüften Seite abrufen. Die getContent und
setContent Methoden der Resource Klasse sowie das onResourceContentCommitted Ereignis können
verwendet werden, um die Änderung des Ressourceninhalts zu unterstützen, z. B. durch einen externen Editor.
Manifest
Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API zu verwenden.
"devtools_page"Code im geprüften Fenster ausführen
Mit der Methode eval können Erweiterungen JavaScript-Code im Kontext der geprüften Seite ausführen. Diese Methode ist leistungsstark, wenn sie im richtigen Kontext verwendet wird, und gefährlich, wenn sie unangemessen verwendet wird. Verwenden Sie die tabs.executeScript Methode, es sei denn, Sie benötigen die spezifische Funktionalität
die die eval Methode bietet.
Hier sind die Hauptunterschiede zwischen den Methoden eval und tabs.executeScript:
- Die Methode
evalverwendet keine isolierte Welt für den auszuwertenden Code. Daher ist der JavaScript-Status des geprüften Fensters für den Code zugänglich. Verwenden Sie diese Methode, wenn Zugriff auf den JavaScript-Status der geprüften Seite erforderlich ist. - Der Ausführungskontext des auszuwertenden Codes umfasst die Developer Tools Console API.
Der Code kann beispielsweise
inspectund$0verwenden. - Der ausgewertete Code kann einen Wert zurückgeben, der an den Erweiterungs-Callback übergeben wird. Der zurückgegebene Wert muss ein gültiges JSON-Objekt sein. Er darf nur primitive JavaScript-Typen und azyklische Verweise auf andere JSON-Objekte enthalten. Gehen Sie beim Verarbeiten der von der geprüften Seite empfangenen Daten besonders vorsichtig vor. Der Ausführungskontext wird im Wesentlichen von der geprüften Seite gesteuert. Eine schädliche Seite kann die Daten beeinflussen, die an die Erweiterung zurückgegeben werden.
Beachten Sie, dass eine Seite mehrere verschiedene JavaScript-Ausführungskontexte enthalten kann. Jeder Frame hat einen eigenen Kontext sowie einen zusätzlichen Kontext für jede Erweiterung, in der Inhaltsskripte in diesem Frame ausgeführt werden.
Standardmäßig wird die Methode eval im Kontext des Hauptframes der geprüften Seite ausgeführt.
Die Methode eval verwendet ein optionales zweites Argument, mit dem Sie den Kontext angeben können, in dem der Code ausgewertet wird. Dieses options-Objekt kann einen oder mehrere der folgenden Schlüssel enthalten:
frameURL- Hiermit können Sie einen anderen Frame als den Hauptframe der geprüften Seite angeben.
contextSecurityOrigin- Hiermit können Sie einen Kontext innerhalb des angegebenen Frames entsprechend seinem Web-Ursprung auswählen.
useContentScriptContext- Wenn „true“, wird das Skript im selben Kontext wie die Inhaltsskripte der Erweiterung ausgeführt. Das entspricht der Angabe des eigenen Web-Ursprungs der Erweiterung als Sicherheitsursprung des Kontexts. Damit können Daten mit dem Inhaltsskript ausgetauscht werden.
Beispiele
Der folgende Code prüft die Version von jQuery, die von der geprüften Seite verwendet wird:
chrome.devtools.inspectedWindow.eval(
"jQuery.fn.jquery",
function(result, isException) {
if (isException) {
console.log("the page is not using jQuery");
} else {
console.log("The page is using jQuery v" + result);
}
}
);
Wenn Sie diese API testen möchten, installieren Sie die API-Beispiele für Entwicklertools aus dem Repository chrome-extension-samples.
Typen
Resource
Eine Ressource auf der geprüften Seite, z. B. ein Dokument, ein Skript oder ein Bild.
Properties
-
URL
String
Die URL der Ressource.
-
getContent
void
Ruft den Inhalt der Ressource ab.
Die Funktion
getContentsieht so aus:(callback: function) => {...}
-
callback
Funktion
Der Parameter
callbacksieht so aus:(content: string, encoding: string) => void
-
Inhalt
String
Inhalt der Ressource (möglicherweise codiert).
-
encoding
String
Leer, wenn der Inhalt nicht codiert ist, andernfalls der Name der Codierung. Derzeit wird nur base64 unterstützt.
-
-
-
setContent
void
Legt den Inhalt der Ressource fest.
Die Funktion
setContentsieht so aus:(content: string, commit: boolean, callback?: function) => {...}
-
Inhalt
String
Neuer Inhalt der Ressource. Derzeit werden nur Ressourcen mit dem Texttyp unterstützt.
-
commit
boolean
„True“, wenn der Nutzer die Bearbeitung der Ressource abgeschlossen hat und der neue Inhalt der Ressource beibehalten werden soll. „False“, wenn es sich um eine kleinere Änderung handelt, die während der Bearbeitung der Ressource durch den Nutzer gesendet wurde.
-
callback
Funktion optional
Der Parameter
callbacksieht so aus:(error?: object) => void
-
Fehler
Objekt optional
Auf „undefined“ gesetzt, wenn der Ressourceninhalt erfolgreich festgelegt wurde. Andernfalls wird der Fehler beschrieben.
-
-
Properties
tabId
Die ID des Tabs, der geprüft wird. Diese ID kann mit der chrome.tabs.* API verwendet werden.
Typ
Zahl
Methoden
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
): void
Wertet einen JavaScript-Ausdruck im Kontext des Hauptframes der geprüften Seite aus. Der Ausdruck muss ein JSON-kompatibles Objekt ergeben, andernfalls wird eine Ausnahme ausgelöst. Die Funktion „eval“ kann entweder einen DevTools-seitigen Fehler oder eine JavaScript-Ausnahme melden, die während der Auswertung auftritt. In beiden Fällen ist der Parameter result des Callbacks undefined. Bei einem DevTools-seitigen Fehler ist der isException Parameter nicht null und für isError ist „true“ und für code ein Fehlercode festgelegt. Bei einem JavaScript-Fehler ist isException auf „true“ und value auf den Stringwert des ausgelösten Objekts gesetzt.
Parameter
-
Ausdruck
String
Ein Ausdruck, der ausgewertet werden soll.
-
Optionen
Objekt optional
Der Parameter „options“ kann eine oder mehrere Optionen enthalten.
-
frameURL
String optional
Wenn angegeben, wird der Ausdruck im Iframe ausgewertet, dessen URL mit der angegebenen URL übereinstimmt. Standardmäßig wird der Ausdruck im obersten Frame der geprüften Seite ausgewertet.
-
scriptExecutionContext
String optional
Chrome 107+Werten Sie den Ausdruck im Kontext eines Inhaltsskripts einer Erweiterung aus, die mit dem angegebenen Ursprung übereinstimmt. Wenn angegeben, überschreibt „scriptExecutionContext“ die Einstellung „true“ für „useContentScriptContext“.
-
useContentScriptContext
boolean optional
Werten Sie den Ausdruck im Kontext des Inhaltsskripts der aufrufenden Erweiterung aus, sofern das Inhaltsskript bereits in die geprüfte Seite eingefügt wurde. Andernfalls wird der Ausdruck nicht ausgewertet und der Callback wird aufgerufen, wobei der Parameter „exception“ auf ein Objekt gesetzt ist, für das das
isErrorFeld auf „true“ und dascodeFeld aufE_NOTFOUNDgesetzt ist.
-
-
callback
Funktion optional
Der Parameter
callbacksieht so aus:(result: object, exceptionInfo: object) => void
-
Ergebnis
Objekt
Das Ergebnis der Auswertung.
-
exceptionInfo
Objekt
Ein Objekt mit Details, wenn bei der Auswertung des Ausdrucks eine Ausnahme aufgetreten ist.
-
Code
String
Wird festgelegt, wenn der Fehler auf der Entwicklertools-Seite aufgetreten ist, bevor der Ausdruck ausgewertet wurde.
-
Beschreibung
String
Wird festgelegt, wenn der Fehler auf der Entwicklertools-Seite aufgetreten ist, bevor der Ausdruck ausgewertet wurde.
-
Details
any[]
Wird festgelegt, wenn der Fehler auf der Entwicklertools-Seite aufgetreten ist, bevor der Ausdruck ausgewertet wurde. Enthält das Array der Werte, die in den Beschreibungsstring eingefügt werden können, um weitere Informationen zur Ursache des Fehlers zu liefern.
-
isError
boolean
Wird festgelegt, wenn der Fehler auf der Entwicklertools-Seite aufgetreten ist, bevor der Ausdruck ausgewertet wurde.
-
isException
boolean
Wird festgelegt, wenn der ausgewertete Code eine nicht behandelte Ausnahme erzeugt.
-
Wert
String
Wird festgelegt, wenn der ausgewertete Code eine nicht behandelte Ausnahme erzeugt.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
): void
Ruft die Liste der Ressourcen von der geprüften Seite ab.
Parameter
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
): void
Lädt die geprüfte Seite neu.
Parameter
-
reloadOptions
Objekt optional
-
ignoreCache
boolean optional
Wenn „true“, umgeht das Ladeprogramm den Cache für alle Ressourcen der geprüften Seite, die geladen wurden, bevor das Ereignis
loadausgelöst wurde. Die Wirkung ist ähnlich wie beim Drücken von Strg+Umschalttaste+R im geprüften Fenster oder im Fenster der Entwicklertools. -
injectedScript
String optional
Wenn angegeben, wird das Skript sofort nach dem Laden in jeden Frame der geprüften Seite eingefügt, bevor die Skripts des Frames ausgeführt werden. Das Skript wird nach nachfolgenden Neuladevorgängen nicht eingefügt, z. B. wenn der Nutzer Strg+R drückt.
-
userAgent
String optional
Wenn angegeben, überschreibt der String den Wert des HTTP-Headers
User-Agent, der beim Laden der Ressourcen der geprüften Seite gesendet wird. Der String überschreibt auch den Wert der Propertynavigator.userAgent, die an alle Skripts zurückgegeben wird, die auf der geprüften Seite ausgeführt werden.
-
Ereignisse
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Wird ausgelöst, wenn der geprüften Seite eine neue Ressource hinzugefügt wird.
Parameter
-
callback
Funktion
Der Parameter
callbacksieht so aus:(resource: Resource) => void
-
Ressource
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Wird ausgelöst, wenn eine neue Überarbeitung der Ressource übernommen wird (z.B. wenn ein Nutzer eine bearbeitete Version der Ressource in den Entwicklertools speichert).