As extensões do DevTools adicionam recursos ao Chrome DevTools acessando-as específicas APIs de extensão por uma página do DevTools adicionada à extensão.
![Diagrama de arquitetura mostrando a página do DevTools se comunicando com o
a janela inspecionada e o service worker. O service worker é mostrado
comunicação com scripts de conteúdo e acesso a APIs de extensão.
A página do DevTools tem acesso às APIs do DevTools, por exemplo, ao criar painéis.](https://developer.chrome.com/static/docs/extensions/how-to/devtools/extend-devtools/image/architecture-diagram.png?authuser=6&hl=pt-br)
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 do DevTools cria uma instância da página correspondente que existe enquanto a janela está aberta. Esta página tem acesso às APIs do DevTools e às APIs de extensão e pode fazer o seguinte:
- Crie e interaja com painéis usando as APIs
devtools.panels
, incluindo a adição de outras páginas de extensão como painéis ou barras laterais à janela do DevTools. - Receba informações sobre a janela inspecionada e avalie o código na janela inspecionada usando o
devtools.inspectedWindow
APIs. - Receba informações sobre solicitações de rede usando as APIs
devtools.network
. - Estenda o painel Gravador usando as APIs
devtools.recorder
. - Receba informações sobre o status da gravação do painel Performance usando as APIs
devtools.performance
.
A página do DevTools pode acessar diretamente as APIs de extensões. Isso inclui ser capaz se comunicar com o service worker usando 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
à extensão.
manifesto do app:
{
"name": ...
"version": "1.0",
"devtools_page": "devtools.html",
...
}
O campo devtools_page
precisa apontar para uma página HTML. Como o DevTools
deve ser local à sua 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 no DevTools
janela 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 de interface de extensão usuais, como ações do navegador, menus de contexto e pop-ups, uma A 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 estilos, estilos computados e Os painéis de Listeners de eventos no painel Elementos são exemplos de painéis de barra lateral. Dependendo versão do Chrome que está usando e onde a janela DevTools está ancorada, os painéis da barra lateral podem é parecida com esta imagem de exemplo:
![Janela do DevTools mostrando os painéis Elements e Styles da barra lateral.](https://developer.chrome.com/static/docs/extensions/how-to/devtools/extend-devtools/image/devtools-window-showing-e-9051f7f0347cd.png?authuser=6&hl=pt-br)
Cada painel é um arquivo HTML próprio, que pode incluir outros recursos (JavaScript, CSS, imagens e muito 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 que a página 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()
. 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 ele apareceria no
Console do DevTools. No entanto, setExpression()
permite exibir elementos DOM e JavaScript arbitrário.
objetos, enquanto setObject()
oferece suporte apenas a objetos JSON.
Comunicar entre componentes de extensão
As seções a seguir descrevem algumas maneiras úteis de permitir que os componentes de extensão do DevTools se comuniquem umas com as outras.
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 o método
propriedade inspectedWindow.tabId
.
Se um script de conteúdo já tiver sido injetado, você pode usar APIs de mensagens para se comunicar com ele.
Avaliar o JavaScript na janela inspecionada
Você pode usar o método inspectedWindow.eval()
para executar JavaScript.
no contexto da página inspecionada. Você pode invocar o método eval()
de uma página do DevTools,
ou no painel da barra lateral.
Por padrão, a expressão é avaliada no contexto do frame principal da página.
O inspectedWindow.eval()
usa o mesmo contexto e opções de execução de script que o código.
inserido no console do DevTools, que permite o acesso aos Utilitários do console do DevTools
API ao usar eval()
. Por exemplo, SOAK o usa para inspecionar um elemento:
chrome.devtools.inspectedWindow.eval(
"inspect($$('head script[data-soak=main]')[0])",
function(result, isException) { }
);
Você também pode 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, use uma declaração de script de conteúdo estático antes de chamar eval()
, chamando executeScript()
ou especificando um objeto
script no arquivo manifest.json
. Depois que o contexto do script de contexto for carregado, também será possível usar essa opção para
inserir scripts de conteúdo adicionais.
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 que você
executar usando inspectedWindow.eval()
tem acesso ao DevTools
console e APIs Console Utilitários. Por exemplo, no código avaliado, é possível usar $0
para acessar
elemento selecionado.
Para transmitir o elemento selecionado a um script de conteúdo:
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 }
Chame o método na página do DevTools usando
inspectedWindow.eval()
. com a opçãouseContentScriptContext: 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 ele possa acessar o método setSelectedElement
.
Receber o window
de um painel de referência
Para chamar postMessage()
em um painel do DevTools, é necessário ter uma referência ao objeto window
dele. Receba um
janela de iframe do painel no 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
Código injetado diretamente na página sem um script de conteúdo, incluindo a anexação de um <script>
ou chamando inspectedWindow.eval()
, não é possível enviar mensagens para o
página do DevTools usando runtime.sendMessage()
. Em vez disso, recomendamos
combinar o script injetado com um script de conteúdo que pode 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. Devido ao cada guia pode ter sua própria janela 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 no exemplo a seguir:
// 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 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:
- Polymer Devtools Extension (em inglês): usa muitos auxiliares em execução na página do host para fazer consultas. Estado DOM/JS para enviar de volta ao painel personalizado.
- Extensão React DevTools: usa um submódulo do renderizador para reutilizar a interface do DevTools componentes de solução.
- 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 de hospedagem.
- As extensões de exemplo têm outras extensões interessantes para instalar, testar e aprender. se originou.
Mais informações
Para mais informações sobre as APIs padrão que as extensões podem usar, consulte chrome.* APIs e Web APIs.
Envie seu feedback. Seus comentários e sugestões nos ajudam a melhorar as APIs.
Exemplos
Confira exemplos que usam as APIs do DevTools em Amostras (link em inglês).