chrome.devtools.inspectedWindow

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.

Eine allgemeine Einführung in die Verwendung von APIs für Entwicklertools finden Sie unter Zusammenfassung der Entwicklertools-APIs.

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

Manifest

Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API verwenden zu können.

"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 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öher

      Wertet 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 Feld code auf E_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

      Ressource[]

      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 Eigenschaft navigator.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

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)

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Ressource

      Ressource

    • Inhalte herausgestellt werden

      String