Informações gerais
Uma extensão do DevTools adiciona funcionalidade ao Chrome DevTools. Ele pode adicionar novos painéis de IU e barras laterais, interagir com a página inspecionada, receber informações sobre solicitações de rede e muito mais. Confira as extensões do DevTools em destaque. As extensões do DevTools têm acesso a um conjunto adicional de APIs de extensão específicas do DevTools:
Uma extensão do DevTools é estruturada como qualquer outra: ela pode ter uma página em segundo plano, scripts de conteúdo e outros itens. Além disso, cada extensão tem uma página, que tem acesso às APIs do DevTools.
Página do DevTools
Uma instância da página DevTools da extensão é criada sempre que uma janela dele é aberta. A página do DevTools existe durante o ciclo de vida da janela do DevTools. A página do DevTools tem acesso às APIs DevTools e a um conjunto limitado de APIs de extensão. Mais especificamente, a página do DevTools pode:
- Criar e interagir com painéis usando as APIs
devtools.panels. - Receba informações sobre a janela inspecionada e avalie o código nela usando as
APIs
devtools.inspectedWindow. - Receba informações sobre solicitações de rede usando as APIs
devtools.network.
A página do DevTools não pode usar a maioria das APIs de extensões diretamente. Ele tem acesso ao mesmo subconjunto
das APIs extension e runtime que pode ser acessado por um script de conteúdo. Como um script
de conteúdo, uma página do DevTools pode se comunicar com a página em segundo plano usando o envio de mensagens. Para ver um
exemplo, consulte Como injetar um script de conteúdo.
Como 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",
"minimum_chrome_version": "10.0",
"devtools_page": "devtools.html",
...
}
Uma instância do devtools_page especificada no manifesto da extensão é criada para cada janela do DevTools aberta. A página pode adicionar outras páginas de extensão como painéis e barras laterais à
janela do DevTools usando a API devtools.panels.
Os módulos da API chrome.devtools.* estão disponíveis apenas para as páginas carregadas na janela
do DevTools. Os scripts de conteúdo e outras páginas de extensão não têm essas APIs. Portanto, as APIs ficam
disponíveis somente durante o ciclo de vida da janela do DevTools.
Há também algumas APIs DevTools que ainda são experimentais. Consulte chrome.experimental.* APIs para a lista de APIs experimentais e diretrizes sobre como usá-las.
Elementos da interface do DevTools: painéis e da barra lateral
Além dos elementos usuais da interface da extensão, como ações do navegador, menus de contexto e pop-ups, uma extensão DevTools pode adicionar elementos de interface à janela do DevTools:
- Um painel é uma guia de nível superior, como os painéis "Elementos", "Fontes" e "Rede".
- Um painel da barra lateral apresenta a IU 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. Observe que a aparência dos painéis da barra lateral pode não corresponder à imagem, dependendo da versão do Chrome que você está usando e de onde a janela do DevTools está encaixada.
Cada painel é um arquivo HTML próprio, que pode incluir outros recursos (JavaScript, CSS, imagens etc.). A criação de um painel básico é assim:
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 da barra lateral tem acesso às mesmas APIs que a página do DevTools.
A criação de um painel básico da barra lateral para o painel Elementos é semelhante ao seguinte:
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 da barra lateral:
- Conteúdo HTML. Chame
setPagepara 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ão
As seções a seguir descrevem alguns cenários típicos de comunicação entre os diferentes componentes de uma extensão do DevTools.
Como injetar um script de conteúdo
A página do DevTools não pode chamar tabs.executeScript diretamente. Para injetar um script de conteúdo da
página do DevTools, você precisa extrair o ID da guia da janela inspecionada usando a propriedade
inspectedWindow.tabId e enviar uma mensagem para a página em segundo plano. Na página em segundo plano, chame tabs.executeScript para injetar o script.
Os snippets de código a seguir mostram como injetar um script de conteúdo usando 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"
});
Código da página de plano de fundo:
// 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);
});
});
Como avaliar o JavaScript na janela inspecionada
Use 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, painel ou painel da barra lateral do DevTools.
Por padrão, a expressão é avaliada no contexto do frame principal da página. Talvez você
já conheça os recursos da API da linha de comando do DevTools, como inspeção de elemento
(inspect(elem)), interrupção em funções (debug(fn)), cópia para a área de transferência (copy()) e muito mais.
inspectedWindow.eval() usa o mesmo contexto e opções de execução de script que o código digitado no console do DevTools, o que permite acesso a essas APIs na avaliação. Por exemplo, SOAK o utiliza
para inspecionar um elemento:
chrome.devtools.inspectedWindow.eval(
"inspect($$('head script[data-soak=main]')[0])",
function(result, isException) { }
);
Como alternativa, use a opção useContentScriptContext: true de inspectedWindow.eval() para
avaliar a expressão no mesmo contexto que os scripts de conteúdo. Chamar eval com
useContentScriptContext: true não cria um contexto de script de conteúdo. Portanto, é preciso carregar um
script de contexto antes de chamar eval, chamando executeScript ou especificando um script de
conteúdo no arquivo manifest.json.
Quando o contexto do script de contexto existir, é possível usar essa opção para injetar outros scripts de conteúdo.
O método eval é eficiente quando usado no contexto certo e perigoso quando usado
inadequadamente. Use o método tabs.executeScript se você não precisar de acesso ao
contexto JavaScript da página inspecionada. Para ver precauções detalhadas e uma comparação dos dois métodos,
consulte inspectedWindow.
Como transmitir o elemento selecionado para um script de conteúdo
O script de conteúdo não tem acesso direto ao elemento selecionado no momento. No entanto, qualquer código
executado usando o inspectedWindow.eval tem acesso ao console do DevTools e às APIs de linha de comando.
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:
- Crie um método no script de conteúdo que tenha o elemento selecionado como argumento.
- Chame o método na página do DevTools usando
inspectedWindow.evalcom a opçãouseContentScriptContext: true.
O código no seu script de conteúdo pode ser parecido com este:
function setSelectedElement(el) {
// do something with the selected element
}
Invoque o método na página do DevTools desta maneira:
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.
Como receber o window de um painel de referência
Para postMessage em um painel do DevTools, você precisará de uma referência ao objeto window.
Acesse a janela de iframe de um painel pelo manipulador de eventos panel.onShown:
onShown.addListener(function callback)
extensionPanel.onShown.addListener(function (extPanelWindow) {
extPanelWindow instanceof Window; // true
extPanelWindow.postMessage( // …
});
Mensagens de scripts de conteúdo para a página do DevTools
O envio de mensagens entre a página do DevTools e os scripts de conteúdo é indireto, por meio da página de segundo plano.
Ao enviar uma mensagem para um script de conteúdo, a página em segundo plano pode usar o
método tabs.sendMessage, que direciona uma mensagem para os scripts de conteúdo em uma guia específica,
como mostrado em Como injetar um script de conteúdo.
Ao enviar uma mensagem de um script de conteúdo, não há um método pronto para entregar uma mensagem à instância correta da página do DevTools associada à guia atual. Como solução alternativa, você pode fazer com que a página do DevTools estabeleça uma conexão de longa duração com a página em segundo plano e que ela mantenha um mapa de IDs de guia para as conexões, de modo que ela possa rotear cada mensagem para a conexão correta.
// 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;
});
A página do DevTools (ou painel ou painel da barra lateral) estabelece a conexão da seguinte maneira:
// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
name: "panel"
});
backgroundPageConnection.postMessage({
name: 'init',
tabId: chrome.devtools.inspectedWindow.tabId
});
Mensagens de scripts injetados para a página do DevTools
Embora a solução acima funcione para scripts de conteúdo, o código injetado diretamente na página
(por exemplo, anexando uma tag <script> ou usando inspectedWindow.eval) exige uma
estratégia diferente. Nesse contexto, runtime.sendMessage não transmitirá mensagens para o script em segundo plano como esperado.
Como solução alternativa, você pode combinar o script injetado com um script de conteúdo que atua como
intermediário. Para transmitir mensagens ao script de conteúdo, use a API
window.postMessage. Confira um exemplo, supondo que 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
if (typeof message !== 'object' || message === null ||
!message.source === 'my-devtools-extension') {
return;
}
chrome.runtime.sendMessage(message);
});
Sua mensagem agora fluirá do script injetado para o script de conteúdo, para o script de segundo plano e, finalmente, para a página do DevTools.
Considere também duas técnicas alternativas de transmissão de mensagens.
Como detectar quando o DevTools abre e fecha
Se a extensão precisar rastrear se a janela do DevTools está aberta, é possível adicionar um listener onConnect à página de segundo plano e chamar 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, é preciso contar os eventos de conexão e desconexão, conforme mostrado abaixo:
// 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 background page
var backgroundPageConnection = chrome.runtime.connect({
name: "devtools-page"
});
Exemplos de extensão do DevTools
Procure a origem destes exemplos de extensão do DevTools:
- 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 Blink para reutilizar componentes da interface do DevTools.
- Ember Inspector (em inglês): núcleo de extensão compartilhado com adaptadores para Chrome e Firefox.
- Coquette-inspect: uma extensão limpa baseada em React com um agente de depuração injetado na página do host.
- Na Galeria de extensões do DevTools e nas Extensões de exemplo, você encontra outros apps que valem a pena para instalar, testar e usar.
Mais informações
Para saber mais sobre as APIs padrão que as extensões podem usar, acesse 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 APIs DevTools em Samples.