browser.devtools.inspectedWindow

Beschreibung

Verwenden Sie die chrome.devtools.inspectedWindow API, um mit dem geprüften Fenster zu 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 Entwicklertool-APIs finden Sie in der Zusammenfassung der Entwicklertool-APIs.

Das Attribut tabId enthält die Tab-ID, die Sie mit den browser.tabs.*-API-Aufrufen verwenden können. Aus Sicherheitsgründen ist die browser.tabs.* API jedoch nicht für die Seiten der Entwicklertools-Erweiterung verfügbar. Sie müssen die Tab-ID an die Hintergrundseite übergeben und die browser.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 früh beim Seitenaufbau eingefügt wird, oder eine Option zum Erzwingen des Neuladens von im Cache gespeicherten Ressourcen angeben.

Verwenden Sie den Aufruf getResources und das Ereignis onResourceContent, um die Liste der Ressourcen (Dokumente, Stylesheets, Skripts, Bilder usw.) auf der geprüften Seite abzurufen. Die Methoden getContent und setContent der Klasse Resource sowie das Ereignis onResourceContentCommitted 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 Methode tabs.executeScript, es sei denn, Sie benötigen die spezifische Funktionalität, die die Methode eval bietet.

Hier sind die Hauptunterschiede zwischen den Methoden eval und tabs.executeScript:

  • Die Methode eval verwendet keine isolierte Welt für den ausgewerteten Code, sodass der JavaScript-Status des geprüften Fensters für den Code zugänglich ist. Verwenden Sie diese Methode, wenn Zugriff auf den JavaScript-Status der geprüften Seite erforderlich ist.
  • Der Ausführungskontext des ausgewerteten Codes umfasst die Entwicklertools Console API. Der Code kann beispielsweise inspect und $0 verwenden.
  • Der ausgewertete Code kann einen Wert zurückgeben, 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, wenn Sie die von der geprüften Seite empfangenen Daten verarbeiten. Der Ausführungskontext wird im Wesentlichen von der geprüften Seite gesteuert. Eine schädliche Seite kann die an die Erweiterung zurückgegebenen Daten beeinflussen.

Eine Seite kann mehrere verschiedene JavaScript-Ausführungskontexte enthalten. Jeder Frame hat einen eigenen Kontext sowie einen zusätzlichen Kontext für jede Erweiterung, die Inhaltsskripts in diesem Frame ausführt.

Standardmäßig wird die Methode eval im Kontext des Hauptframes der geprüften Seite ausgeführt.

Die Methode eval akzeptiert 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
Damit können Sie einen anderen Frame als den Hauptframe der geprüften Seite angeben.
contextSecurityOrigin
Wird verwendet, um einen Kontext innerhalb des angegebenen Frames anhand seines Webursprungs auszuwählen.
useContentScriptContext
Wenn „true“, wird das Script im selben Kontext wie die Inhaltsscripts der Erweiterung ausgeführt. (Entspricht der Angabe des eigenen Webursprungs der Erweiterung als Sicherheitsursprung des Kontexts.) Damit können Daten mit dem Inhaltsskript ausgetauscht werden.

Beispiele

Mit dem folgenden Code wird die jQuery-Version der geprüften Seite ermittelt:

browser.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 ausprobieren möchten, installieren Sie die DevTools API-Beispiele aus dem Repository chrome-extension-samples.

Typen

Resource

Eine Ressource auf der geprüften Seite, z. B. ein Dokument, ein Script oder ein Bild.

Attribute

  • 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+ browser.* seit Chrome 152

      Eine Funktion, die Ressourceninhalte 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 vom Typ „Text“ 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 geringfügige Änderung handelt, die während der Bearbeitung der Ressource durch den Nutzer gesendet wurde.

    • Gibt zurück

      Promise<object>

      Chrome 151+ browser.* seit Chrome 152

      Eine Funktion, die nach Abschluss der Anfrage aufgerufen wird.

Attribute

tabId

Die ID des geprüften Tabs. Diese ID kann mit chrome.tabs.* verwendet werden. oder die Compute Engine API.

Typ

Zahl

Methoden

eval()

browser.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 ein JSON-konformes 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 Fehler auf der DevTools-Seite ist der Parameter isException nicht null, isError ist auf „true“ gesetzt und code ist auf einen Fehlercode gesetzt. Bei einem JavaScript-Fehler wird 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 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+ browser.* seit Chrome 152

      Wertet den Ausdruck im Kontext eines Inhaltsskripts einer Erweiterung aus, die dem angegebenen Ursprung entspricht. Wenn „scriptExecutionContext“ angegeben ist, wird die Einstellung „true“ für „useContentScriptContext“ überschrieben.

    • useContentScriptContext

      Boolesch optional

      Wertet 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 mit dem Ausnahmeparameter aufgerufen, der auf ein Objekt festgelegt ist, bei dem das Feld isError auf „true“ und das Feld code auf E_NOTFOUND festgelegt ist.

Ausgabe

  • Promise<object>

    Chrome 151+ browser.* seit Chrome 152

    Eine Funktion, die aufgerufen wird, wenn die Bewertung abgeschlossen ist.

getResources()

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

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

Ausgabe

  • Promise<Resource[]>

    Chrome 151+ browser.* seit Chrome 152

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

reload()

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

Lädt die geprüfte Seite neu.

Parameter

  • reloadOptions

    Objekt optional

    • ignoreCache

      Boolesch optional

      Wenn „true“, umgeht der Loader den Cache für alle geprüften Seitenressourcen, die vor dem Auslösen des load-Ereignisses geladen werden. Der Effekt ist ähnlich wie das Drücken von Strg + Umschalttaste + R im geprüften Fenster oder im Toolfenster „Entwicklertools“.

    • injectedScript

      String optional

      Wenn angegeben, wird das Script sofort nach dem Laden in jeden Frame der geprüften Seite eingefügt, bevor die Scripts des Frames ausgeführt werden. Das Skript wird nach nachfolgenden Aktualisierungen 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 des Attributs navigator.userAgent, der an alle Skripts zurückgegeben wird, die auf der geprüften Seite ausgeführt werden.

Ereignisse

onResourceAdded

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

browser.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine neue Version der Ressource übernommen wird (z.B. wenn der Nutzer eine bearbeitete Version der Ressource in den Entwicklertools speichert).

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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