chrome.devtools.inspectedWindow

Beschreibung

Verwenden Sie die chrome.devtools.inspectedWindow API, um mit dem untersuchten Fenster zu interagieren: Rufen Sie die Tab-ID der untersuchten Seite ab, bewerten Sie den Code im Kontext des untersuchten Fensters, aktualisieren Sie die Seite oder rufen Sie die Liste der Ressourcen auf der Seite ab.

Eine allgemeine Einführung zur Verwendung der Entwicklertools-APIs finden Sie in der Zusammenfassung der Entwicklertools.

Die Eigenschaft tabId enthält die Tab-ID, die Sie mit dem chrome.tabs.* verwenden können API-Aufrufe Beachten Sie jedoch, dass die chrome.tabs.* API nicht für die Entwicklertools verfügbar ist. Erweiterungsseiten aus Sicherheitsgründen – Sie müssen die Tab-ID an den Hintergrund und die API-Funktionen von chrome.tabs.* von dort aus aufrufen.

Die Methode reload kann verwendet werden, um die geprüfte Seite neu zu laden. Außerdem kann der Aufrufer angeben, eine Überschreibung für den User-Agent-String, ein Skript, das beim Seitenaufbau vorzeitig eingeschleust wird, oder ein Option, um das Aktualisieren von im Cache gespeicherten Ressourcen zu erzwingen.

Verwenden Sie den Aufruf getResources und das Ereignis onResourceContent, um die Liste der Ressourcen abzurufen (Dokumente, Stylesheets, Skripte, Bilder usw.) auf der untersuchten Seite. Die getContent und Die setContent-Methoden der Klasse Resource können zusammen mit dem onResourceContentCommitted-Ereignis werden verwendet, um Änderungen des Ressourceninhalts zu unterstützen, z. B. durch einen externen Mitbearbeiter.

Manifest

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

"devtools_page"

Code im untersuchten Fenster ausführen

Die Methode eval bietet Erweiterungen die Möglichkeit, JavaScript-Code im Kontext eines der untersuchten Seite. Diese Methode ist leistungsstark, wenn sie im richtigen Kontext verwendet wird, und gefährlich, wenn sie verwendet wird. die nicht unangemessen sind. Verwenden Sie die Methode tabs.executeScript, es sei denn, Sie benötigen die entsprechende Funktion die die eval-Methode bietet.

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

  • Die Methode eval verwendet für den auszuwertenden Code keine isolierte Welt, sodass das JavaScript des überprüften Fensters für den Code zugänglich ist. Verwenden Sie diese Methode beim Zugriff auf die Der JavaScript-Status der geprüften Seite ist erforderlich.
  • Der Ausführungskontext des zu bewertenden Codes umfasst die Developer Tools Console API. Der Code kann beispielsweise inspect und $0 enthalten.
  • Der ausgewertete Code kann einen Wert zurückgeben, der an den Erweiterungs-Callback übergeben wird. Den zurückgegebenen Wert muss ein gültiges JSON-Objekt sein (es darf nur primitive JavaScript-Typen und azyklische Verweise auf andere JSON-Objekte). Bitte sei besonders vorsichtig, wenn du die erhaltenen Daten verarbeitet hast. von der untersuchten Seite aus. Der Ausführungskontext wird im Wesentlichen von der untersuchten Seite gesteuert. eine kann sich auf die Daten auswirken, die an die Erweiterung zurückgegeben werden.

Eine Seite kann mehrere verschiedene Kontexte für die JavaScript-Ausführung enthalten. Jeder Frame hat eine eigene eigenen Kontext sowie einen zusätzlichen Kontext für jede Erweiterung, in der Inhaltsskripte ausgeführt werden. Frame.

Die Methode eval wird standardmäßig im Kontext des Hauptframes der untersuchten Seite ausgeführt.

Die Methode eval verwendet ein optionales zweites Argument, mit dem Sie den Kontext angeben können, in dem wird der Code ausgewertet. Dieses options-Objekt kann einen oder mehrere der folgenden Schlüssel enthalten:

