Estendi DevTools

Le estensioni DevTools aggiungono funzionalità a Chrome DevTools accedendo alle API delle estensioni specifiche di DevTools tramite una pagina DevTools aggiunta all'estensione.

Diagramma dell'architettura che mostra la pagina DevTools che comunica con la finestra ispezionata e il service worker. Il service worker viene mostrato mentre comunica con gli script dei contenuti e accede alle API delle estensioni. La pagina DevTools ha accesso alle API DevTools, ad esempio creando i riquadri.
Architettura delle estensioni DevTools.

Le API di estensione specifiche di DevTools includono quanto segue:

La pagina DevTools

Quando si apre una finestra DevTools, un'estensione DevTools crea un'istanza della pagina DevTools che esiste finché la finestra è aperta. Questa pagina può accedere alle API DevTools e alle API delle estensioni ed eseguire le seguenti operazioni:

  • Crea e interagisci con i riquadri usando le API devtools.panels, ad esempio aggiungendo altre pagine di estensioni come riquadri o barre laterali alla finestra DevTools.
  • Ottieni informazioni sulla finestra ispezionata e valuta il codice nella finestra ispezionata utilizzando le API devtools.inspectedWindow.
  • Ottenere informazioni sulle richieste di rete utilizzando le API di devtools.network.
  • Estendi il riquadro Registratore utilizzando le API devtools.recorder.

La pagina DevTools può accedere direttamente alle API delle estensioni. Ciò include la possibilità di comunicare con il service worker utilizzando la trasmissione di messaggi.

Crea un'estensione DevTools

Per creare una pagina DevTools per l'estensione, aggiungi il campo devtools_page nel file manifest dell'estensione:

{
  "name": ...
  "version": "1.0",
  "devtools_page": "devtools.html",
  ...
}

Il campo devtools_page deve puntare a una pagina HTML. Poiché la pagina DevTools deve essere locale dell'estensione, ti consigliamo di specificarla utilizzando un URL relativo.

I membri dell'API chrome.devtools sono disponibili solo per le pagine caricate all'interno della finestra DevTools quando questa è aperta. Gli script di contenuti e le pagine di altre estensioni non hanno accesso a queste API.

Elementi dell'interfaccia utente di DevTools: riquadri e riquadri della barra laterale

Oltre ai consueti elementi UI delle estensioni, ad esempio azioni del browser, menu contestuali e popup, un'estensione DevTools può aggiungere elementi UI 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 relativa 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 in uso e di dove è agganciata la finestra DevTools, i riquadri della barra laterale potrebbero avere l'aspetto della seguente immagine di esempio:
Finestra DevTools che mostra il riquadro Elementi e il riquadro della barra laterale Stili.
Finestra DevTools che mostra il riquadro Elementi e il riquadro della barra laterale Stili.

Ogni riquadro è il proprio file HTML, che può includere altre risorse (JavaScript, CSS, immagini e così via). Per creare un riquadro di base, utilizza il codice seguente:

chrome.devtools.panels.create("My Panel",
    "MyPanelIcon.png",
    "Panel.html",
    function(panel) {
      // code invoked on panel creation
    }
);

JavaScript eseguito in un riquadro o nel riquadro della barra laterale ha accesso alle stesse API della pagina DevTools.

Per creare un riquadro di base nella barra laterale, 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: trasmetti 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.

Sia per setObject() che per setExpression(), il riquadro mostra il valore visualizzato nella console di DevTools. Tuttavia, setExpression() consente di visualizzare elementi DOM e oggetti JavaScript arbitrari, mentre setObject() supporta solo gli oggetti JSON.

Comunicazione tra componenti delle estensioni

Le seguenti sezioni descrivono alcuni modi utili per consentire ai componenti dell'estensione DevTools di comunicare tra loro.

Inserisci 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 proprietà inspectedWindow.tabId.

Se uno script di contenuti è già stato inserito, puoi utilizzare le API di messaggistica per comunicare con questo script.

Valuta JavaScript nella finestra ispezionata

Puoi utilizzare il metodo inspectedWindow.eval() per eseguire il codice JavaScript nel contesto della pagina ispezionata. Puoi richiamare il metodo eval() da una pagina, un riquadro o un riquadro della barra laterale di DevTools.

Per impostazione predefinita, l'espressione viene valutata nel contesto del frame principale della pagina. inspectedWindow.eval() utilizza lo stesso contesto di esecuzione dello script e le stesse opzioni del codice inserito nella console DevTools, il che consente di accedere alle funzionalità dell'API Console Utilities di DevTools quando utilizzi eval(). Ad esempio, SOAK lo utilizza per ispezionare un elemento:

chrome.devtools.inspectedWindow.eval(
  "inspect($$('head script[data-soak=main]')[0])",
  function(result, isException) { }
);

Puoi anche impostare useContentScriptContext su true quando chiami inspectedWindow.eval() per valutare l'espressione nello stesso contesto degli script dei contenuti. Per utilizzare questa opzione, utilizza una dichiarazione dello script di contenuti statici prima di chiamare eval(), chiamando executeScript() o specificando uno script dei contenuti nel file manifest.json. Una volta caricato il contesto dello script di contesto, puoi utilizzare questa opzione anche per inserire altri script di contenuti.

Trasmettere l'elemento selezionato a uno script di contenuti

Lo script dei 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 Utilities della console. Ad esempio, nel codice valutato puoi utilizzare $0 per accedere all'elemento selezionato.

Per trasmettere l'elemento selezionato a uno script di contenuti:

  1. Crea nello script dei contenuti un metodo che utilizzi l'elemento selezionato come argomento.

    function setSelectedElement(el) {
    // do something with the selected element
}

  2. Chiama il metodo dalla pagina DevTools utilizzando inspectedWindow.eval() con l'opzione useContentScriptContext: 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 dei contenuti, in modo che possa accedere al metodo setSelectedElement.

Ottieni window di un riquadro di riferimento

Per chiamare postMessage() da un riquadro DevTools, hai bisogno di un riferimento al relativo oggetto window. Ottieni la finestra iframe di un riquadro dal gestore di eventi panel.onShown:

extensionPanel.onShown.addListener(function (extPanelWindow) {
    extPanelWindow instanceof Window; // true
    extPanelWindow.postMessage( // …
});

Invia messaggi dagli script inseriti alla pagina DevTools

Il codice inserito direttamente nella pagina senza uno script di contenuti, ad esempio aggiungendo un tag <script> o chiamando 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ò agire da intermediario e utilizzare il metodo window.postMessage(). L'esempio seguente utilizza lo script in background 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 per la trasmissione dei messaggi sono disponibili su GitHub.

Rileva l'apertura e la chiusura di DevTools

Per monitorare se la finestra DevTools è aperta, aggiungi un listener onConnect 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 una finestra DevTools è aperta, conteggia 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 la seguente:

// 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 condivisa 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ù interessanti da installare, provare e da cui imparare.

Maggiori informazioni

Per informazioni sulle API standard che le estensioni possono utilizzare, visita la pagina chrome.* API e API web.

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