Exemplo: Inseridor de imagem usando script de conteúdo

Este exemplo usa código JavaScript para inserir a stars.jpeg imagem na parte superior da página da Web atual, dentro do <body> elemento. O pop-up da extensão contém um título e um botão HTML rotulado como Inserir imagem. Quando você clica no botão Inserir imagem , o código JavaScript da extensão envia uma mensagem do pop-up do ícone da extensão e insere dinamicamente o JavaScript que é executado na guia do navegador.

Este exemplo demonstra os seguintes recursos de extensão:

  • Injetando bibliotecas JavaScript em uma extensão.
  • Expor ativos de extensão a guias do navegador.
  • Incluir páginas da Web de conteúdo nas guias existentes do navegador.
  • Fazer com que as páginas da Web de conteúdo ouçam mensagens de pop-ups e respondam.

Visualização do exemplo

Você instalará o exemplo de extensão usando a guia Gerenciar Extensões do navegador, clicará no botão Extensões (ícone Extensões) para mostrar a lista de extensões instaladas e, em seguida, clicará nesta extensão de exemplo:

Clicar no ícone da extensão para abri-la

A extensão exibe uma pequena página da Web HTML em um pop-up, contendo um título, um botão Inserir imagem e instruções:

popup.html exibição após selecionar o ícone de extensão

Quando você clica no botão Inserir Imagem , o código JavaScript é stars.jpeg inserido temporariamente na parte superior da página da Web atual, empurrando o conteúdo da página da Web para abaixo da imagem. O conteúdo injetado define o elemento image para exibir a imagem stars.jpeg estática na parte superior da página da Web atual:

A imagem que aparece no navegador

Quando você clica na imagem, o JavaScript injetado remove a imagem da árvore DOM e da página da Web.

Obtenha, instale e execute o exemplo da seguinte maneira.

Clonar o repositório MicrosoftEdge-Extensions

Você pode usar várias ferramentas para clonar um repositório do GitHub. Você pode baixar um diretório selecionado ou clonar o repositório inteiro.

Clone o repositório MicrosoftEdge-Extensions em sua unidade local e, em seguida, alterne para um branch de trabalho, da seguinte maneira.

  1. Em um prompt de comando, insira git para marcar se o git está instalado.

  2. Se ainda não terminou, baixe o git e instale-o.

  3. Se ainda não tiver terminado, inicie um prompt de comando onde o git está instalado.

  4. Altere para o diretório no qual você deseja clonar o repositório MicrosoftEdge-Extensions . Por exemplo:

    cd C:/Users/localAccount/GitHub/

  5. No Microsoft Edge, vá para o repositório MicrosoftEdge-Extensions .

  6. Clique na seta para baixo no lado direito do botão Código verde e, em seguida, na seção Clonar usando a URL da Web , clique no botão Copiar URL para a área de transferência ao lado https://github.com/microsoft/MicrosoftEdge-Extensions.gitde .

  7. Na janela do prompt de comando, digite o comando:

    git clone https://github.com/microsoft/MicrosoftEdge-Extensions.git

    O /MicrosoftEdge-Extensions/ diretório é adicionado dentro do diretório especificado.

Criar um branch de trabalho e alternar para ele

  1. Verifique a lista de diretórios:

    ls

    O /MicrosoftEdge-Extensions/ diretório está listado.

  2. Mude para o novo diretório:

    cd MicrosoftEdge-Extensions

  3. Criar um branch de trabalho:

    git branch test

  4. Alternar para o branch de trabalho:

    git switch test

    Devoluções: Switched to branch 'test'

Agora você está livre para modificar o código em seu branch de trabalho, sem alterar o código que está no branch "main" do repositório. Mais tarde, você pode querer voltar para a ramificação "main" ou criar uma ramificação diferente com base na ramificação "main".

Instalar o exemplo localmente (sideload)

