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 oppure ricevi l'elenco delle risorse all'interno della pagina.
Manifest
Per poter utilizzare questa API, le seguenti chiavi devono essere dichiarate nel manifest.
"devtools_page"
Utilizza 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 oppure ottieni l'elenco delle risorse all'interno della pagina.
Consulta il riepilogo delle API degli strumenti per sviluppatori per un'introduzione generale all'utilizzo delle API degli strumenti per sviluppatori.
Panoramica
La proprietà tabId
fornisce l'identificatore di scheda che puoi utilizzare con le chiamate API chrome.tabs.*
. Tuttavia, tieni presente che l'API chrome.tabs.*
non è esposta alle pagine dell'estensione Strumenti per sviluppatori per motivi di sicurezza: dovrai passare l'ID scheda alla pagina in background e richiamare le funzioni dell'API chrome.tabs.*
da lì.
Puoi usare il metodo reload
per ricaricare la pagina ispezionata. Inoltre, il chiamante può specificare un override per la stringa dello user agent, uno script che verrà inserito in anticipo al caricamento della 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 di risorse
(documenti, fogli di stile, script, immagini e così via) all'interno della pagina ispezionata. I metodi getContent
e setContent
della classe Resource
e l'evento onResourceContentCommitted
possono essere usati 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 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 tu non abbia bisogno della funzionalità specifica
fornita dal metodo eval
.
Ecco le principali differenze tra i metodi eval
e tabs.executeScript
:
- Il metodo
eval
non utilizza un mondo isolato per il codice valutato, pertanto lo stato JavaScript della finestra di ispezione è accessibile al codice. Utilizza questo metodo quando è richiesto l'accesso allo stato JavaScript della pagina ispezionata. - Il contesto di esecuzione del codice valutato include l'API della console Strumenti per sviluppatori.
Ad esempio, nel codice possono essere utilizzati
inspect
e$0
. - Il codice valutato potrebbe restituire un valore trasmesso 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 un proprio contesto, oltre a un contesto aggiuntivo per ogni estensione con script di contenuti in esecuzione nel frame.
Per impostazione predefinita, il metodo eval
viene eseguito nel contesto del frame principale della pagina ispezionata.
Il metodo eval
richiede 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
- Da utilizzare per specificare un frame diverso da quello principale della pagina ispezionata.
contextSecurityOrigin
- Utilizza questa opzione per selezionare un contesto all'interno del frame specificato in base alla sua origine web.
useContentScriptContext
- Se il valore è true, esegui lo script nello stesso contesto degli script dei contenuti dell'estensione. (Equivale a specificare l'origine web delle estensioni come origine della sicurezza del contesto). Questa può essere usata per scambiare dati con lo script dei contenuti.
Esempi
Il codice seguente 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 ispezionata, ad esempio un documento, uno script o un'immagine.
Proprietà
-
url
stringa
L'URL della risorsa.
-
getContent
void
Recupera i contenuti della risorsa.
La funzione
getContent
ha il seguente aspetto:(callback: function) => {...}
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(content: string, encoding: string) => void
-
nuovi, di alta qualità, pertinenti e variegati
stringa
Contenuti della risorsa (potenzialmente codificati).
-
codifica
stringa
Vuoto se i contenuti non sono codificati, altrimenti il nome di codifica. Al momento è supportato solo il formato base64.
-
-
-
setContent
void
Imposta i contenuti della risorsa.
La funzione
setContent
ha il seguente aspetto:(content: string, commit: boolean, callback?: function) => {...}
-
nuovi, di alta qualità, pertinenti e variegati
stringa
Nuovi contenuti della risorsa. Al momento sono supportate solo risorse di tipo testo.
-
commit
boolean
True se l'utente ha completato la modifica della risorsa e i nuovi contenuti devono essere resi persistenti; false se si tratta di una modifica di minore entità inviata mentre l'utente sta modificando la risorsa.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(error?: object) => void
-
errore
oggetto facoltativo
Imposta su non definito se il contenuto della risorsa è stato impostato correttamente; altrimenti descrive l'errore.
-
-
Proprietà
tabId
L'ID della scheda ispezionata. Questo ID può essere utilizzato con chrome.tabs.* API.
Tipo
numero
Metodi
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
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 di valutazione 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
è diverso da null e ha isError
impostato su true e code
su un codice di errore. In caso di errore JavaScript, isException
viene impostato su true e value
sul valore stringa dell'oggetto generato.
Parametri
-
espressione
stringa
Un'espressione da valutare.
-
opzioni
oggetto facoltativo
Il parametro delle opzioni può contenere una o più opzioni.
-
frameURL
stringa facoltativo
Se specificato, l'espressione viene valutata sull'iframe il cui URL corrisponde a quello specificato. Per impostazione predefinita, l'espressione viene valutata nel frame superiore della pagina ispezionata.
-
scriptExecutionContext
stringa facoltativo
Chrome 107 e versioni successiveValuta l'espressione nel contesto di uno script di contenuti di un'estensione che corrisponde all'origine specificata. Se fornito, scriptExecutionContext sostituisce l'impostazione "true" in useContentScriptContext.
-
useContentScriptContext
booleano facoltativo
Valuta l'espressione nel contesto dello script dei contenuti dell'estensione di chiamata, a condizione che lo script dei contenuti sia già 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 campocode
impostato suE_NOTFOUND
.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: object, exceptionInfo: object) => void
-
risultato
oggetto
Il risultato della valutazione.
-
exceptionInfo
oggetto
Un oggetto che fornisce dettagli se si è verificata un'eccezione durante la valutazione dell'espressione.
-
codice
stringa
Da impostare se l'errore si è verificato sul lato DevTools prima che venga valutata l'espressione.
-
descrizione
stringa
Da impostare se l'errore si è verificato sul lato DevTools prima che venga valutata l'espressione.
-
dettagli
qualsiasi[]
Da impostare se l'errore si è verificato sul lato DevTools prima che l'espressione venga valutata. Contiene l'array di valori che possono essere sostituiti nella stringa di descrizione per fornire ulteriori informazioni sulla causa dell'errore.
-
isError
boolean
Da impostare se l'errore si è verificato sul lato DevTools prima che venga valutata l'espressione.
-
isException
boolean
Da impostare se il codice valutato produce un'eccezione non gestita.
-
valore
stringa
Da impostare se il codice valutato produce un'eccezione non gestita.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Recupera l'elenco delle risorse dalla pagina ispezionata.
Parametri
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Ricarica la pagina ispezionata.
Parametri
-
reloadOptions
oggetto facoltativo
-
ignoreCache
booleano facoltativo
Se il valore è true, il caricatore ignorerà la cache per tutte le risorse della pagina ispezionate caricate prima che venga attivato l'evento
load
. L'effetto è simile alla pressione di Ctrl+Maiusc+R nella finestra ispezionata o nella finestra Strumenti per sviluppatori. -
injectedScript
stringa facoltativo
Se specificato, lo script verrà inserito in ogni frame della pagina ispezionata subito dopo il caricamento, prima di qualsiasi script del frame. Lo script non verrà inserito dopo successivi ricaricamenti, ad esempio se l'utente preme Ctrl+R.
-
userAgent
stringa facoltativo
Se specificato, 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 per gli script in esecuzione nella pagina ispezionata.
-
Eventi
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Si attiva quando viene aggiunta una nuova risorsa alla pagina ispezionata.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(resource: Resource) => void
-
risorsa
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Attivato quando viene eseguito il commit di una nuova revisione della risorsa (ad esempio, l'utente salva una versione modificata della risorsa negli Strumenti per sviluppatori).