Estensione di DevTools

Panoramica

Un'estensione DevTools aggiunge funzionalità a Chrome DevTools. Può aggiungere nuovi riquadri e barre laterali dell'interfaccia utente, interagire con la pagina ispezionata, ottenere informazioni sulle richieste di rete e altro ancora. Visualizza le estensioni DevTools in primo piano . Le estensioni DevTools hanno accesso a un insieme aggiuntivo di API di estensione specifiche di DevTools:

Un'estensione DevTools è strutturata come qualsiasi altra estensione: può avere una pagina di sfondo, script di contenuti e altri elementi. Inoltre, ogni estensione DevTools ha una pagina DevTools, che ha accesso alle API DevTools.

Diagramma dell'architettura che mostra la pagina DevTools che comunica con la finestra ispezionata e la pagina di sfondo. La pagina di sfondo viene mostrata comunicare con gli script di contenuti e accedere alle API delle estensioni. La pagina DevTools ha accesso alle API DevTools, ad esempio per la creazione di riquadri.

La pagina DevTools

Viene creata un'istanza della pagina DevTools dell'estensione ogni volta che si apre una finestra DevTools. La pagina DevTools esiste per la durata della finestra DevTools. La pagina DevTools ha accesso alle API DevTools e a un insieme limitato di API di estensione. In particolare, la pagina DevTools può:

  • Creare e interagire con i riquadri utilizzando le devtools.panels API.
  • Ottenere informazioni sulla finestra ispezionata e valutare il codice nella finestra ispezionata utilizzando le devtools.inspectedWindow API.
  • Ottenere informazioni sulle richieste di rete utilizzando le devtools.network API.

La pagina DevTools non può utilizzare direttamente la maggior parte delle API delle estensioni. Ha accesso allo stesso sottoinsieme delle extension e runtime API a cui ha accesso uno script di contenuti. Come uno script di contenuti, una pagina DevTools può comunicare con la pagina di sfondo utilizzando il passaggio di messaggi. Per un esempio, consulta Inserire uno script di contenuti.

Creare un'estensione DevTools

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

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

Viene creata un'istanza di devtools_page specificata nel manifest dell'estensione per ogni finestra DevTools aperta. La pagina può aggiungere altre pagine di estensione come riquadri e barre laterali alla finestra DevTools utilizzando l'API devtools.panels.

I moduli API chrome.devtools.* sono disponibili solo per le pagine caricate nella finestra DevTools. Gli script di contenuti e le altre pagine di estensione non hanno queste API. Pertanto, le API sono disponibili solo per la durata della finestra DevTools.

Esistono anche alcune API DevTools che sono ancora sperimentali. Consulta chrome.experimental.* API per l'elenco delle API sperimentali e le linee guida su come utilizzarle.

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. (Tieni presente che l'aspetto dei riquadri della barra laterale potrebbe non corrispondere all'immagine, a seconda della versione di Chrome che utilizzi e della posizione in cui è ancorata la finestra DevTools.)

Finestra DevTools che mostra il riquadro Elementi e il riquadro della barra laterale Stili.

Ogni riquadro è un file HTML separato, che può includere altre risorse (JavaScript, CSS, immagini e così via). La creazione di un riquadro di base è simile alla seguente:

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.

La creazione di un riquadro della barra laterale di base per il riquadro Elementi è simile alla seguente:

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 e visualizza il valore restituito.

Per setObject e setExpression, il riquadro visualizza il valore così come apparirebbe nella console DevTools. Tuttavia, setExpression consente di visualizzare elementi DOM e oggetti JavaScript arbitrari, mentre setObject supporta solo gli oggetti JSON.

Comunicare tra i componenti dell'estensione

Le sezioni seguenti descrivono alcuni scenari tipici per la comunicazione tra i diversi componenti di un'estensione DevTools.

Inserire uno script di contenuti

La pagina DevTools non può chiamare tabs.executeScript direttamente. Per inserire uno script di contenuti da la pagina DevTools, devi recuperare l'ID della scheda della finestra ispezionata utilizzando la proprietà inspectedWindow.tabId e inviare un messaggio alla pagina di sfondo. Dalla pagina di sfondo, chiama tabs.executeScript per inserire lo script.

I seguenti snippet di codice mostrano come inserire uno script di contenuti utilizzando executeScript.

// DevTools page -- devtools.js
// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
    name: "devtools-page"
});

backgroundPageConnection.onMessage.addListener(function (message) {
    // Handle responses from the background page, if any
});

// Relay the tab ID to the background page
chrome.runtime.sendMessage({
    tabId: chrome.devtools.inspectedWindow.tabId,
    scriptToInject: "content_script.js"
});

Codice per la pagina di sfondo:

// Background page -- background.js
chrome.runtime.onConnect.addListener(function(devToolsConnection) {
    // assign the listener function to a variable so we can remove it later
    var devToolsListener = function(message, sender, sendResponse) {
        // Inject a content script into the identified tab
        chrome.tabs.executeScript(message.tabId,
            { file: message.scriptToInject });
    }
    // add the listener
    devToolsConnection.onMessage.addListener(devToolsListener);

    devToolsConnection.onDisconnect.addListener(function() {
         devToolsConnection.onMessage.removeListener(devToolsListener);
    });
});

Valutare JavaScript nella finestra ispezionata

Puoi utilizzare il metodo inspectedWindow.eval per eseguire codice JavaScript 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. Ora, potresti avere familiarità con le funzionalità dell'API della riga di comandodi DevTools, come l'ispezione degli elementi (inspect(elem)), l'interruzione delle funzioni (debug(fn)), la copia negli appunti (copy()) e altro ancora. inspectedWindow.eval() utilizza lo stesso contesto di esecuzione dello script e le stesse opzioni del codice digitato nella console DevTools, il che consente l'accesso a queste API all'interno di eval. Ad esempio, SOAK lo utilizza per ispezionare un elemento:

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