Em vez de instalar o exemplo de Complementos do Microsoft Edge, você instalará o exemplo localmente, para que possa modificá-lo e testar rapidamente as alterações. Instalar localmente às vezes é chamado de sideload de uma extensão.

  1. No Microsoft Edge, clique no botão Extensões (ícone de Extensões), ao lado da barra de endereços, se esse ícone for exibido. Ou selecione Configurações e mais (o ícone> "Configurações e mais") Ícone de extensõesExtensões. O pop-up de extensões é aberto:

    O pop-up de Extensões quando nenhuma extensão está instalada

  2. Clique em Gerenciar extensões. A página Gerenciamento de extensões é aberta em uma nova guia:

    Ativando o modo de desenvolvedor

  3. Ative a alternância do modo Desenvolvedor .

  4. Ao instalar a extensão de exemplo pela primeira vez, clique no botão Carregar descompactado (o ícone A caixa de diálogo Selecionar o diretório de extensão é aberta.

  5. Selecione o diretório que contém os arquivos de origem da extensão, como manifest.json.

    Caminho de exemplo:

    C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

  6. Clique no botão Selecionar Pasta .

    A caixa de diálogo Selecionar o diretório de extensão é aberta.

    A extensão é instalada no navegador, semelhante a uma extensão instalada a partir de complementos do Microsoft Edge:

    Página de extensões instaladas, mostrando uma extensão de sideload

Executar o exemplo

  1. Acesse uma página da Web, como o aplicativo TODO, em uma nova janela ou guia. A guia não deve estar vazia e não deve ser a página Gerenciar Extensões, pois este exemplo insere o conteúdo na página da Web atual.

  2. Atualize a página da Web. Às vezes, isso é necessário após recarregar uma extensão.

  3. No Microsoft Edge, à direita da barra de endereços, se esse ícone for exibido, clique no botão Extensões (ícone de Extensões). Ou selecione Configurações e mais (o ícone> "Configurações e mais") Extensões.

    O pop-up de extensões é aberto:

    Clicar no ícone da extensão para abri-la

  4. Clique no ícone ou no nome da extensão (Inseridor de imagem usando script de conteúdo).

    A extensão é aberta e o ícone da extensão é adicionado ao lado da barra de endereços e do ícone de Extensões (ícone de Extensões).

    Um pop-up é aberto, contendo uma pequena página da web HTML com um título, um botão Inserir imagem e instruções:

    popup.html depois de clicar no ícone da extensão

  5. Clique no botão Inserir Imagem . stars.jpeg é inserido na parte superior da página da web atual na guia atual, empurrando o conteúdo da página da Web para baixo da imagem:

    A imagem que aparece no navegador

  6. Clique na stars.jpeg imagem que preenche a parte superior da página da Web. Esse elemento de imagem é removido da árvore DOM e da página da Web, e a página da Web atual é restaurada, deslocando seu conteúdo de volta para o topo da guia.

A extensão envia uma mensagem do pop-up do ícone da extensão e insere dinamicamente o JavaScript em execução como conteúdo na guia do navegador. O conteúdo injetado define o elemento de imagem a ser exibido stars.jpeg na parte superior da página da Web atual e, em seguida, remove a imagem quando você clica na imagem.

Veja também:

Estude a amostra

Nas seções a seguir, você estudará a amostra. Depois disso, para desenvolver sua própria extensão do Microsoft Edge, você pode copiar e modificar o diretório do exemplo e instalar e testar a extensão resultante.

Files e diretórios

O exemplo tem a seguinte estrutura de diretórios e arquivos.

Exemplo de caminho para o exemplo:

C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

Diretórios e arquivos no /picture-inserter-content-script/ diretório:

/content-scripts/
   content.js
/icons/
   extension-icon16x16.png
   extension-icon32x32.png
   extension-icon48x48.png
   extension-icon128x128.png
/images/
   stars.jpeg
/popup/
   popup.html
   popup.js
manifest.json
  • O /content-scripts/ diretório contém content.js, que é o script injetado na página da Web atual.
  • O /icons/ diretório contém versões de um .png arquivo usado para representar a extensão perto da barra de endereços do navegador, no pop-up Extensões e na página Gerenciamento de extensões .
  • O /images/ diretório contém stars.jpeg, que é exibido no pop-up da extensão.
  • O /popup/ diretório contém os arquivos:
    • popup.html Define o conteúdo na página da Web pop-up inicial da extensão (um título, um botão e instruções).
    • popup.js Para a página da Web pop-up inicial, envia uma mensagem para o script de conteúdo (content.js) que está em execução na página da guia, especificando qual arquivo de imagem exibir.
  • manifest.json Contém informações básicas sobre a extensão.

Estratégia para atualizar a página da Web para inserir a imagem na parte superior (stars.jpeg)

Este exemplo inclui um script de conteúdo injetado na página da Web carregada na guia atual do navegador.

  1. Quando você executa o exemplo de extensão, a página HTML pop-up inicial é exibida (popup.html), mostrando um título, instruções e o botão Inserir Imagem .

  2. Quando você clica no botão Inserir imagem , o JavaScript (popup.js) da página pop-up inicial envia uma mensagem para o script de conteúdo (content.js) que está em execução na página da guia. A mensagem especifica qual arquivo de imagem deve ser exibido.

  3. O script de conteúdo (content.js) em execução na página da guia recebe a mensagem e exibe o arquivo de imagem especificado (stars.jpeg).

A página da Web pop-up inicial (popup.html)

/popup/popup.html é especificado no arquivo de manifesto como a página da Web a ser exibida no pop-up inicial da extensão. O arquivo de manifesto contém o campo "default_popup": "popup/popup.html"de chave . O arquivo deste popup.html exemplo é uma pequena página da Web que contém um título, um botão Inserir imagem e instruções.

popup.html:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <style>
            body {
                width: 500px;
            }
            button {
                background-color: #336dab;
                border: none;
                color: white;
                padding: 15px 32px;
                text-align: center;
                font-size: 16px;
            }
        </style>
    </head>
    <body>
        <h1>Picture inserter using a content script</h1>
        <button id="sendmessageid">Insert picture</button>
        <script src="popup.js"></script>
        <p>Click the displayed image to remove it from the webpage.</p>
    </body>
</html>

JavaScript (popup.js) para a página pop-up inicial, para enviar uma mensagem para o JavaScript injetado

/popup/popup.js Envia uma mensagem para o script de conteúdo (content.js) que é temporariamente injetado na guia do navegador. Para fazer isso, popup.js adiciona um onclick evento ao botão Inserir imagem da página pop-up, que tem a ID sendmessageid:

popup.js (parte):

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        ...
    };
}

