Beschreibung
Verwenden Sie die chrome.devtools.inspectedWindow
API, um mit dem geprüften Fenster zu interagieren: Rufen Sie die Tab-ID der geprüften 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.
Manifest
Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API verwenden zu können.
"devtools_page"
Verwenden Sie chrome.devtools.inspectedWindow
, um mit dem geprüften Fenster zu interagieren: Rufen Sie die Tab-ID der geprüften Seite ab, werten Sie den Code im Kontext des geprüften Fensters aus, aktualisieren Sie die Seite oder rufen Sie die Liste der Ressourcen auf der Seite ab.
Eine allgemeine Einführung in die Verwendung von APIs für Entwicklertools finden Sie unter Zusammenfassung der Entwicklertools-APIs.
Überblick
Das Attribut tabId
stellt die Tab-ID bereit, die Sie für die chrome.tabs.*
-API-Aufrufe verwenden können. Beachten Sie jedoch, dass die chrome.tabs.*
API aus Sicherheitsgründen nicht auf den Erweiterungsseiten der Entwicklertools verfügbar ist. Sie müssen die Tab-ID an die Hintergrundseite übergeben und von dort die chrome.tabs.*
API-Funktionen aufrufen.
Sie können die Methode reload
verwenden, um die geprüfte Seite neu zu laden. Außerdem kann der Aufrufer eine Überschreibung für den User-Agent-String, ein Skript, das beim Seitenaufbau eingeschleust wird, oder eine Option zum Erzwingen des Neuladens von im Cache gespeicherten Ressourcen angeben.
Verwenden Sie den getResources
-Aufruf und das onResourceContent
-Ereignis, um die Liste der Ressourcen (Dokumente, Stylesheets, Skripts, Bilder usw.) auf der geprüften Seite abzurufen. Die Methoden getContent
und setContent
der Klasse Resource
zusammen mit dem Ereignis onResourceContentCommitted
können verwendet werden, um die Änderung des Ressourceninhalts zu unterstützen (z. B. durch einen externen Bearbeiter).
Code im Fenster „Überprüft“ 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 eingesetzt wird, und bei unsachgemäßer Verwendung gefährlich. Verwenden Sie die Methode tabs.executeScript
, sofern Sie nicht die spezifischen Funktionen der Methode eval
benötigen.
Dies sind die Hauptunterschiede zwischen den Methoden eval
und tabs.executeScript
:
- Bei der Methode
eval
wird für den zu bewertenden Code keine isolierte Welt verwendet. Daher kann der Code auf den JavaScript-Status des geprüften Fensters zugreifen. Verwenden Sie diese Methode, wenn Zugriff auf den JavaScript-Status der geprüften Seite erforderlich ist. - Der Ausführungskontext des evaluierten Codes umfasst die Developer Tools Console API.
Der Code kann beispielsweise
inspect
und$0
enthalten. - Der ausgewertete Code gibt möglicherweise einen Wert zurück, der an den Callback der Erweiterung ü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. Seien Sie besonders vorsichtig bei der Verarbeitung der Daten, die von der geprüften Seite empfangen werden. Der Ausführungskontext wird im Wesentlichen von der geprüften Seite gesteuert. Eine schädliche Seite kann sich darauf auswirken, welche Daten an die Erweiterung zurückgegeben werden.
Beachten Sie, dass eine Seite mehrere verschiedene JavaScript-Ausführungskontexte enthalten kann. Jeder Frame hat seinen eigenen Kontext sowie einen zusätzlichen Kontext für jede Erweiterung, in der Inhaltsskripte 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. Das Objekt options kann einen oder mehrere der folgenden Schlüssel enthalten:
frameURL
- Mit dieser Option können Sie einen anderen Frame als den Hauptframe der geprüften Seite angeben.
contextSecurityOrigin
- Mit dieser Option wird ein Kontext innerhalb des angegebenen Frames gemäß seinem Webursprung ausgewählt.
useContentScriptContext
- Bei „true“ wird das Skript im selben Kontext wie die Inhaltsskripte der Erweiterung ausgeführt. Entspricht der Angabe der eigenen Weborgin der Erweiterung als Ursprung für die Kontextsicherheit. Dadurch können Daten mit dem Content-Script ausgetauscht werden.
Beispiele
Mit dem folgenden Code wird nach der jQuery-Version gesucht, die von der untersuchten 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 devtools API-Beispiele aus dem Repository chrome-extension-sample.
Typen
Resource
Eine Ressource auf der untersuchten Seite, z. B. ein Dokument, ein Skript oder ein Bild.
Attribute
-
url
String
Die URL der Ressource.
-
getContent
void
Ruft den Inhalt der Ressource ab.
Die Funktion
getContent
sieht so aus:(callback: function) => {...}
-
callback
Funktion
Der Parameter
callback
sieht so aus:(content: string, encoding: string) => void
-
Inhalte herausgestellt werden
String
Inhalt der Ressource (möglicherweise codiert).
-
encoding
String
Leer, wenn der Inhalt nicht codiert ist, andernfalls Codierungsname. Derzeit wird nur base64 unterstützt.
-
-
-
setContent
void
Legt den Inhalt der Ressource fest.
Die Funktion
setContent
sieht so aus:(content: string, commit: boolean, callback?: function) => {...}
-
Inhalte herausgestellt werden
String
Neuer Inhalt der Ressource. Derzeit werden nur Ressourcen mit dem Texttyp unterstützt.
-
Commit
boolean
„True“, wenn der Nutzer das Bearbeiten der Ressource abgeschlossen hat und der neue Inhalt der Ressource beibehalten werden soll; „false“, wenn es sich um eine kleine Änderung handelt, die beim Bearbeiten der Ressource gesendet wird.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(error?: object) => void
-
error
Objekt optional
Wird auf „undefiniert“ gesetzt, wenn der Ressourceninhalt erfolgreich festgelegt wurde; andernfalls wird der Fehler beschrieben.
-
-
Attribute
tabId
Die ID des zu prüfenden Tabs. Diese ID kann mit chrome.tabs verwendet werden.* API.
Typ
Zahl
Methoden
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
Wertet einen JavaScript-Ausdruck im Kontext des Hauptframes der untersuchten Seite aus. Der Ausdruck muss als JSON-konformes Objekt ausgewertet werden. Andernfalls wird eine Ausnahme ausgelöst. Die Bewertungsfunktion kann entweder einen Fehler auf der Entwicklertools-Seite oder eine JavaScript-Ausnahme melden, die während der Bewertung auftritt. In beiden Fällen ist der Parameter result
des Callbacks undefined
. Bei einem Fehler auf Seite der Entwicklertools ist der Parameter isException
nicht null und isError
auf „true“ und code
auf einen Fehlercode gesetzt. Bei einem JavaScript-Fehler werden isException
auf „true“ und value
auf den Stringwert des ausgelösten Objekts gesetzt.
Parameters
-
expression
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 für den iFrame ausgewertet, dessen URL mit der angegebenen übereinstimmt. Standardmäßig wird der Ausdruck im obersten Frame der geprüften Seite ausgewertet.
-
scriptExecutionContext
String optional
Chrome 107 und höherWertet 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
Boolescher Wert optional
Werten Sie den Ausdruck im Kontext des Inhaltsskripts der Anruferweiterung aus, sofern das Inhaltsskript bereits in die geprüfte Seite eingefügt wurde. Andernfalls wird der Ausdruck nicht ausgewertet und der Callback wird ausgelöst, wobei der Ausnahmeparameter auf ein Objekt gesetzt ist, bei dem das Feld
isError
auf „true“ und das Feldcode
aufE_NOTFOUND
gesetzt sind.
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: object, exceptionInfo: object) => void
-
Ergebnis
Objekt
Das Ergebnis der Bewertung.
-
exceptionInfo
Objekt
Ein Objekt, das Details liefert, wenn beim Auswerten des Ausdrucks eine Ausnahme aufgetreten ist.
-
Code
String
Legt fest, ob der Fehler in den Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wird.
-
Beschreibung
String
Legt fest, ob der Fehler in den Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wird.
-
Details
beliebige[]
Dieser Wert wird festgelegt, wenn der Fehler auf der Seite der Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wurde. Enthält das Array der Werte, die im Beschreibungsstring ersetzt werden können, um weitere Informationen zur Fehlerursache zu liefern.
-
isError
boolean
Legt fest, ob der Fehler in den Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wird.
-
isException
boolean
Wird festgelegt, wenn der ausgewertete Code eine unbehandelte Ausnahme auslöst.
-
value
String
Wird festgelegt, wenn der ausgewertete Code eine unbehandelte Ausnahme auslöst.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Ruft die Liste der Ressourcen von der geprüften Seite ab.
Parameters
-
callback
Funktion
Der Parameter
callback
sieht so aus:(resources: Resource[]) => void
-
Ressourcen
Die Ressourcen auf der Seite.
-
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Lädt die geprüfte Seite neu.
Parameters
-
reloadOptions
Objekt optional
-
ignoreCache
Boolescher Wert optional
Ist dieser Wert auf „true“ gesetzt, umgeht das Ladeprogramm den Cache für alle geprüften Seitenressourcen, die geladen werden, bevor das
load
-Ereignis ausgelöst wird. Der Effekt ähnelt dem Drücken von Strg+Umschalt+R im zu überprüfenden Fenster oder im Fenster der Entwicklertools. -
injectedScript
String optional
Wenn angegeben, wird das Skript unmittelbar nach dem Laden und vor einem Skript des Frames in jeden Frame der geprüften Seite injiziert. 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 Eigenschaftnavigator.userAgent
, der an alle Skripts zurückgegeben wird, die auf der untersuchten Seite ausgeführt werden.
-
Veranstaltungen
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Wird ausgelöst, wenn der geprüften Seite eine neue Ressource hinzugefügt wird
Parameters
-
callback
Funktion
Der Parameter
callback
sieht so aus:(resource: Resource) => void
-
Ressource
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Wird ausgelöst, wenn für eine neue Version der Ressource ein Commit durchgeführt wird (z. B. wenn der Nutzer eine bearbeitete Version der Ressource in den Entwicklertools speichert)