Partilhar via

Exemplo: Insertor de imagens com o script de conteúdo

  • Artigo

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

Este exemplo demonstra as seguintes funcionalidades de extensão:

  • Injetar bibliotecas JavaScript numa extensão.
  • Expor recursos de extensão a separadores do browser.
  • Incluindo páginas Web de conteúdo em separadores de browser existentes.
  • Fazer com que as páginas Web de conteúdo ouçam mensagens de pop-ups e respondam.

Pré-visualização do exemplo

Irá instalar o exemplo de extensão com o separador Gerir Extensões do browser, 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 abrir a extensão

A extensão apresenta uma pequena página Web HTML num pop-up, que contém um título, um botão Inserir imagem e instruções:

popup.html apresentar depois de selecionar o ícone de Extensão

Quando clica no botão Inserir imagem , o código JavaScript é inserido stars.jpeg temporariamente na parte superior da página Web atual e envia o conteúdo da página Web para baixo para baixo da imagem. O conteúdo injetado define o elemento de imagem para apresentar a imagem stars.jpeg estática na parte superior da página Web atual:

A imagem apresentada no browser

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

Obtenha, instale e execute o exemplo da seguinte forma.

Clonar o repositório de MicrosoftEdge-Extensions

Pode utilizar várias ferramentas para clonar um repositório do GitHub. Pode transferir um diretório selecionado ou clonar todo o repositório.

Clone o repositório MicrosoftEdge-Extensions para a unidade local e, em seguida, mude para um ramo de trabalho, da seguinte forma.

  1. Numa linha de comandos, introduza git para marcar se o git está instalado.

  2. Se ainda não tiver terminado, transfira o git e instale-o.

  3. Se ainda não tiver terminado, inicie uma linha de comandos onde o git está instalado.

  4. Mude para o diretório para o qual pretende clonar o repositório MicrosoftEdge-Extensions . Por exemplo:

    cd C:/Users/localAccount/GitHub/

  5. No Microsoft Edge, aceda ao repositório MicrosoftEdge-Extensions .

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

  7. Na janela da linha de comandos, introduza o comando:

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

    O /MicrosoftEdge-Extensions/ diretório é adicionado no diretório que especificou.

Criar um ramo de trabalho e mudar para o mesmo

  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 ramo de trabalho:

    git branch test

  4. Mude para o ramo de trabalho:

    git switch test

    Devolve: Switched to branch 'test'

Agora, pode modificar o código no ramo de trabalho, sem alterar o código que está no ramo "main" do repositório. Mais tarde, poderá querer mudar para o ramo "main" ou criar um ramo diferente com base no ramo "main".

Instalar o exemplo localmente

Em vez de instalar o exemplo a partir da Loja, irá instalar o exemplo localmente, para que possa modificá-lo e testar rapidamente as alterações. Por vezes, instalar localmente chama-se sideloading de uma extensão.

  1. No Microsoft Edge, clique no botão Extensões (ícone Extensões), junto à Barra de endereço, se este ícone for apresentado. Em alternativa, selecione Definições e muito mais (o ícone ) >Extensões ícone extensões. O pop-up Extensions (Extensões ) é aberto:

    O pop-up Extensões quando não existem extensões instaladas

  2. Clique em Gerir extensões. A página Gestão de extensões é aberta num novo separador:

    Ativar o Modo de Programador

  3. Ative o botão de alternar Modo de programador .

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

  5. Selecione o diretório que contém os ficheiros 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 é fechada.

    A extensão é instalada no browser, semelhante a uma extensão instalada a partir do arquivo:

    Página de extensões instaladas a mostrar uma extensão de sideload

Executar o exemplo

  1. Aceda a uma página Web, como a aplicação TODO, numa nova janela ou separador. O separador não pode estar vazio e não pode ser a página Gerir Extensões, porque este exemplo insere conteúdo na página Web atual.

  2. Atualize a página Web. Por vezes, isto é necessário depois de recarregar uma extensão.

  3. No Microsoft Edge à direita da Barra de endereço, se este ícone for apresentado, clique no botão Extensões (ícone Extensões). Em alternativa, selecione Definições e muito mais (o ícone ) >Extensões.

    O pop-up Extensions (Extensões ) é aberto:

    Clicar no ícone da extensão para abrir a extensão

  4. Clique no ícone ou nome da extensão (Insertor de imagens com script de conteúdo).

    A extensão é aberta e o ícone da extensão é adicionado junto ao ícone Barra de endereço e Extensões (ícone Extensões).

    É aberto um pop-up que contém uma pequena página 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 Web atual no separador atual, ao enviar o conteúdo da página Web para baixo abaixo da imagem:

    A imagem apresentada no browser

  6. Clique na stars.jpeg imagem que está a preencher a parte superior da página Web. Esse elemento de imagem é removido da árvore do DOM e da página Web e a página Web atual é restaurada, mudando o respetivo conteúdo de volta para a parte superior do separador.

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

Veja também:

Estudar a amostra

Nas secções seguintes, vai estudar o exemplo. Depois disso, para desenvolver a sua própria extensão do Microsoft Edge, pode copiar e modificar o diretório do exemplo e instalar e testar a extensão resultante.

Ficheiros e diretórios

O exemplo tem a seguinte estrutura e ficheiros de diretório.

Caminho de exemplo para o exemplo:

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

