chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.devtools.inspectedWindow per interagire con la finestra ispezionata: ottieni l'ID scheda della pagina ispezionata, valuta il codice nel contesto della finestra ispezionata, ricarica la pagina o ottieni l'elenco delle risorse all'interno della pagina.

Manifest

Per utilizzare questa API, le seguenti chiavi devono essere dichiarate nel file manifest.

"devtools_page"

Utilizza chrome.devtools.inspectedWindow per interagire con la finestra ispezionata: ottieni l'ID scheda per la pagina ispezionata, valuta il codice nel contesto della finestra ispezionata, ricarica la pagina o ottieni l'elenco delle risorse all'interno della pagina.

Consulta il riepilogo delle API DevTools per un'introduzione generale all'utilizzo delle API Strumenti per sviluppatori.

Panoramica

La proprietà tabId fornisce l'identificatore della scheda che puoi utilizzare con le chiamate API chrome.tabs.*. Tuttavia, tieni presente che l'API chrome.tabs.* non è esposta alle pagine delle estensioni degli Strumenti per sviluppatori per motivi di sicurezza. Dovrai passare l'ID della scheda alla pagina in background e richiamare le funzioni dell'API chrome.tabs.* da lì.

Il metodo reload può essere utilizzato per ricaricare la pagina ispezionata. Inoltre, il chiamante può specificare un override per la stringa dello user agent, uno script che verrà inserito all'inizio del caricamento pagina o un'opzione per forzare il ricaricamento delle risorse memorizzate nella cache.

Utilizza la chiamata getResources e l'evento onResourceContent per ottenere l'elenco delle risorse (documenti, fogli di stile, script, immagini e così via) all'interno della pagina ispezionata. I metodi getContent e setContent della classe Resource, insieme all'evento onResourceContentCommitted, possono essere utilizzati per supportare la modifica dei contenuti della risorsa, ad esempio da parte di un editor esterno.

Esecuzione del codice nella finestra ispezionata

Il metodo eval consente alle estensioni di eseguire il codice JavaScript nel contesto della pagina ispezionata. Questo metodo è efficace se utilizzato nel contesto giusto e pericoloso se utilizzato in modo inappropriato. Utilizza il metodo tabs.executeScript, a meno che non ti serva la funzionalità specifica fornita dal metodo eval.

Ecco le principali differenze tra i metodi eval e tabs.executeScript:

  • Il metodo eval non utilizza un isolated world per il codice in fase di valutazione, pertanto lo stato JavaScript della finestra ispezionata è accessibile al codice. Utilizza questo metodo quando è necessario l'accesso allo stato JavaScript della pagina ispezionata.
  • Il contesto di esecuzione del codice in fase di valutazione include l'API della console Strumenti per sviluppatori. Ad esempio, il codice può utilizzare inspect e $0.
  • Il codice valutato potrebbe restituire un valore che viene passato al callback dell'estensione. Il valore restituito deve essere un oggetto JSON valido (può contenere solo tipi JavaScript primitivi e riferimenti aciclici ad altri oggetti JSON). Presta particolare attenzione durante l'elaborazione dei dati ricevuti dalla pagina ispezionata: il contesto di esecuzione è essenzialmente controllato dalla pagina ispezionata; una pagina dannosa potrebbe influire sui dati restituiti all'estensione.

Tieni presente che una pagina può includere più contesti di esecuzione JavaScript diversi. Ogni frame ha il proprio contesto, oltre a un contesto aggiuntivo per ogni estensione con script di contenuti in esecuzione in quel frame.

Per impostazione predefinita, il metodo eval viene eseguito nel contesto del frame principale della pagina ispezionata.

Il metodo eval accetta un secondo argomento facoltativo che puoi utilizzare per specificare il contesto in cui viene valutato il codice. Questo oggetto options può contenere una o più delle seguenti chiavi:

frameURL
Utilizzalo per specificare un frame diverso da quello principale della pagina ispezionata.
contextSecurityOrigin
Utilizza questo comando per selezionare un contesto all'interno del frame specificato in base alla sua origine web.
useContentScriptContext
Se true, esegui lo script nello stesso contesto degli script dei contenuti delle estensioni. (Equivale a specificare l'origine web dell'estensione come origine di sicurezza del contesto). Può essere utilizzato per scambiare dati con lo script dei contenuti.

Esempi

Il seguente codice verifica la versione di jQuery utilizzata dalla pagina ispezionata:

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

Per provare questa API, installa gli esempi di API devtools dal repository chrome-extension-samples.

Tipi

Resource

Una risorsa all'interno della pagina controllata, ad esempio un documento, uno script o un'immagine.

Proprietà

  • url

    stringa

    L'URL della risorsa.

  • getContent

    void

    Promise

    Recupera i contenuti della risorsa.

    La funzione getContent ha il seguente aspetto: 

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

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      (response: object) => void

      • risposta

        oggetto

        Chrome 151 e versioni successive

        Un oggetto contenente i contenuti della risorsa e la relativa codifica.

        • contenuti

          stringa

          Contenuto della risorsa (potenzialmente codificato).

        • encoding

          stringa

          Vuoto se i contenuti non sono codificati, altrimenti il nome della codifica. Al momento è supportato solo base64.

    • returns

      Promise<object>

      Chrome 151 e versioni successive

      Una funzione che riceve i contenuti della risorsa al completamento della richiesta.

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

  • setContent

    void

    Promise

    Imposta i contenuti della risorsa.

    La funzione setContent ha il seguente aspetto: 

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

    • contenuti

      stringa

      Nuovi contenuti della risorsa. Al momento sono supportate solo le risorse di tipo testo.

    • commit

      booleano

      True se l'utente ha terminato di modificare la risorsa e i nuovi contenuti della risorsa devono essere mantenuti; false se si tratta di una modifica minore inviata durante la modifica della risorsa da parte dell'utente.

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      (error?: object) => void

      • errore

        object facoltativo

        Impostato su undefined se i contenuti della risorsa sono stati impostati correttamente; in caso contrario, descrive l'errore.

    • returns

      Promise<object>

      Chrome 151 e versioni successive

      Una funzione chiamata al completamento della richiesta.

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Proprietà

