Estender DevTools

As extensões do DevTools adicionam recursos ao Chrome DevTools acessando APIs de extensão específicas do DevTools usando uma página adicionada à extensão.

Diagrama de arquitetura que mostra a página do DevTools se comunicando com a janela inspecionada e o service worker. O service worker aparece se comunicando com os scripts de conteúdo e acessando APIs de extensão. A página do DevTools tem acesso às APIs do DevTools, por exemplo, para criar painéis.
Arquitetura de extensão do DevTools
.

As APIs de extensão específicas do DevTools incluem o seguinte:

Página do DevTools

Quando uma janela do DevTools é aberta, uma extensão cria uma instância da página do DevTools que existe desde que a janela esteja aberta. Esta página tem acesso às APIs DevTools e APIs de extensão e pode fazer o seguinte:

A página DevTools pode acessar diretamente as APIs de extensões. Isso inclui a capacidade de se comunicar com o service worker usando a transmissão de mensagens.

Criar uma extensão do DevTools

Para criar uma página do DevTools para sua extensão, adicione o campo devtools_page ao manifesto da extensão:

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

O campo devtools_page precisa apontar para uma página HTML. Como a página do DevTools precisa ser local para a extensão, recomendamos especificá-la usando um URL relativo.

Os membros da API chrome.devtools estão disponíveis apenas para as páginas carregadas na janela do DevTools enquanto ela está aberta. Os scripts de conteúdo e outras páginas de extensão não têm acesso a essas APIs.

Elementos da interface do DevTools: painéis e painéis da barra lateral

Além dos elementos comuns da interface da extensão, como ações do navegador, menus de contexto e pop-ups, uma extensão do DevTools pode adicionar elementos da interface à janela do DevTools:

  • Um painel é uma guia de nível superior, como os painéis "Elementos", "Origens" e "Rede".
  • Um painel da barra lateral apresenta a interface complementar relacionada a um painel. Os painéis "Estilos", "Estilos computados" e Listeners de eventos no painel "Elementos" são exemplos de painéis da barra lateral. Dependendo da versão do Chrome que você está usando e de onde a janela do DevTools está encaixada, os painéis da barra lateral podem se parecer com a seguinte imagem de exemplo:
Janela do DevTools mostrando o painel Elements e o painel da barra lateral Styles.
Janela do DevTools mostrando o painel "Elementos" e o painel da barra lateral "Estilos".

Cada painel é um arquivo HTML próprio, que pode incluir outros recursos (JavaScript, CSS, imagens etc.). Para criar um painel básico, use o seguinte código:

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

O JavaScript executado em um painel ou painel de barra lateral tem acesso às mesmas APIs da página do DevTools.

Para criar um painel básico de barra lateral, use o seguinte código:

chrome.devtools.panels.elements.createSidebarPane("My Sidebar",
    function(sidebar) {
        // sidebar initialization code here
        sidebar.setObject({ some_data: "Some data to show" });
});

Há várias maneiras de exibir conteúdo em um painel de barra lateral:

  • Conteúdo HTML: chame setPage() para especificar uma página HTML a ser exibida no painel.
  • Dados JSON: transmita um objeto JSON para setObject().
  • Expressão JavaScript: transmita uma expressão para setExpression(). O DevTools avalia a expressão no contexto da página inspecionada e exibe o valor de retorno.

Para setObject() e setExpression(), o painel exibe o valor como apareceria no console do DevTools. No entanto, setExpression() permite exibir elementos DOM e objetos JavaScript arbitrários, enquanto setObject() aceita apenas objetos JSON.

Comunicação entre componentes de extensões

As seções a seguir descrevem algumas maneiras úteis de permitir que os componentes de extensão do DevTools se comuniquem uns com os outros.

Injetar um script de conteúdo

Para injetar um script de conteúdo, use scripting.executeScript():

// DevTools page -- devtools.js
chrome.scripting.executeScript({
  target: {
    tabId: chrome.devtools.inspectedWindow.tabId
  },
  files: ["content_script.js"]
});

É possível recuperar o ID da guia da janela inspecionada usando a propriedade inspectedWindow.tabId.

Se um script de conteúdo já tiver sido injetado, use APIs de mensagens para se comunicar com ele.

Avaliar o JavaScript na janela inspecionada

Você pode usar o método inspectedWindow.eval() para executar o código JavaScript no contexto da página inspecionada. É possível invocar o método eval() em uma página, um painel ou um painel da barra lateral do DevTools.

Por padrão, a expressão é avaliada no contexto do frame principal da página. inspectedWindow.eval() usa o mesmo contexto e opções de execução de script que o código inserido no console do DevTools, o que permite acesso aos recursos da API Console Assets do DevTools ao usar eval(). Por exemplo, SOAK usa essa classe para inspecionar um elemento:

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

Também é possível definir useContentScriptContext como true ao chamar inspectedWindow.eval() para avaliar a expressão no mesmo contexto que os scripts de conteúdo. Para usar essa opção, utilize uma declaração de script de conteúdo estático antes de chamar eval(), chamando executeScript() ou especificando um script de conteúdo no arquivo manifest.json. Depois que o contexto do script de contexto for carregado, também será possível usar essa opção para injetar outros scripts de conteúdo.

Transmitir o elemento selecionado para um script de conteúdo

O script de conteúdo não tem acesso direto ao elemento selecionado. No entanto, qualquer código executado usando inspectedWindow.eval() tem acesso ao console do DevTools e às APIs Console Assets. Por exemplo, no código avaliado, é possível usar $0 para acessar o elemento selecionado.

Para transmitir o elemento selecionado para um script de conteúdo:

  1. Crie um método no script de conteúdo que use o elemento selecionado como argumento.

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

  2. Chame o método da página do DevTools usando inspectedWindow.eval() com a opção useContentScriptContext: true.

    chrome.devtools.inspectedWindow.eval("setSelectedElement($0)",
    { useContentScriptContext: true });

A opção useContentScriptContext: true especifica que a expressão precisa ser avaliada no mesmo contexto que os scripts de conteúdo, para que ela possa acessar o método setSelectedElement.

Acessar o window do painel de referência

Para chamar postMessage() em um painel do DevTools, você vai precisar de uma referência ao objeto window. Recupere a janela de iframe de um painel pelo manipulador de eventos panel.onShown:

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

Enviar mensagens de scripts injetados para a página do DevTools

O código injetado diretamente na página sem um script de conteúdo, inclusive anexando uma tag <script> ou chamando inspectedWindow.eval(), não pode enviar mensagens para a página do DevTools usando runtime.sendMessage(). Em vez disso, recomendamos combinar o script injetado com um script de conteúdo que possa atuar como intermediário e usar o método window.postMessage(). O exemplo a seguir usa o script de segundo plano da seção anterior:

// 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);
});

Outras técnicas alternativas de transmissão de mensagens podem ser encontradas no GitHub (link em inglês).

Detectar quando o DevTools abre e fecha

Para rastrear se a janela do DevTools está aberta, adicione um listener onConnect ao service worker e chame connect() na página do DevTools. Como cada guia pode ter a própria janela do DevTools aberta, você pode receber vários eventos de conexão. Para rastrear se alguma janela do DevTools está aberta, conte os eventos de conexão e desconexão, conforme mostrado neste exemplo:

// 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.");
          }
      });
    }
});

A página do DevTools cria uma conexão como esta:

// 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);

Exemplos de extensão do DevTools

Os exemplos nesta página são provenientes das seguintes páginas:

  • Extensão Polymer Devtools: usa vários auxiliares em execução na página do host para consultar o estado DOM/JS e enviar de volta ao painel personalizado.
  • Extensão React DevTools: usa um submódulo do renderizador para reutilizar os componentes da interface do DevTools.
  • Ember Inspector: núcleo de extensão compartilhado com adaptadores para o Chrome e o Firefox.
  • Coquette-inspect: uma extensão limpa baseada em React com um agente de depuração injetado na página do host.
  • As extensões de exemplo têm extensões mais úteis para instalar, testar e aprender.

Mais informações

Para mais informações sobre as APIs padrão que as extensões podem usar, consulte chrome.* APIs e APIs da Web.

Envie seu feedback. Seus comentários e sugestões nos ajudam a melhorar as APIs.

Exemplos

Confira exemplos que usam as APIs DevTools em Amostras.