browser.devtools.inspectedWindow

Beschrijving

Gebruik de chrome.devtools.inspectedWindow API om te communiceren met het geïnspecteerde venster: verkrijg de tabblad-ID voor de geïnspecteerde pagina, evalueer de code in de context van het geïnspecteerde venster, laad de pagina opnieuw of verkrijg de lijst met bronnen op de pagina.

Ga naar Overzicht van DevTools API's voor een algemene inleiding over het gebruik van API's voor ontwikkelaarstools.

De property tabId biedt de tabblad-ID die je kunt gebruiken met de API-aanroepen browser.tabs.*. De browser.tabs.* API wordt vanwege beveiligingsoverwegingen niet weergegeven op de pagina's van de extensie Developer Tools. Je moet de tabblad-ID doorgeven aan de achtergrondpagina en de browser.tabs.* API-functies vanaf daar aanroepen.

De methode reload kan worden gebruikt om de geïnspecteerde pagina opnieuw te laden. Daarnaast kan de beller een overschrijving opgeven voor de user-agent-tekenreeks, een script dat vroeg wordt geïnjecteerd wanneer de pagina wordt geladen of een optie om het opnieuw laden van gecachte bronnen af te dwingen.

Gebruik de aanroep getResources en de gebeurtenis onResourceContent om de lijst met bronnen (documenten, stylesheets, scripts, afbeeldingen, enzovoort) op de geïnspecteerde pagina op te halen. De methoden getContent en setContent van de klasse Resource en de gebeurtenis onResourceContentCommitted kunnen worden gebruikt om wijziging van de broncontent te ondersteunen, bijvoorbeeld door een externe editor.

Manifest

De volgende sleutels moeten in het manifest worden gedefinieerd om deze API te gebruiken.

"devtools_page"

Code uitvoeren in het geïnspecteerde venster

De methode eval biedt extensies de mogelijkheid om JavaScript-code uit te voeren in de context van de geïnspecteerde pagina. Deze methode is krachtig als je deze in de juiste context gebruikt en gevaarlijk als je deze onjuist gebruikt. Gebruik de methode tabs.executeScript, tenzij u de specifieke functionaliteit nodig heeft die de methode eval biedt.

Dit zijn de belangrijkste verschillen tussen de methoden eval en tabs.executeScript:

  • De methode eval gebruikt geen geïsoleerde wereld voor de code die wordt geëvalueerd, dus de JavaScript-status van het geïnspecteerde venster is toegankelijk voor de code. Gebruik deze methode als toegang tot de JavaScript-status van de geïnspecteerde pagina is vereist.
  • De uitvoeringscontext van de code die wordt geëvalueerd, omvat de API voor de console voor tools voor ontwikkelaars. De code kan bijvoorbeeld inspect en $0 gebruiken.
  • De geëvalueerde code kan een waarde retourneren die wordt doorgegeven aan de callback van de extensie. De geretourneerde waarde moet een geldig JSON-object zijn (het mag alleen primitieve JavaScript-typen en acyclische verwijzingen naar andere JSON-objecten bevatten). Wees extra voorzichtig bij de verwerking van de gegevens die je ontvangt van de geïnspecteerde pagina. De uitvoeringscontext wordt in wezen beheerd door de geïnspecteerde pagina. Een schadelijke pagina kan van invloed zijn op de gegevens die worden teruggestuurd naar de extensie.

Een pagina kan meerdere verschillende JavaScript-uitvoeringscontexten bevatten. Elk frame heeft een eigen context, plus een extra context voor elke extensie met contentscripts die in dat frame worden uitgevoerd.

De methode eval wordt standaard uitgevoerd in de context van het hoofdframe van de geïnspecteerde pagina.

De methode eval heeft een optioneel tweede argument dat je kunt gebruiken om de context aan te geven waarin de code wordt geëvalueerd. Dit options-object kan een of meer van de volgende sleutels bevatten:

frameURL
Gebruik dit om een ander frame op te geven dan het hoofdframe van de geïnspecteerde pagina.
contextSecurityOrigin
Gebruik dit om een context binnen het opgegeven frame te selecteren op basis van de web-oorsprong.
useContentScriptContext
Als dit waar is, wordt het script uitgevoerd in dezelfde context als de contentscripts van de extensie. (Dit is gelijk aan de eigen web-oorsprong van de extensie invoeren als de beveiligingsoorsprong van de context.) Dit kan worden gebruikt om gegevens uit te wisselen met het contentscript.

Voorbeelden

De volgende code controleert de versie van jQuery die wordt gebruikt door de geïnspecteerde pagina:

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

Als je deze API wilt proberen, installeer je de API-voorbeelden voor devtools uit de repository chrome-extension-samples.

Typen

Resource

Een bron op de geïnspecteerde pagina, zoals een document, een script of een afbeelding.