Diretórios e ficheiros 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 que é injetado na página Web atual.
  • O /icons/ diretório contém versões de um .png ficheiro que é utilizado para representar a extensão perto da barra de Endereço do browser, no pop-up Extensões e na página Gestão de extensões .
  • O /images/ diretório contém stars.jpeg, que é apresentado no pop-up da extensão.
  • O /popup/ diretório contém os ficheiros:
    • popup.html define o conteúdo na página Web de pop-up inicial da extensão (um título, botão e instruções).
    • popup.js para a página Web de pop-up inicial envia uma mensagem para o script de conteúdo (content.js) que está em execução na página de separador, especificando o ficheiro de imagem a apresentar.
  • manifest.json contém informações básicas sobre a extensão.

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

Este exemplo inclui um script de conteúdo que é injetado na página Web que é carregado no separador atual do browser.

  1. Quando executa o exemplo de extensão, é apresentada a página HTML de pop-up inicial (popup.html), que mostra um título, instruções e o botão Inserir imagem .

  2. Quando clica no botão Inserir imagem , o JavaScript (popup.js) da página de pop-up inicial envia uma mensagem para o script de conteúdo (content.js) que está em execução na página de separador. A mensagem especifica o ficheiro de imagem a apresentar.

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

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

/popup/popup.html é especificado no ficheiro de manifesto como a página Web a apresentar no pop-up inicial da extensão. O ficheiro de manifesto contém o campo "default_popup": "popup/popup.html"de chave . O ficheiro deste popup.html exemplo é uma pequena página 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 de 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 no separador do browser. Para tal, popup.js adiciona um onclick evento ao botão Inserir imagem da página Web de pop-up, que tem o ID sendmessageid:

popup.js (porção):

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

Em popup.js, chrome.tabs.query localiza o separador do browser atual e, em seguida chrome.tabs.sendMessage , envia uma mensagem para esse separador. O exemplo passa no ID do separador atual. A mensagem tem de incluir o URL da imagem que será apresentada.

Tem de enviar um ID exclusivo para atribuir à imagem inserida, para encontrar o elemento de imagem novamente mais tarde e eliminá-lo. Para enviar um ID exclusivo para atribuir à imagem inserida, o ID exclusivo é gerado e popup.js transmitido para o script de conteúdo.

popup.js (concluído):

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 serviço de escuta de mensagens do script de conteúdo (content.js)

Eis o content-scripts\content.js ficheiro que é injetado em todas as páginas de separadores do browser. Este ficheiro está listado na content-scripts secção em manifest.json.

content.js (concluído):

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 regista um serviço de escuta com o método da chrome.runtime.onMessage.addListener API de Extensão. Este serviço de escuta aguarda a mensagem que é enviada quando popup.js chama chrome.tabs.sendMessage.

No content.js, o addListener método utiliza um único parâmetro que é uma função. O primeiro parâmetro dessa função, request, contém os detalhes da mensagem que está a ser transmitida.

No content.js, quando um evento é processado pelo serviço de escuta, a função de addListener serviço de escuta transmitida é executada. O primeiro parâmetro da função de serviço de escuta transmitida é um request objeto que tem atributos atribuídos por sendMessage.

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

Eis a função de serviço de escuta isolada que é transmitida para addListener:

content.js (porção)

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 de serviço de escuta acrescentam um img elemento imediatamente abaixo do body elemento no separador do browser.

A segunda linha na função do serviço de escuta, img.id = request.imageDivId;, define o ID do img elemento para o imageDivId do pedido transmitido.

Na função de serviço de escuta, a addEventListener chamada adiciona uma click função de serviço de escuta de eventos que abrange toda a imagem, permitindo ao utilizador clicar em qualquer parte da imagem. Quando clica na imagem inserida, a imagem é removida da página Web atual pela linha img.remove();e o serviço de escuta de eventos também é removido ao especificar { once: true }.

Como stars.jpeg é disponibilizado a partir de qualquer separador do browser

Para disponibilizar images/stars.jpeg a partir de qualquer separador do browser:

  • popup.js (acima) utiliza a chrome.runtime.getURL API.
  • O manifesto (abaixo) especifica que web_accessible_resources do tipo .jpeg corresponde a todos os URLs.

O exemplo injeta a imagem com o src atributo do img elemento na página de conteúdo. A página de conteúdo está em execução num thread exclusivo que não é o mesmo que o thread que executa a extensão. O ficheiro de imagem estático tem de ser exposto como um recurso Web, para que funcione corretamente.

É adicionada outra entrada no manifest.json ficheiro para declarar que a imagem está disponível para todos os separadores do browser:

/manifest.json (porção):

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

O código no popup.js ficheiro envia uma mensagem para a página de conteúdo incorporada na página do separador ativo atual.

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

O exemplo cria e injeta a página de conteúdo incorporada na página do separador ativo atual. manifest.json inclui o content-scripts e web_accessible_resources, da seguinte forma:

/manifest.json (concluído):

{
    "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 secção do manifesto injeta JavaScript em todos os separadores do content_scripts browser

content_scripts Na secção de chave do ficheiro de manifesto, o atributo está definido como <all_urls>, o matches que significa que .js os ficheiros (ou .css) especificados na secção de chave são injetados em content_scripts todas as páginas de separador do browser quando cada separador é carregado. Os tipos de ficheiro 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 no seu próprio thread, em sandbox

Cada página de separador (e extensão) é executada no seu próprio thread. Mesmo que o separador do browser contenha uma página Web que execute código JavaScript, o content.js script que é injetado nesse separador do browser 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 Web.

Próximas etapas

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

Confira também

GitHub: