Estendi DevTools

Le estensioni DevTools aggiungono funzionalità a Chrome DevTools accedendo a strumenti specifici per DevTools. le API dell'estensione tramite una pagina DevTools aggiunta all'estensione.

Diagramma dell'architettura che mostra la pagina DevTools che comunica con il
         finestra ispezionata e il service worker. Viene mostrato il service worker
         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.
Architettura dell'estensione di DevTools.

Le API di estensione specifiche per DevTools includono quanto segue:

Pagina DevTools

Quando si apre una finestra DevTools, un'estensione DevTools crea un'istanza della relativa pagina DevTools che esiste solo se la finestra è aperta. Questa pagina ha accesso alle API DevTools e alle API delle estensioni e può effettuare le seguenti operazioni:

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

Crea un'estensione DevTools

Per creare una pagina DevTools per la tua estensione, aggiungi il campo devtools_page nell'estensione manifest:

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

Il campo devtools_page deve rimandare a una pagina HTML. Poiché i DevTools deve essere locale rispetto all'estensione, ti consigliamo di specificarla con un URL relativo.

I membri dell'API chrome.devtools sono disponibili solo per le pagine caricate in DevTools finestra mentre è aperta. Gli script di contenuti e le altre pagine di estensioni non dispongono dell'accesso a queste API.

Elementi UI DevTools: riquadri e riquadri della barra laterale

Oltre ai soliti elementi dell'interfaccia utente delle estensioni, come le azioni del browser, i menu contestuali e i popup, è disponibile L'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 una UI supplementare relativa a un riquadro. Stili, stili elaborati e I riquadri Listener di eventi nel riquadro Elementi sono esempi di riquadri della barra laterale. In base di Chrome che stai utilizzando e in cui la finestra DevTools è agganciata, i riquadri della barra laterale potrebbero simile alla seguente immagine di esempio:
di Gemini Advanced.
Finestra DevTools che mostra il riquadro Elementi e il riquadro della barra laterale Stili.
Finestra DevTools che mostra il riquadro Elementi e il riquadro Stili nella barra laterale.

Ogni riquadro è il proprio file HTML, che può includere altre risorse (JavaScript, CSS, immagini attiva). 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: richiama 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, poi visualizza il valore restituito.

Sia per setObject() che per setExpression(), il riquadro mostra il valore come apparirebbe nel Console DevTools. Tuttavia, setExpression() consente di visualizzare elementi DOM e JavaScript arbitrario mentre setObject() supporta solo oggetti JSON.

Comunicare tra i componenti delle estensioni

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

Inserisci uno script dei 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 il metodo Proprietà inspectedWindow.tabId.

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

valuta JavaScript nella finestra ispezionata

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

Per impostazione predefinita, l'espressione viene valutata nel contesto del frame principale della pagina. inspectedWindow.eval() utilizza lo stesso contesto e le stesse opzioni di esecuzione dello script del codice inserito nella console DevTools, che consente l'accesso alle utilità della console DevTools API quando si utilizza 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 valutano l'espressione nello stesso contesto degli script di contenuti. Per utilizzare questa opzione, usa una dichiarazione di script di contenuti statici prima di chiamare eval(), chiamando executeScript() o specificando un contenuto nel file manifest.json. Dopo aver caricato il contesto dello script di contesto, puoi utilizzare questa opzione anche per inserire script di contenuti aggiuntivi.

Trasmetti l'elemento selezionato a uno script di contenuti

Lo script dei contenuti non ha accesso diretto all'elemento attualmente selezionato. Tuttavia, qualsiasi codice l'esecuzione con inspectedWindow.eval() ha accesso a DevTools e le API Console Utilities. Ad esempio, nel codice valutato puoi usare $0 per accedere al dell'elemento selezionato.

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

  1. Crea un metodo nello script dei contenuti 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 nel campo stesso contesto degli script di contenuti, in modo che possa accedere al metodo setSelectedElement.

Ottieni window di un pannello di riferimento

Per chiamare postMessage() da un riquadro DevTools, devi avere un riferimento al relativo oggetto window. Ricevi un finestra iframe del 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

Codice inserito direttamente nella pagina senza uno script di contenuti, anche aggiungendo un <script> tag o chiamando inspectedWindow.eval(), non potrai inviare messaggi alla pagina DevTools utilizzando runtime.sendMessage(). Consigliamo invece combinando lo script inserito con uno script di contenuti che possa fungere da intermediario, e utilizzando il metodo window.postMessage(). L'esempio seguente utilizza lo script in background dalla 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 di trasmissione dei messaggi alternative 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 nel seguente esempio:

// 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 Stato DOM/JS da inviare al riquadro personalizzato.
  • Estensione DevTools di reazione: utilizza un sottomodulo del renderer per riutilizzare l'interfaccia utente di DevTools. componenti.
  • Ember Inspector: core dell'estensione condivisa con adattatori per Chrome e Firefox.
  • Coquette-inspect: un'estensione pulita basata su React in cui è stato inserito un agente di debug nella pagina host.
  • Con le estensioni di esempio puoi trovare estensioni più utili da installare, provare e apprendere da cui proviene.

Ulteriori informazioni

Per informazioni sulle API standard che le estensioni possono utilizzare, visita la pagina 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 Campioni.