frameURL
Hier können Sie einen anderen Frame als den Hauptframe der geprüften Seite angeben.
contextSecurityOrigin
Mit dieser Option können Sie einen Kontext innerhalb des angegebenen Frames nach seiner Webursprung auswählen.
useContentScriptContext
Bei „true“ wird das Script im selben Kontext wie die Inhaltsskripte der Erweiterungen ausgeführt. (Entspricht Dabei wird die eigene Webquelle der Erweiterung als Kontextsicherheitsquelle angegeben.) Dies kann verwendet werden, um Daten mit dem Content-Skript austauschen.

Beispiele

Mit dem folgenden Code wird nach der von der untersuchten Seite verwendeten jQuery-Version gesucht:

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);
    }
  }
);

Um diese API auszuprobieren, installieren Sie die devtools API-Beispiele aus chrome-extension-samples zu erstellen.

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

    voidm

    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

      • Inhalt

        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

    voidm

    Legt den Inhalt der Ressource fest.

    Die Funktion setContent sieht so aus: 

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

    • 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 kleine Ä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

        Objekt (optional)

        Wird auf „nicht definiert“ gesetzt, wenn der Ressourceninhalt festgelegt wurde. beschreibt Fehler ansonsten.

Attribute

tabId

Die ID des zu prüfenden Tabs. Diese ID kann mit chrome.tabs verwendet werden.* die API verwenden.

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 ein JSON-kompatibles Objekt ergeben. Andernfalls wird eine Ausnahme ausgelöst. Die eval-Funktion kann entweder einen Fehler in den Entwicklertools oder eine JavaScript-Ausnahme melden, die während der Bewertung auftritt. In beiden Fällen lautet der result-Parameter des Callbacks undefined. Bei einem Fehler in den Entwicklertools ist der isException-Parameter 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 Ausdruck, der ausgewertet werden soll.

  • Optionen

    Objekt (optional)

    Der Optionsparameter kann eine oder mehrere Optionen enthalten.

    • frameURL

      String optional

      Wenn angegeben, wird der Ausdruck in dem iFrame ausgewertet, dessen URL mit dem angegebenen übereinstimmt. Standardmäßig wird der Ausdruck im obersten Frame der untersuchten Seite ausgewertet.

    • scriptExecutionContext

      String optional

      Chrome 107 oder höher

      Wertet den Ausdruck im Kontext eines Inhaltsskripts einer Erweiterung aus, die dem angegebenen Ursprung entspricht. Falls angegeben, überschreibt „scriptExecutionContext“ „true“ für "useContentScriptContext" festgelegt.

    • useContentScriptContext

      Boolescher Wert optional

      Werten Sie den Ausdruck im Kontext des Inhaltsskripts der aufrufenden Erweiterung aus, vorausgesetzt, das Inhaltsskript wurde bereits in die untersuchte Seite eingefügt. Andernfalls wird der Ausdruck nicht ausgewertet und der Callback wird aufgerufen, indem der Ausnahmeparameter auf ein Objekt gesetzt wird, 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: 

    (result: object, exceptionInfo: object) => void

    • Ergebnis

      Objekt

      Das Ergebnis der Bewertung.

    • exceptionInfo

      Objekt

      Ein Objekt, das Details bereitstellt, wenn beim Bewerten 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

        Beliebig[]

        Legt fest, ob der Fehler auf der Entwicklertools-Seite vor der Auswertung des Ausdrucks aufgetreten ist. Enthält das Array der Werte, die in den Beschreibungsstring ersetzt werden können, um weitere Informationen zur Ursache des Fehlers bereitzustellen.

      • isError

        boolean

        Legt fest, ob der Fehler in den Entwicklertools aufgetreten ist, bevor der Ausdruck ausgewertet wird.

      • isException

        boolean

        Legt fest, wenn der ausgewertete Code eine unbehandelte Ausnahme erzeugt.

      • Wert

        String

        Legt fest, wenn der ausgewertete Code eine unbehandelte Ausnahme erzeugt.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

Ruft die Liste der Ressourcen von der untersuchten Seite ab.

Parameter

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

Parameter

  • 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 + Umschalttaste + R im untersuchten Fenster oder im Fenster der Entwicklertools.

    • injectedScript

      String optional

      Wenn angegeben, wird das Skript unmittelbar beim Laden in jeden Frame der untersuchten Seite vor den Skripts des Frames eingeschleust. 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 untersuchten Seite gesendet wird. Mit dem String wird auch der Wert der Eigenschaft navigator.userAgent überschrieben, 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 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 ein Commit für eine neue Version der Ressource durchgeführt 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