chrome.devtools.inspectedWindow

Beschreibung

Mit der chrome.devtools.inspectedWindow API können Sie mit dem untersuchten Fenster interagieren: Sie können die Tab-ID für die untersuchte Seite abrufen, den Code im Kontext des untersuchten 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 unter DevTools APIs summary.

Das Attribut tabId enthält die Tab-ID, die Sie für chrome.tabs.*-API-Aufrufe verwenden können. Die chrome.tabs.* API ist jedoch aus Sicherheitsgründen nicht auf den 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 früh beim Seitenaufbau eingefügt 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 untersuchten 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, damit diese API verwendet werden kann.

"devtools_page"

Code im untersuchten Fenster ausführen

Mit der Methode eval können Erweiterungen JavaScript-Code im Kontext der untersuchten Seite ausführen. Diese Methode ist leistungsstark, wenn sie im richtigen Kontext verwendet wird, und gefährlich, wenn sie unangemessen eingesetzt 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:

  • Bei der Methode eval wird keine isolierte Umgebung für den auszuwertenden Code verwendet. Der JavaScript-Status des untersuchten Fensters ist also für den Code zugänglich. Verwenden Sie diese Methode, wenn Sie Zugriff auf den JavaScript-Status der untersuchten Seite benötigen.
  • Der Ausführungskontext des auszuwertenden Codes umfasst die Developer Tools Console API. Im Code können beispielsweise inspect und $0 verwendet werden.
  • 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. Seien Sie bei der Verarbeitung der von der untersuchten Seite empfangenen Daten besonders vorsichtig. Der Ausführungskontext wird im Wesentlichen von der untersuchten Seite gesteuert. Eine schädliche Seite kann die an die Erweiterung zurückgegebenen Daten beeinträchtigen.

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 Inhalts-Scripts in diesem Frame ausgeführt werden.

Standardmäßig wird die Methode eval im Kontext des Hauptframes der untersuchten 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
Wird verwendet, um einen anderen Frame als den Hauptframe der untersuchten Seite anzugeben.
contextSecurityOrigin
Wird verwendet, um einen Kontext innerhalb des angegebenen Frames anhand seines Webursprungs auszuwählen.
useContentScriptContext
Bei „true“ wird das Skript im selben Kontext wie die Inhaltsskripts der Erweiterung ausgeführt. (Entspricht der Angabe des eigenen Webursprungs der Erweiterung als Sicherheitsursprung des Kontexts.) Damit können Daten mit dem Content-Script ausgetauscht werden.

Beispiele

Mit dem folgenden Code wird geprüft, welche Version von jQuery auf 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 ausprobieren möchten, installieren Sie die devtools API-Beispiele aus dem Repository chrome-extension-samples.

Typen

Resource

Eine Ressource auf der untersuchten 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 getContent-Funktion sieht so aus: 

    () => {...}

    • Gibt zurück

      Promise<object>

      Ausstehend

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

  • setContent

    void

    Legt den Inhalt der Ressource fest.

    Die setContent-Funktion sieht so aus: 

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

    • Inhalt

      String

      Neue Inhalte 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 gespeichert werden soll. „False“, wenn es sich um eine geringfügige Änderung handelt, die während der Bearbeitung der Ressource durch den Nutzer gesendet wird.

    • Gibt zurück

      Promise<object>

      Ausstehend

      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.* verwendet werden. oder die Compute Engine API.

Typ

Zahl

Methoden

eval()

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

Wertet einen JavaScript-Ausdruck im Kontext des Hauptframes der untersuchten Seite aus. Der Ausdruck muss zu einem JSON-kompatiblen Objekt ausgewertet werden. Andernfalls wird eine Ausnahme ausgelöst. Die eval-Funktion kann entweder einen DevTools-seitigen Fehler oder eine JavaScript-Ausnahme melden, die während der Auswertung auftritt. In beiden Fällen ist der result-Parameter des Callbacks undefined. Bei einem Fehler auf der DevTools-Seite ist der Parameter isException nicht null und isError ist auf „true“ und code 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 auszuwertender Ausdruck.

  • Optionen

    object 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 untersuchten Seite ausgewertet.

    • scriptExecutionContext

      String optional

      Chrome 107 und höher

      Wertet den Ausdruck im Kontext eines Inhalts-Scripts einer Erweiterung aus, die dem angegebenen Ursprung entspricht. Falls angegeben, überschreibt „scriptExecutionContext“ die Einstellung „true“ für „useContentScriptContext“.

    • useContentScriptContext

      Boolesch optional

      Werten Sie den Ausdruck im Kontext des Inhaltsskripts der aufrufenden Erweiterung aus, sofern das Inhaltsskript bereits in die untersuchte Seite eingefügt wurde. Andernfalls wird der Ausdruck nicht ausgewertet und der Callback wird mit dem Ausnahme-Parameter aufgerufen, der auf ein Objekt gesetzt ist, bei dem das Feld isError auf „true“ und das Feld code auf E_NOTFOUND gesetzt ist.

Ausgabe

  • Promise<object>

    Ausstehend

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

getResources()

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

Ruft die Liste der Ressourcen von der untersuchten Seite ab.

Ausgabe

  • Promise<Resource[]>

    Ausstehend

    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 untersuchte Seite neu.

Parameter

  • reloadOptions

    object optional

    • ignoreCache

      Boolesch optional

      Wenn „true“, umgeht der Loader den Cache für alle untersuchten Seitenressourcen, die vor dem Auslösen des load-Ereignisses geladen werden. Das Ergebnis ist dasselbe, als würden Sie im untersuchten Fenster oder im Fenster der Entwicklertools Strg + Umschalt + R drücken.

    • injectedScript

      String optional

      Falls angegeben, wird das Skript unmittelbar nach dem Laden in jeden Frame der untersuchten Seite eingefügt, bevor eines der Skripts des Frames ausgeführt wird. Das Skript wird nach nachfolgenden Neuladevorgängen nicht eingefügt, z. B. wenn der Nutzer Strg + R drückt.

    • userAgent

      String optional

      Wenn angegeben, wird der Wert des HTTP-Headers User-Agent, der beim Laden der Ressourcen der untersuchten Seite gesendet wird, durch den String überschrieben. Der String überschreibt auch den Wert des Attributs navigator.userAgent, der an alle Skripts zurückgegeben wird, die auf der untersuchten Seite ausgeführt werden.

Ereignisse

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Wird ausgelöst, wenn der untersuchten 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 Revision 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