chrome.devtools.inspectedWindow

Beschreibung

Mit der chrome.devtools.inspectedWindow API können Sie mit dem geprüften Fenster interagieren: Sie können die Tab-ID für die geprüfte Seite abrufen, den Code im Kontext des geprüften Fensters auswerten, die Seite neu laden oder die Liste der Ressourcen auf der Seite abrufen.

Eine allgemeine Einführung in die Verwendung von Developer Tools APIs finden Sie in der 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 von Developer Tools 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 eval verwendet 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 inspect und $0 verwenden.
  • 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 bei der Verarbeitung der von der geprüften Seite empfangenen Daten besonders sorgfältig 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.

Eine Seite kann mehrere verschiedene JavaScript-Ausführungskontexte enthalten. 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. (Entspricht der Angabe des eigenen Web-Ursprungs der Erweiterung als Sicherheitsursprung des Kontexts.) Dies kann verwendet werden, um Daten mit dem Inhaltsskript auszutauschen.

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 die 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 getContent sieht so aus: 

    () => {...}

    • Gibt zurück

      Promise<object>

      Chrome 151+

      Eine Funktion, die den Ressourceninhalt empfängt, wenn die Anfrage abgeschlossen ist.

  • setContent

    void

    Legt den Inhalt der Ressource fest.

    Die Funktion setContent sieht so aus: 

    (content: string, commit: boolean) => {...}

    • 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 wird.

    • Gibt zurück

      Promise<object>

      Chrome 151+

      Eine Funktion, die nach Abschluss der Anfrage aufgerufen wird.

Properties

tabId

Die ID des Tabs, der geprüft wird. Diese ID kann mit chrome.tabs.* API verwendet werden.

Typ

Zahl

Methoden

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

Wertet einen JavaScript-Ausdruck im Kontext des Hauptframes der geprüften Seite aus. Der Ausdruck muss zu einem JSON-konformen Objekt ausgewertet werden, 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 festgelegt.

Parameter

  • Ausdruck

    String

    Ein Ausdruck, der ausgewertet werden soll.

  • Optionen

    Optionales Objekt

    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 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

      Boolescher Wert 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 isError Feld auf „true“ und das code Feld auf E_NOTFOUND gesetzt ist.

Ausgabe

  • Promise<object>

    Chrome 151+

    Eine Funktion, die nach Abschluss der Auswertung aufgerufen wird.

getResources()

chrome.devtools.inspectedWindow.getResources(): Promise<Resource[]>

Ruft die Liste der Ressourcen von der geprüften Seite ab.

Ausgabe

  • Promise<Resource[]>

    Chrome 151+

    Eine Funktion, die die Liste der Ressourcen empfängt, wenn die Anfrage abgeschlossen ist.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

Lädt die geprüfte Seite neu.

Parameter

  • reloadOptions

    Optionales Objekt

    • ignoreCache

      Boolescher Wert optional

      Wenn „true“, umgeht das Ladeprogramm den Cache für alle Ressourcen der geprüften Seite, die geladen wurden, bevor das Ereignis load ausgelö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 Property navigator.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 callback sieht so aus: 

    (resource: Resource) => void

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).

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (resource: Resource, content: string) => void