Criar uma extensão que personaliza a IU do DevTools

Artigo
07/16/2024

Este tutorial mostra como criar a sua própria extensão DevTools do zero. É uma boa forma de experimentar tudo o que é necessário para o desenvolvimento típico. No final do tutorial, terá uma extensão de trabalho que cria o seu próprio painel e interage com as APIs de DevTools.

Primeiro, reveja os pré-requisitos. Em seguida, transfira e execute a extensão final a partir da secção Solução para ver o que vai criar neste tutorial. Caso contrário, comece no Passo 1 - Crie uma Extensão DevTools Básica para criar a extensão do zero.

Pré-requisitos

Microsoft Edge Browser para executar a extensão.
Um editor de código, como o Visual Studio Code , para acompanhar o tutorial.

Solução

Nesta secção, vai transferir e executar o estado final da extensão que o resto deste tutorial lhe irá ensinar a criar. Mais tarde, irá começar do zero e aprender a escrever o código para criar a sua própria extensão.

Obtenha o código final da extensão ao transferir este ficheiro zip e extrair o respetivo conteúdo para uma pasta no seu computador.
Abra o Microsoft Edge e aceda a edge://extensions/.
Ative o botão de alternar Modo de programador .
Clique em Carregar desempacotado e navegue para a pasta onde extraiu o ficheiro zip. Nesta pasta, selecione Demos-main>devtools-extension sample>4 e, em seguida, clique em Selecionar Pasta.

A página edge://extensions no Microsoft Edge a mostrar os botões Modo de programador e Carregar desempacotado

A extensão DevTools deverá agora ser carregada. Abra um novo separador no Microsoft Edge e, em seguida, abra DevTools ao premir F12.

A extensão cria um separador Painel de Exemplo na janela DevTools:

Microsoft Edge, a mostrar DevTools na parte lateral, com o Painel de Exemplo da extensão selecionado

Passo 1 – Criar uma extensão básica de DevTools

Uma extensão básica de DevTools consiste em dois ficheiros, conforme mostrado no código do Passo 1:

Um ficheiro de manifesto.

{
    "name": "DevTools Sample Extension",
    "description": "A Basic DevTools Extension",
    "manifest_version": 3,
    "version": "1.0",
    "devtools_page": "devtools.html"
}

Propriedade	Descrição
nome	O nome da extensão que será apresentada em `edge://extensions/`.
description	A descrição da extensão que será apresentada sob o nome da extensão.
versão	A versão da extensão que será apresentada junto ao nome da extensão.
manifest_version	Determina o conjunto de funcionalidades que a extensão irá utilizar, como funções de trabalho de serviço ou modificação de pedidos de rede. A versão atual é a versão `3`. Para saber mais sobre esta versão e as diferenças com a versão , veja Descrição geral e linhas cronológicas para migrar para o Manifesto V3.`2`
devtools_page	O caminho para um ficheiro HTML que será executado sempre que a IU do DevTools for aberta. Embora a página não seja composta em DevTools, será utilizada para carregar os ficheiros JavaScript necessários para a extensão.

Um ficheiro html para corresponder ao devtools_page campo no ficheiro de manifesto.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    A Basic DevTools Extension.
  </body>
</html>

Para carregar e testar a extensão DevTools no Microsoft Edge, utilize o Modo de programador:

No Microsoft Edge, aceda a edge://extensions/.
Ative o botão de alternar Modo de programador .
Clique em Carregar desempacotado, navegue para a pasta onde escreveu o código para a sua extensão e clique em Selecionar pasta.

A extensão DevTools está agora carregada. Abra um novo separador e, em seguida, abra DevTools (F12).

A extensão está carregada, mas ainda não é apresentada nas DevTools, porque ainda não criou um painel para a extensão.

Passo 2 – Adicionar um painel DevTools

Neste passo, irá criar um novo painel no DevTools. Pode encontrar o código para este passo no código do Passo 2 ou escrevê-lo manualmente ao seguir as instruções abaixo.

Um painel é um separador na barra de ferramentas principal em DevTools, semelhante às ferramentas Elementos, Consola e Origens mostradas abaixo:

Painéis e barras laterais de DevTools

Neste passo, vamos criar uma extensão de DevTools básica com um painel de exemplo.

Crie um devtools.js ficheiro com o seguinte código:
```
chrome.devtools.panels.create("Sample Panel", "icon.png", "panel.html", panel => {
    // code invoked on panel creation
});
```
O create método requer quatro parâmetros: title, iconpath, pagePathe uma função de chamada de retorno. Tenha em atenção que, embora o ícone do painel seja um parâmetro obrigatório, não é apresentado atualmente nas DevTools do Microsoft Edge.

Para saber mais sobre a chrome.devtools.panels API de extensão, veja chrome.devtools.panels API reference (Referência da API chrome.devtools.panels).
Carregue o ficheiro a partir da página HTML especificada no campo de devtools_page manifesto anteriormente (o devtools.html ficheiro), ao adicionar um script elemento no código fonte.
```
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <script src="devtools.js"></script>
  </body>
</html>
```
Crie o panel.html ficheiro que referiu na chamada de método anterior chrome.devtools.panels.create . Esta página Web irá conter a interface de utilizador do painel que a sua extensão está a adicionar às DevTools.
```
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <h1>A Basic DevTools Extension with Panel</h1>
  </body>
</html>
```

Para testar as suas alterações no Microsoft Edge, recarregue a extensão a edge://extensions/ partir da página:

Navegue (ou volte) para a edge://extensions/ página.
Localize a entrada de extensão desembalada que carregou no passo 1.
Clique em Recarregar.

A extensão DevTools deverá agora ser recarregada. Abra um novo separador no Microsoft Edge e, em seguida, abra DevTools (F12). O painel de extensões DevTools deve ser apresentado em DevTools:

Microsoft Edge, com DevTools na parte lateral, a mostrar o novo painel de extensões

Passo 3 – Chamar APIs de extensão a partir de uma extensão DevTools

Neste passo, irá utilizar as APIs de extensão para apresentar informações de memória no painel DevTools. Para tal, teremos de atualizar o permissions no ficheiro de manifesto, na interface do painel e no script de devtools. O código fonte para este passo pode ser encontrado no código do Passo 3 ou escrevê-lo manualmente ao seguir as instruções abaixo.

Utilize o membro do permissions manifesto no seu manifest.json ficheiro. Este membro define as permissões que a sua extensão necessita do utilizador. Algumas permissões são necessárias para utilizar determinadas APIs de extensão.
```
"permissions": [
  "system.memory",
]
```
A system-memory permissão é necessária para utilizar as APIs de extensão que utilizaremos mais adiante neste tutorial. Para saber mais sobre as APIs disponíveis e as permissões associadas, veja a Referência da API.

Adicione o seguinte ao corpo do panel.html ficheiro para apresentar os dados no painel.

<div>
  Available Memory Capacity: <span id="availableMemoryCapacity"></span>
</div>
<div>
  Total Memory Capacity: <span id="totalMemoryCapacity"></span>
</div>

Atualize o devtools.js ficheiro com o seguinte código.

let availableMemoryCapacity;
let totalMemoryCapacity;

chrome.devtools.panels.create("Sample Panel", "icon.png", "panel.html", panel => {
    // code invoked on panel creation
    panel.onShown.addListener((extPanelWindow) => {
        availableMemoryCapacity = extPanelWindow.document.querySelector('#availableMemoryCapacity');
        totalMemoryCapacity = extPanelWindow.document.querySelector('#totalMemoryCapacity');
    });
});

setInterval(() => {
    chrome.system.memory.getInfo((data) => {
        if (availableMemoryCapacity) {
            availableMemoryCapacity.innerHTML = data.availableCapacity;
        }
        if (totalMemoryCapacity) {
            totalMemoryCapacity.innerHTML = data.capacity;
        }
    });
}, 1000);

O fragmento de código acima faz o seguinte:

Cria um novo painel Sample Panel no DevTools.
Quando o painel é apresentado (panel.onShown serviço de escuta), os availableMemoryCapacity elementos e totalMemoryCapacity são obtidos a partir do DOM.
Em seguida, é definido um temporizador para executar o código a cada segundo depois de o painel ser apresentado.
Quando o temporizador é acionado, o chrome.system.memory.getInfo método é utilizado para obter a capacidade de memória total e disponível do dispositivo e estes valores são apresentados nos elementos DOM correspondentes.

Para testar as suas alterações no Microsoft Edge, recarregue a extensão a edge://extensions/ partir da página:

Navegue (ou volte) para a edge://extensions/ página.
Localize a entrada de extensão desembalada que carregou no passo 1.
Clique em Recarregar.

A extensão DevTools deverá agora ser recarregada. Abra um novo separador e, em seguida, abra DevTools (F12). O painel de extensões DevTools deverá agora mostrar as capacidades de memória disponíveis e totais.

O novo painel de extensões no DevTools a mostrar informações de memória

Pode encontrar mais APIs de extensão na página Referência da API .

Passo 4 – Interagir com a página Web inspecionada

Neste passo do tutorial, irá adicionar código que interage com a página Web inspecionada. Esse código irá:

Ouça os eventos que ocorrem na página Web e inicie sessão na ferramenta Consola de DevTools.
Mostrar a posição de clique do rato no painel de extensão DevTools.
Mostrar um alerta de saudação na página inspecionada quando o utilizador clica num botão no painel de extensão DevTools.

O código fonte para este passo pode ser encontrado no código do Passo 4 ou escrevê-lo manualmente ao seguir as instruções abaixo.

Infelizmente, o painel DevTools que acabou de criar não tem acesso direto à página Web inspecionada e não é executado até que o DevTools seja aberto. Para tal, irá utilizar um script de conteúdo e uma função de trabalho de serviço em segundo plano.

Um script de conteúdo é executado no contexto da página Web inspecionada e, da mesma forma que outros scripts são carregados pela página, têm acesso ao DOM e podem alterá-lo.
Uma função de trabalho de serviço em segundo plano é um script que o browser executa num thread separado e tem acesso às APIs de extensão.

O diagrama seguinte fornece uma descrição geral de como a página DevTools, a página inspecionada, o script de conteúdo e a função de trabalho de serviço em segundo plano se encaixam numa extensão.

A anatomia de uma extensão DevTools

Nesta parte do tutorial, irá detetar que o utilizador clica numa página Web com um script de conteúdo. O script de conteúdo irá reencaminhar estas informações para o devtools.js ficheiro onde os dados serão apresentados na consola do e no painel de extensão DevTools.

Acrescente o seguinte ao manifest.json ficheiro

"content_scripts": [{
  "matches": [
    "http://*/*",
    "https://*/*"
  ],
  "run_at": "document_idle",
  "js": [
    "content_script.js"
  ]
}],
"background": {
    "service_worker": "background.js"
}

Propriedade	Valor
correspondências	Especifica em que páginas este script de conteúdo será injetado.
run_at	Indica quando o browser injeta o script na página.
js	Os ficheiros javascript a serem injetados.

Crie o ficheiro content_script.js com o seguinte conteúdo:
```
document.addEventListener("click", (event) => {
  chrome.runtime.sendMessage({
      click: true,
      xPosition: event.clientX + document.body.scrollLeft,
      yPosition: event.clientY + document.body.scrollTop
    },
    response => {
      console.log("Received response", response);
    }
  );
});
```
O fragmento de código acima imprime uma mensagem na consola quando o script é injetado na página. Também adiciona um serviço de escuta de eventos de clique à página que enviará uma mensagem com a posição de clique do rato na página inspecionada com a chrome.runtime.sendMessage API.
panel.html No ficheiro, adicione um sayHello botão e uma youClickedOn etiqueta . Estes dois elementos são utilizados para despromover a interação entre a página inspecionada, o painel DevTools e a função de trabalho de serviço em segundo plano. Quando o utilizador clica no sayHello botão na extensão DevTools, apresenta uma mensagem de saudação na janela inspecionada. Quando o utilizador clica em qualquer parte da página inspecionada, apresenta uma mensagem para mostrar a posição do clique do rato no painel da extensão DevTools.
```
<button id="sayHello">Say Hello to the inspected page!</button>
<h2><span id="youClickedOn"></span></h2>
```