Eigenschappen

  • url

    tekenreeks

    De URL van de bron.

  • getContent

    ongeldig

    Haalt de content van de bron op.

    De functie getContent ziet er zo uit: 

    () => {...}

    • returns

      Promise<object>

      Chrome 151+ browser.* sinds Chrome 152

      Een functie die resourcecontent krijgt als het verzoek is afgerond.

  • setContent

    ongeldig

    Stelt de content van de bron in.

    De functie setContent ziet er zo uit: 

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

    • content

      tekenreeks

      Nieuwe content van de bron. Alleen bronnen met het teksttype worden op dit moment ondersteund.

    • toewijzen

      booleaans

      Waar als de gebruiker klaar is met het bewerken van de bron en de nieuwe content van de bron moet worden bewaard. Onwaar als dit een kleine wijziging is die is gestuurd terwijl de gebruiker de bron bewerkt.

    • returns

      Promise<object>

      Chrome 151+ browser.* sinds Chrome 152

      Een functie die wordt aangeroepen als het verzoek is afgerond.

Eigenschappen

tabId

De ID van het tabblad dat wordt geïnspecteerd. Deze ID kan worden gebruikt met chrome.tabs.* API.

Type

getal

Methoden

eval()

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

Evalueert een JavaScript-expressie in de context van het hoofdframe van de geïnspecteerde pagina. De expressie moet resulteren in een json-compatibel object, anders wordt er een uitzondering gegenereerd. De eval-functie kan een fout aan de DevTools-zijde of een JavaScript-uitzondering melden die optreedt tijdens de evaluatie. In beide gevallen is de parameter result van de callback undefined. In het geval van een fout aan de DevTools-kant is de parameter isException niet-null en is isError ingesteld op true en code ingesteld op een foutcode. In het geval van een JavaScript-fout wordt isException ingesteld op true en value op de tekenreekswaarde van het gegenereerde object.

Parameters

  • expressie

    tekenreeks

    Een expressie die u wilt evalueren.

  • opties

    object optioneel

    De parameter options kan een of meer opties bevatten.

    • frameURL

      tekenreeks optioneel

      Als je dit opgeeft, wordt de expressie geëvalueerd in het iframe waarvan de URL overeenkomt met de opgegeven URL. De expressie wordt standaard geëvalueerd in het bovenste frame van de geïnspecteerde pagina.

    • scriptExecutionContext

      tekenreeks optioneel

      Chrome 107+ -browser.* sinds Chrome 152

      Evalueer de expressie in de context van een contentscript van een extensie die overeenkomt met de opgegeven oorsprong. Als deze parameter wordt opgegeven, overschrijft scriptExecutionContext de instelling 'true' voor useContentScriptContext.

    • useContentScriptContext

      booleaans optioneel

      Evalueer de expressie in de context van het contentscript van de aanroepende extensie, op voorwaarde dat het contentscript al is geïnjecteerd in de geïnspecteerde pagina. Als dat niet het geval is, wordt de expressie niet geëvalueerd en wordt de callback aangeroepen met de uitzonderingsparameter ingesteld op een object waarvan het veld isError is ingesteld op true en het veld code is ingesteld op E_NOTFOUND.

Retourzendingen

  • Promise<object>

    Chrome 151+ browser.* sinds Chrome 152

    Een functie die wordt aangeroepen als de evaluatie is afgerond.

getResources()

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

Haalt de lijst met bronnen op van de geïnspecteerde pagina.

Retourzendingen

  • Promise<Resource[]>

    Chrome 151+ browser.* sinds Chrome 152

    Een functie die de lijst met bronnen ontvangt wanneer het verzoek is afgerond.

reload()

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

Laadt de geïnspecteerde pagina opnieuw.

Parameters

  • reloadOptions

    object optioneel

    • ignoreCache

      booleaans optioneel

      Als deze waarde True is, slaat het laadprogramma het cachegeheugen over voor alle geïnspecteerde paginabronnen die worden geladen voordat de gebeurtenis load wordt geactiveerd. Het effect is vergelijkbaar met het indrukken van Ctrl+Shift+R in het geïnspecteerde venster of in het venster Hulpprogramma's voor ontwikkelaars.

    • injectedScript

      tekenreeks optioneel

      Als dit is opgegeven, wordt het script onmiddellijk na het laden in elk frame van de geïnspecteerde pagina geïnjecteerd, vóór de scripts van het frame. Het script wordt niet geïnjecteerd na volgende herlaadbeurten, bijvoorbeeld als de gebruiker op Ctrl+R drukt.

    • userAgent

      tekenreeks optioneel

      Als je een tekenreeks invoert, overschrijft deze de waarde van de HTTP-header User-Agent die wordt gestuurd terwijl de bronnen van de geïnspecteerde pagina worden geladen. De tekenreeks overschrijft ook de waarde van de property navigator.userAgent die wordt geretourneerd naar scripts die worden uitgevoerd op de geïnspecteerde pagina.

Evenementen

onResourceAdded

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

Wordt geactiveerd als er een nieuwe bron wordt toegevoegd aan de geïnspecteerde pagina.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (resource: Resource) => void

onResourceContentCommitted

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

Wordt geactiveerd als een nieuwe revisie van de bron wordt vastgelegd (bijvoorbeeld als de gebruiker een bewerkte versie van de bron opslaat in de Tools voor ontwikkelaars).

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

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