Le estensioni DevTools aggiungono funzionalità a Chrome DevTools accedendo alle API di estensione specifiche di DevTools tramite una pagina DevTools aggiunta all'estensione.
Le API di estensione specifiche di DevTools includono le seguenti:
La pagina DevTools
Quando si apre una finestra DevTools, un'estensione DevTools crea un'istanza della relativa pagina DevTools che esiste finché la finestra è aperta. Questa pagina ha accesso alle API DevTools e alle API di estensione e può eseguire le seguenti operazioni:
- Crea e interagisci con i riquadri utilizzando le
devtools.panelsAPI, inclusa l'aggiunta di altre pagine di estensione come riquadri o barre laterali alla finestra DevTools. - Ottieni informazioni sulla finestra ispezionata e valuta il codice nella finestra ispezionata utilizzando le
devtools.inspectedWindowAPI. - Ottieni informazioni sulle richieste di rete utilizzando le
devtools.networkAPI. - Estendi il riquadro Registratore utilizzando le
devtools.recorderAPI. - Ottieni informazioni sullo stato di registrazione del riquadro Rendimento utilizzando le
devtools.performanceAPI.
La pagina DevTools può accedere direttamente alle API delle estensioni. Ciò include la possibilità di comunicare con il service worker utilizzando il passaggio di messaggi.
Creare un'estensione DevTools
Per creare una pagina DevTools per la tua estensione, aggiungi il campo devtools_page nel manifest dell'estensione:
{
"name": ...
"version": "1.0",
"devtools_page": "devtools.html",
...
}
Il campo devtools_page deve rimandare a una pagina HTML. Poiché la pagina DevTools deve essere locale per l'estensione, ti consigliamo di specificarla utilizzando un URL relativo.
I membri dell'API chrome.devtools sono disponibili solo per le pagine caricate nella finestra DevTools mentre questa è aperta. Gli script di contenuti e le altre pagine di estensione non hanno accesso a queste API.
Lo spazio dei nomi del browser e le estensioni DevTools
Nelle versioni di Chrome 152 e successive, le estensioni con una pagina DevTools possono utilizzare lo spazio dei nomi browser.
Nelle versioni di Chrome precedenti alla 152, lo spazio dei nomi browser
era disattivato per le estensioni che dichiarano
devtools_page. La disattivazione si applicava all'intera estensione, non solo alla pagina DevTools, ma a ogni contesto di script in cui vengono eseguite le API di estensione.
Il motivo era una lacuna di compatibilità con
webextension-polyfill.
Le API chrome.devtools.* precedenti a Chrome 152 erano solo di callback, non restituivano le promesse in modo nativo, quindi le estensioni DevTools si basavano in genere sul polyfill per eseguirne il wrapping. Il polyfill salta il wrapping ogni volta che viene definito browser, presupponendo che l'host abbia già eseguito il lavoro. Se Chrome avesse attivato browser per queste estensioni, il polyfill non avrebbe eseguito alcuna operazione e le chiamate chrome.devtools.* avrebbero smesso di restituire le promesse. Mantenendo browser disattivato, il polyfill continuava a eseguire il wrapping.
La stessa disattivazione ha disattivato anche le altre modifiche dell'API di messaggistica di Chrome 148
per queste estensioni, incluse
le risposte di promessa in runtime.onMessage.
La limitazione è stata rimossa quando le API DevTools hanno supportato le promesse in modo nativo.
Elementi dell'interfaccia utente di DevTools: riquadri e riquadri della barra laterale
Oltre ai normali elementi dell'interfaccia utente delle estensioni, come le azioni del browser, i menu contestuali e i popup, un'estensione DevTools può aggiungere elementi dell'interfaccia utente alla finestra DevTools:
- Un riquadro è una scheda di primo livello, come i riquadri Elementi, Sorgenti e Rete.
- Un riquadro della barra laterale presenta un'interfaccia utente supplementare correlata a un riquadro. I riquadri Stili, Stili elaborati e Listener di eventi nel riquadro Elementi sono esempi di riquadri della barra laterale. A seconda della versione di Chrome che utilizzi e della posizione in cui è ancorata la finestra DevTools, i riquadri della barra laterale potrebbero essere simili all'immagine di esempio seguente:
Ogni riquadro è un file HTML separato, che può includere altre risorse (JavaScript, CSS, immagini e così via). Per creare un riquadro di base, utilizza il seguente codice:
chrome.devtools.panels.create("My Panel",
"MyPanelIcon.png",
"Panel.html",
function(panel) {
// code invoked on panel creation
}
);
Il codice JavaScript eseguito in un riquadro o in un riquadro della barra laterale ha accesso alle stesse API della pagina DevTools.
Per creare un riquadro della barra laterale di base, utilizza il seguente codice:
chrome.devtools.panels.elements.createSidebarPane("My Sidebar",
function(sidebar) {
// sidebar initialization code here
sidebar.setObject({ some_data: "Some data to show" });
});
Esistono diversi modi per visualizzare i contenuti in un riquadro della barra laterale:
- Contenuti HTML: chiama
setPage()per specificare una pagina HTML da visualizzare nel riquadro. - Dati JSON: passa un oggetto JSON a
setObject(). - Espressione JavaScript: passa un'espressione a
setExpression(). DevTools valuta l'espressione nel contesto della pagina ispezionata, quindi visualizza il valore restituito.
Per setObject() e setExpression(), il riquadro visualizza il valore così come apparirebbe nella console DevTools. Tuttavia, setExpression() ti consente di visualizzare gli elementi DOM e gli oggetti JavaScript arbitrari, mentre setObject() supporta solo gli oggetti JSON.
Comunicare tra i componenti dell'estensione
Le sezioni seguenti descrivono alcuni modi utili per consentire ai componenti dell'estensione DevTools di comunicare tra loro.
Inserire uno script di contenuti
Per inserire uno script di contenuti, utilizza scripting.executeScript():
// DevTools page -- devtools.js
chrome.scripting.executeScript({
target: {
tabId: chrome.devtools.inspectedWindow.tabId
},
files: ["content_script.js"]
});
Puoi recuperare l'ID scheda della finestra ispezionata utilizzando la
inspectedWindow.tabId proprietà.
Se è già stato inserito uno script di contenuti, puoi utilizzare le API di messaggistica per comunicare con esso.
Valutare JavaScript nella finestra ispezionata
Puoi utilizzare il inspectedWindow.eval() metodo per eseguire JavaScript
codice nel contesto della pagina ispezionata. Puoi richiamare il metodo eval() da una pagina DevTools, un riquadro o un riquadro della barra laterale.
Per impostazione predefinita, l'espressione viene valutata nel contesto del frame principale della pagina.
inspectedWindow.eval() utilizza lo stesso contesto di esecuzione degli script e le stesse opzioni del codice
inserito nella console DevTools, il che consente l'accesso alle funzionalità dell'API Console Utilities
di DevTools quando si utilizza eval(). Ad esempio, utilizzalo per ispezionare
il primo elemento script nella sezione <head> del documento HTML:
chrome.devtools.inspectedWindow.eval(
"inspect($$('head script')[0])",
function(result, isException) { }
);
Puoi anche impostare useContentScriptContext su true quando chiami inspectedWindow.eval() per valutare l'espressione nello stesso contesto degli script di contenuti. Per utilizzare questa opzione, utilizza una dichiarazione di script di contenuti statici prima di chiamare eval(), chiamando executeScript() o specificando uno script di contenuti
nel file manifest.json. Dopo il caricamento del contesto dello script di contenuti, puoi utilizzare questa opzione anche per inserire altri script di contenuti.
Passare l'elemento selezionato a uno script di contenuti
Lo script di contenuti non ha accesso diretto all'elemento attualmente selezionato. Tuttavia, qualsiasi codice che
esegui utilizzando inspectedWindow.eval() ha accesso alla console DevTools
e alle API Console Utilities. Ad esempio, nel codice valutato puoi utilizzare $0 per accedere all'elemento selezionato.
Per passare l'elemento selezionato a uno script di contenuti:
Crea un metodo nello script di contenuti che accetta l'elemento selezionato come argomento.
function setSelectedElement(el) { // do something with the selected element }Chiama il metodo dalla pagina DevTools utilizzando
inspectedWindow.eval()con l'opzioneuseContentScriptContext: true.chrome.devtools.inspectedWindow.eval("setSelectedElement($0)", { useContentScriptContext: true });
L'opzione useContentScriptContext: true specifica che l'espressione deve essere valutata nello stesso contesto degli script di contenuti, in modo che possa accedere al metodo setSelectedElement.
Ottenere una finestra window di un riquadro di riferimento
Per chiamare postMessage() da un riquadro DevTools, devi avere un riferimento al relativo oggetto window. Ottieni la
finestra iframe di un riquadro dal panel.onShown gestore di eventi:
extensionPanel.onShown.addListener(function (extPanelWindow) {
extPanelWindow instanceof Window; // true
extPanelWindow.postMessage( // …
});
Inviare messaggi dagli script inseriti alla pagina DevTools
Il codice inserito direttamente nella pagina senza uno script di contenuti, incluso l'aggiunta di un <script>
tag o la chiamata di inspectedWindow.eval(), non può inviare messaggi alla
pagina DevTools utilizzando runtime.sendMessage(). Ti consigliamo invece di
combinare lo script inserito con uno script di contenuti che può fungere da intermediario e di utilizzare
il metodo window.postMessage(). L'esempio seguente utilizza lo script di sfondo della sezione precedente:
// injected-script.js
window.postMessage({
greeting: 'hello there!',
source: 'my-devtools-extension'
}, '*');
// content-script.js
window.addEventListener('message', function(event) {
// Only accept messages from the same frame
if (event.source !== window) {
return;
}
var message = event.data;
// Only accept messages that we know are ours. Note that this is not foolproof
// and the page can easily spoof messages if it wants to.
if (typeof message !== 'object' || message === null ||
message.source !== 'my-devtools-extension') {
return;
}
chrome.runtime.sendMessage(message);
});
Altre tecniche alternative di passaggio di messaggi sono disponibili su GitHub.
Rilevare quando DevTools si apre e si chiude
Per monitorare se la finestra DevTools è aperta, aggiungi un onConnect listener al service worker e chiama connect() dalla pagina DevTools. Poiché ogni scheda può avere la propria finestra DevTools aperta, potresti ricevere più eventi di connessione. Per monitorare se è aperta una finestra DevTools, conta gli eventi di connessione e disconnessione come mostrato nell'esempio seguente:
// background.js
var openCount = 0;
chrome.runtime.onConnect.addListener(function (port) {
if (port.name == "devtools-page") {
if (openCount == 0) {
alert("DevTools window opening.");
}
openCount++;
port.onDisconnect.addListener(function(port) {
openCount--;
if (openCount == 0) {
alert("Last DevTools window closing.");
}
});
}
});
La pagina DevTools crea una connessione come questa:
// devtools.js
// Create a connection to the service worker
const serviceWorkerConnection = chrome.runtime.connect({
name: "devtools-page"
});
// Send a periodic heartbeat to keep the port open.
setInterval(() => {
port.postMessage("heartbeat");
}, 15000);
Esempi di estensioni DevTools
Gli esempi in questa pagina provengono dalle seguenti pagine:
- Estensione Polymer DevTools: utilizza molti helper in esecuzione nella pagina host per eseguire query sullo stato DOM/JS da inviare al riquadro personalizzato.
- Estensione React DevTools: utilizza un sottomodulo del renderer per riutilizzare i componenti dell'interfaccia utente di DevTools.
- Ember Inspector: core dell'estensione condiviso con adattatori per Chrome e Firefox.
- Coquette-inspect: un'estensione pulita basata su React con un agente di debug inserito nella pagina host.
- Le estensioni di esempio hanno estensioni più utili da installare, provare e da cui imparare.
Ulteriori informazioni
Per informazioni sulle API standard che le estensioni possono utilizzare, consulta chrome.* API e web API.
Inviaci il tuo feedback. I tuoi commenti e suggerimenti ci aiutano a migliorare le API.
Esempi
Puoi trovare esempi che utilizzano le API DevTools in Esempi.