In alternativa, utilizza l'opzione useContentScriptContext: true per inspectedWindow.eval() per valutare l'espressione nello stesso contesto degli script di contenuti. La chiamata di eval con useContentScriptContext: true non crea un contesto di script di contenuti, quindi devi caricare uno script di contesto prima di chiamare eval, chiamando executeScript o specificando uno script di contenuti nel file manifest.json.

Una volta creato il contesto dello script di contesto, puoi utilizzare questa opzione per inserire altri script di contenuti.

Il metodo eval è potente se utilizzato nel contesto giusto e pericoloso se utilizzato in modo inappropriato. Utilizza il metodo tabs.executeScript se non hai bisogno di accedere al contesto JavaScript della pagina ispezionata. Per precauzioni dettagliate e un confronto tra i due metodi, consulta inspectedWindow.

Trasmettere 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 della riga di comando. Ad esempio, nel codice valutato puoi utilizzare $0 per accedere all'elemento selezionato.

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

  • Crea un metodo nello script di contenuti che accetta l'elemento selezionato come argomento.
  • Chiama il metodo dalla pagina DevTools utilizzando inspectedWindow.eval con l'opzione useContentScriptContext: true.

Il codice nello script di contenuti potrebbe essere simile al seguente:

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

Richiama il metodo dalla pagina DevTools nel seguente modo:

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 la window di un riquadro di riferimento

Per postMessage da un riquadro DevTools, ti servirà un riferimento al relativo oggetto window. Ottieni la finestra iframe di un riquadro dal gestore di eventi panel.onShown:

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

Invio di messaggi dagli script di contenuti alla pagina DevTools

L'invio di messaggi tra la pagina DevTools e gli script di contenuti è indiretto, tramite la pagina di sfondo.

Quando invia un messaggio a uno script di contenuti, la pagina di sfondo può utilizzare il tabs.sendMessage metodo, che indirizza un messaggio agli script di contenuti in una scheda specifica, come mostrato in Inserire uno script di contenuti.

Quando invia un messaggio da uno script di contenuti, non esiste un metodo predefinito per inviare un messaggio all'istanza della pagina DevTools corretta associata alla scheda corrente. Come soluzione alternativa, puoi fare in modo che la pagina DevTools stabilisca una connessione a lunga durata con la pagina di sfondo e che la pagina di sfondo mantenga una mappa degli ID delle schede alle connessioni, in modo che possa instradare ogni messaggio alla connessione corretta.

// background.js
var connections = {};

chrome.runtime.onConnect.addListener(function (port) {

    var extensionListener = function (message, sender, sendResponse) {

        // The original connection event doesn't include the tab ID of the
        // DevTools page, so we need to send it explicitly.
        if (message.name == "init") {
          connections[message.tabId] = port;
          return;
        }

    // other message handling
    }

    // Listen to messages sent from the DevTools page
    port.onMessage.addListener(extensionListener);

    port.onDisconnect.addListener(function(port) {
        port.onMessage.removeListener(extensionListener);

        var tabs = Object.keys(connections);
        for (var i=0, len=tabs.length; i < len; i++) {
          if (connections[tabs[i]] == port) {
            delete connections[tabs[i]]
            break;
          }
        }
    });
});

// Receive message from content script and relay to the devTools page for the
// current tab
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
    // Messages from content scripts should have sender.tab set
    if (sender.tab) {
      var tabId = sender.tab.id;
      if (tabId in connections) {
        connections[tabId].postMessage(request);
      } else {
        console.log("Tab not found in connection list.");
      }
    } else {
      console.log("sender.tab not defined.");
    }
    return true;
});

La pagina DevTools (o il riquadro o il riquadro della barra laterale) stabilisce la connessione nel seguente modo:

// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
    name: "panel"
});

backgroundPageConnection.postMessage({
    name: 'init',
    tabId: chrome.devtools.inspectedWindow.tabId
});

Invio di messaggi dagli script inseriti alla pagina DevTools

Sebbene la soluzione precedente funzioni per gli script di contenuti, il codice inserito direttamente nella pagina (ad es. tramite l'aggiunta di un tag <script> o tramite inspectedWindow.eval) richiede una strategia diversa. In questo contesto, runtime.sendMessage non passerà i messaggi allo script di sfondo come previsto.

Come soluzione alternativa, puoi combinare lo script inserito con uno script di contenuti che funge da intermediario. Per passare i messaggi allo script di contenuti, puoi utilizzare l'window.postMessage API. Ecco un esempio, presupponendo 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
  if (typeof message !== 'object' || message === null ||
      !message.source === 'my-devtools-extension') {
    return;
  }

  chrome.runtime.sendMessage(message);
});

Il messaggio ora passerà dallo script inserito allo script di contenuti, allo script di sfondo e infine alla pagina DevTools.

Puoi anche prendere in considerazione due tecniche alternative di passaggio dei messaggi qui.

Rilevare quando DevTools si apre e si chiude

Se l'estensione deve monitorare se la finestra DevTools è aperta, puoi aggiungere un listener onConnect alla pagina di sfondo e chiamare 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, devi contare gli eventi di connessione e disconnessione come mostrato di seguito:

// 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 nel seguente modo:

// devtools.js

// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
    name: "devtools-page"
});

Esempi di estensioni DevTools

Sfoglia l'origine di questi esempi di estensioni DevTools:

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.