tabId

L'ID della scheda in fase di ispezione. Questo ID può essere utilizzato con chrome.tabs.* tramite Google Cloud CLI o tramite l'API Compute Engine.

Tipo

numero

Metodi

eval()

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

Valuta un'espressione JavaScript nel contesto del frame principale della pagina ispezionata. L'espressione deve restituire un oggetto conforme a JSON, altrimenti viene generata un'eccezione. La funzione eval può segnalare un errore lato DevTools o un'eccezione JavaScript che si verifica durante la valutazione. In entrambi i casi, il parametro result del callback è undefined. In caso di errore lato DevTools, il parametro isException non è nullo e ha isError impostato su true e code impostato su un codice di errore. In caso di errore JavaScript, isException viene impostato su true e value viene impostato sul valore stringa dell'oggetto generato.

Parametri

  • espressione

    stringa

    Un'espressione da valutare.

  • opzioni

    object facoltativo

    Il parametro options può contenere una o più opzioni.

    • frameURL

      stringa facoltativa

      Se specificata, l'espressione viene valutata nell'iframe il cui URL corrisponde a quello specificato. Per impostazione predefinita, l'espressione viene valutata nel frame superiore della pagina ispezionata.

    • scriptExecutionContext

      stringa facoltativa

      Chrome 107 e versioni successive

      Valuta l'espressione nel contesto di uno script di contenuti di un'estensione che corrisponde all'origine specificata. Se specificato, scriptExecutionContext sostituisce l'impostazione "true" su useContentScriptContext.

    • useContentScriptContext

      boolean facoltativo

      Valuta l'espressione nel contesto dello script dei contenuti dell'estensione chiamante, a condizione che lo script dei contenuti sia già stato inserito nella pagina ispezionata. In caso contrario, l'espressione non viene valutata e il callback viene richiamato con il parametro di eccezione impostato su un oggetto con il campo isError impostato su true e il campo code impostato su E_NOTFOUND.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: object) => void

    • risposta

      oggetto

      Chrome 151 e versioni successive

      Il risultato della valutazione e le informazioni sulle eccezioni.

      • exceptionInfo

        oggetto

        Un oggetto che fornisce i dettagli se si è verificata un'eccezione durante la valutazione dell'espressione.

        • codice

          stringa

          Impostato se l'errore si è verificato sul lato DevTools prima della valutazione dell'espressione.

        • descrizione

          stringa

          Impostato se l'errore si è verificato sul lato DevTools prima della valutazione dell'espressione.

        • dettagli

          any[]

          Impostato se l'errore si è verificato sul lato DevTools prima della valutazione dell'espressione, contiene l'array dei valori che possono essere sostituiti nella stringa di descrizione per fornire ulteriori informazioni sulla causa dell'errore.

        • isError

          booleano

          Impostato se l'errore si è verificato sul lato DevTools prima della valutazione dell'espressione.

        • isException

          booleano

          Impostato se il codice valutato genera un'eccezione non gestita.

        • valore

          stringa

          Impostato se il codice valutato genera un'eccezione non gestita.

      • risultato

        oggetto

        Il risultato della valutazione.

Resi

  • Promise<object>

    Chrome 151 e versioni successive

    Una funzione chiamata al termine della valutazione.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getResources()

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

Recupera l'elenco delle risorse dalla pagina ispezionata.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (resources: Resource[]) => void

    • risorse

      Resource[]

      Le risorse all'interno della pagina.

Resi

  • Promise<Resource[]>

    Chrome 151 e versioni successive

    Una funzione che riceve l'elenco di risorse al completamento della richiesta.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

reload()

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

Ricarica la pagina ispezionata.

Parametri

  • reloadOptions

    object facoltativo

    • ignoreCache

      boolean facoltativo

      Se il valore è true, il caricatore ignorerà la cache per tutte le risorse della pagina ispezionata caricate prima dell'attivazione dell'evento load. L'effetto è simile alla pressione di Ctrl+Maiusc+R nella finestra ispezionata o nella finestra Strumenti per sviluppatori.

    • injectedScript

      stringa facoltativa

      Se specificato, lo script verrà inserito in ogni frame della pagina ispezionata immediatamente dopo il caricamento, prima di qualsiasi script del frame. Lo script non verrà inserito dopo i ricaricamenti successivi, ad esempio se l'utente preme Ctrl+R.

    • userAgent

      stringa facoltativa

      Se specificata, la stringa sostituirà il valore dell'intestazione HTTP User-Agent inviata durante il caricamento delle risorse della pagina ispezionata. La stringa sostituirà anche il valore della proprietà navigator.userAgent restituito agli script in esecuzione nella pagina ispezionata.

Eventi

onResourceAdded

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

Attivato quando una nuova risorsa viene aggiunta alla pagina ispezionata.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (resource: Resource) => void

onResourceContentCommitted

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

Attivato quando viene eseguito il commit di una nuova revisione della risorsa (ad es. l'utente salva una versione modificata della risorsa negli Strumenti per sviluppatori).

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • risorsa

      Risorsa

    • contenuti

      stringa