devtools.js No ficheiro, utilize o chrome.runtime.connect método para criar uma ligação à função de trabalho de serviço em segundo plano e, em seguida, envie a janela tabId inspecionada para a função de trabalho de serviço com o backgroundPageConnection.postMessage método . Por fim, adicione serviços de escuta de eventos ao sayHello botão e youClickedOn etiqueta definidos no panel.html ficheiro.

let youClickedOn; 
chrome.devtools.panels.create("Sample Panel", "icon.png", "panel.html", panel => {
    // code invoked on panel creation
    panel.onShown.addListener( (extPanelWindow) => {
        let sayHello = extPanelWindow.document.querySelector('#sayHello');
        youClickedOn = extPanelWindow.document.querySelector('#youClickedOn');
        sayHello.addEventListener("click", () => {
            // show a greeting alert in the inspected page
            chrome.devtools.inspectedWindow.eval('alert("Hello from the DevTools extension");');
        });             
    });
});

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
    // Messages from content scripts should have sender.tab set
    if (sender.tab && request.click == true) {
        console.log('I am here!');
        if (youClickedOn) {
            youClickedOn.innerHTML = `You clicked on position (${request.xPosition}, ${request.yPosition}) in the inspected page.`;
        }
        sendResponse({
            xPosition: request.xPosition,
            yPosition: request.yPosition
        });
    }
});

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

// Relay the tab ID to the background service worker
backgroundPageConnection.postMessage({
    name: 'init',
    tabId: chrome.devtools.inspectedWindow.tabId
});

Quando o utilizador clica no sayHello botão, a extensão DevTools executará um fragmento de código na alert("Hello from the DevTools Extension"); janela inspecionada ao invocar o eval() método da janela chrome.devtools.inspectedWindowinspecionada.

Quando o utilizador clica em qualquer parte da janela inspecionada, a extensão DevTools receberá uma mensagem, da função de trabalho de serviço em segundo plano, com request.click == true e as informações de posição do rato.

Crie o background.js ficheiro e adicione o seguinte código ao mesmo:

let id = null;
const connections = {};

chrome.runtime.onConnect.addListener(devToolsConnection => {
    // Assign the listener function to a variable so we can remove it later
    let devToolsListener = (message, sender, sendResponse) => {
        if (message.name == "init") {
            id = message.tabId;
            connections[id] = devToolsConnection;
            // Send a message back to DevTools
            connections[id].postMessage("Connected!");
        }
    };

    // Listen to messages sent from the DevTools page
    devToolsConnection.onMessage.addListener(devToolsListener);

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

O fragmento de código acima liga a função de trabalho de serviço em segundo plano à página DevTools. Ouve quando a página DevTools se liga, guarda a ligação e envia uma resposta de volta para a página DevTools.

Isto é útil quando a sua função de trabalho de serviço em segundo plano está a recolher dados ou a realizar tarefas em segundo plano que pretende que estejam disponíveis na extensão DevTools.

Para testar o novo sayHello botão:

Saiba mais em edge://extensions/.
Localize a entrada de extensão desembalada que carregou no Passo 1.
Clique no botão Recarregar .
Abra um novo separador do browser, abra DevTools (F12) e clique no separador Painel de Exemplo .
Clique no "Say Hello to The Inspected Page!" botão no seu painel. Deverá ver um alerta na página inspecionada, conforme mostrado abaixo.

Para saber mais sobre scripts de conteúdo, veja a documentação Scripts de Conteúdo.

Para testar a youClickedOn etiqueta:

Clique em OK para fechar a janela de alerta aberta no passo anterior.
Clique em qualquer parte da página inspecionada. A Clicou na posição (x,y) na mensagem de página inspecionada deve aparecer no painel de extensão.
Abra a ferramenta Consola . Também deve ser apresentada uma mensagem semelhante ao passo anterior na ferramenta Consola .

Compartilhar via