Em popup.js, chrome.tabs.query localiza a guia atual do navegador e chrome.tabs.sendMessage envia uma mensagem para essa guia. O exemplo passa na ID da guia atual. A mensagem deve incluir a URL da imagem que será exibida.

Você deve enviar uma ID exclusiva para atribuir à imagem inserida, a fim de localizar o elemento de imagem novamente mais tarde e excluí-lo. Para enviar um ID exclusivo para atribuir à imagem inserida, o ID exclusivo é gerado popup.js e passado para o script de conteúdo.

popup.js (completo):

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
            chrome.tabs.sendMessage(
                tabs[0].id,
                {
                    url: chrome.runtime.getURL("images/stars.jpeg"),
                    imageDivId: crypto.randomUUID(),
                    tabId: tabs[0].id
                },
                function(response) {
                    window.close();
                }
            );
        });
    };
}

O ouvinte de mensagem do script de conteúdo (content.js)

Aqui está o content-scripts\content.js arquivo que é injetado em cada página da guia do navegador. Este arquivo é listado content-scripts na seção em manifest.json.

content.js (completo):

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
});

content.js registra um ouvinte usando o chrome.runtime.onMessage.addListener método de API de Extensão. Esse ouvinte aguarda a mensagem enviada quando popup.js as chamadas chrome.tabs.sendMessage.

Em content.js, o addListener método usa um único parâmetro que é uma função. O primeiro parâmetro dessa função, request, contém os detalhes da mensagem que está sendo passada.

Em content.js, quando um evento é processado pelo ouvinte, a função de ouvinte para a qual é passada addListener é executada. O primeiro parâmetro da função de ouvinte passado é um request objeto que tem atributos atribuídos por sendMessage.

