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.

Manifest

Die folgenden Schlüssel müssen im Manifest deklariert werden, damit diese API verwendet werden kann.

"devtools_page"

Mit chrome.devtools.inspectedWindow 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.

Übersicht

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.

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

    Promise

    Ruft den Inhalt der Ressource ab.

    Die getContent-Funktion sieht so aus: 

    (callback?: function) => {...}

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (response: object) => void

      • Antwort

        Objekt

        Ausstehend

        Ein Objekt, das den Ressourceninhalt und seine Codierung enthält.

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

    • Gibt zurück

      Promise<object>

      Ausstehend

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

      Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

  • setContent

    void

    Promise

    Legt den Inhalt der Ressource fest.

    Die setContent-Funktion sieht so aus: 

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

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

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (error?: object) => void

      • Fehler

        object optional

        Wird auf „undefined“ gesetzt, wenn der Ressourceninhalt erfolgreich festgelegt wurde. Andernfalls wird der Fehler beschrieben.

    • Gibt zurück

      Promise<object>

      Ausstehend

      Eine Funktion, die nach Abschluss der Anfrage aufgerufen wird.

      Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

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

Promise 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): 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.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (response: object) => void

    • Antwort

      Objekt

      Ausstehend

      Das Ergebnis der Bewertung und Informationen zu Ausnahmen.

      • exceptionInfo

        Objekt

        Ein Objekt, das Details enthält, wenn beim Auswerten des Ausdrucks eine Ausnahme aufgetreten ist.

        • Code

          String

          Gibt an, ob der Fehler auf der Seite der Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wurde.

        • Beschreibung

          String

          Gibt an, ob der Fehler auf der Seite der Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wurde.

        • Details

          any[]

          Gibt an, ob der Fehler auf der DevTools-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

          Gibt an, ob der Fehler auf der Seite der Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wurde.

        • isException

          boolean

          Wird festgelegt, wenn der ausgewertete Code eine unbehandelte Ausnahme erzeugt.

        • Wert

          String

          Wird festgelegt, wenn der ausgewertete Code eine unbehandelte Ausnahme erzeugt.

      • Ergebnis

        Objekt

        Das Ergebnis der Bewertung.

Ausgabe

  • Promise<object>

    Ausstehend

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

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

Ruft die Liste der Ressourcen von der untersuchten Seite ab.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (resources: Resource[]) => void

    • Ressourcen

      Resource[]

      Die Ressourcen auf der Seite.

Ausgabe

  • Promise<Resource[]>

    Ausstehend

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

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

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