Em popup.js, para a chrome.tabs.sendMessage chamada de método, os atributos do segundo parâmetro para sendMessage são url, imageDivId, e tabId.

Aqui está a função de ouvinte isolado que é passada para addListener:

content.js (parte)

function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
}

As primeiras cinco linhas na função listener acrescentam um img elemento imediatamente abaixo do body elemento na guia do navegador.

A segunda linha na função de ouvinte, img.id = request.imageDivId;, define a ID do img elemento como a imageDivId solicitação passada.

Na função de ouvinte, a addEventListener chamada adiciona uma click função de ouvinte de evento que abrange toda a imagem, permitindo que o usuário clique em qualquer lugar da imagem. Quando você clica na imagem inserida, ela é removida da página da Web atual pela linha img.remove();, e o ouvinte de eventos também é removido, especificando { once: true }.

Como stars.jpeg é disponibilizado em qualquer guia do navegador

Para disponibilizar images/stars.jpeg em qualquer guia do navegador:

  • popup.js (acima) usa a chrome.runtime.getURL API.
  • O manifesto (abaixo) especifica que web_accessible_resources o tipo .jpeg corresponde a todas as URLs.

O exemplo injeta a imagem usando o src atributo do img elemento na página de conteúdo. A página de conteúdo está sendo executada em um thread exclusivo que não é o mesmo que o thread que executa a extensão. O arquivo de imagem estática deve ser exposto como um ativo da Web para que funcione corretamente.

Outra entrada é adicionada ao manifest.json arquivo para declarar que a imagem está disponível para todas as guias do navegador:

/manifest.json (parte):

"web_accessible_resources": [
    {
      "resources": ["images/*.jpeg"],
      "matches": ["<all_urls>"]
    }
  ]

O código no popup.js arquivo envia uma mensagem para a página de conteúdo que é incorporada à página da guia ativa atual.

Como os recursos são listados no manifesto (manifest.json)

O exemplo cria e injeta a página de conteúdo que é inserida na página da guia ativa atual. manifest.json inclui o content-scripts e web_accessible_resources, da seguinte forma:

/manifest.json (completo):

{
    "name": "Picture inserter using content script",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "description": "A browser extension that uses JavaScript to insert an image at the top of the current webpage.",
    "icons": {
        "16": "icons/extension-icon16x16.png",
        "32": "icons/extension-icon32x32.png",
        "48": "icons/extension-icon48x48.png",
        "128": "icons/extension-icon128x128.png"
    },
    "action": {
        "default_popup": "popup/popup.html"
    },
    "content_scripts": [
        {
            "matches": [
              "<all_urls>"
            ],
            "js": ["content-scripts/content.js"]
        }
    ],
    "web_accessible_resources": [
        {
            "resources": ["images/*.jpeg"],
            "matches": ["<all_urls>"]
        }
    ]
}

A seção do manifesto injeta content_scripts JavaScript em todas as guias do navegador

content_scripts Na seção de chave do arquivo de manifesto, o matches atributo é definido como <all_urls>, o que significa que .js os content_scripts arquivos (ou .css) especificados na seção de chave são injetados em todas as páginas de guia do navegador quando cada guia é carregada. Os tipos de arquivos permitidos que podem ser injetados são JavaScript (.js) e CSS (.css).

O manifesto deste exemplo especifica um único script de conteúdo, content-scripts/content.js.

Cada script de conteúdo é executado em seu próprio thread, em área restrita

Cada página de guia (e extensão) é executada em seu próprio thread. Mesmo que a guia do navegador contenha uma página da Web que executa código JavaScript, o content.js script injetado nessa guia do navegador pela extensão não tem acesso a esse código JavaScript. O script de conteúdo injetado só tem acesso ao DOM da página da Web.

Próximas etapas

Para desenvolver sua própria extensão do Microsoft Edge, você pode copiar e modificar o diretório do exemplo e instalar e testar a extensão resultante.

Confira também

GitHub:

  • Last updated on