Injetar scripts na guia ativa

Simplifique o estilo da página atual clicando no ícone da barra de ferramentas da extensão.

Visão geral

Este tutorial cria uma extensão que simplifica o estilo da extensão do Google Chrome e páginas de documentação da Chrome Web Store para facilitar a leitura.

Neste guia, explicaremos como:

  • Usar o service worker de extensão como o coordenador do evento.
  • Preserve a privacidade do usuário com a permissão "activeTab".
  • Execute o código quando o usuário clicar no ícone da barra de ferramentas da extensão.
  • Insira e remova uma folha de estilo usando a API Scripting.
  • Use um atalho de teclado para executar o código.

Antes de começar

Este guia pressupõe que você tenha experiência básica em desenvolvimento na Web. Recomendamos conferir Hello World para uma introdução ao fluxo de trabalho de desenvolvimento de extensões.

Criar a extensão

Para começar, crie um novo diretório chamado focus-mode que vai conter os arquivos da extensão. Se você Se preferir, faça o download do código-fonte completo no GitHub.

Etapa 1: adicionar os dados e ícones da extensão

Crie um arquivo chamado manifest.json e inclua o código abaixo.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

Para saber mais sobre essas chaves de manifesto, confira "Executar scripts em todas as guias" que explica os metadados e os ícones da extensão com mais detalhes.

Crie uma pasta images e faça o download dos ícones nela.

Etapa 2: inicializar a extensão

As extensões podem monitorar eventos do navegador em segundo plano usando o serviço da extensão worker. Service workers são ambientes JavaScript especiais que lidam e são encerrados quando não são necessários.

Comece registrando o service worker no arquivo manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

Crie um arquivo chamado background.js e adicione o seguinte código:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

O primeiro evento que nosso service worker vai detectar é runtime.onInstalled() Esse método permite que a extensão defina um valor ou concluir algumas tarefas na instalação. As extensões podem usar a API Storage e IndexedDB para armazenar o estado do aplicativo. Nesse caso, como estamos lidando apenas com dois estados, usaremos o próprio texto do selo da ação para rastrear se a extensão está "ATIVADA". ou "DESATIVADO".

Etapa 3: ativar a ação da extensão

A ação da extensão controla o ícone da barra de ferramentas da extensão. Portanto, sempre que o usuário clicar ícone de extensão, ela executará um código (como neste exemplo) ou exibirá um pop-up. Adicione o método código a seguir para declarar a ação de extensão no arquivo manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

Usar a permissão ActiveTab para proteger a privacidade do usuário

A permissão activeTab concede à extensão a capacidade temporária de executar código. na guia ativa. Ele também permite o acesso a propriedades confidenciais de guia atual.

Essa permissão é ativada quando o usuário invoca a extensão. Nesse caso, o usuário invoca clicando na ação da extensão.

💡 Quais outras interações do usuário ativam a permissão ActiveTab na minha extensão?

  • Pressionando uma combinação de atalhos de teclado.
  • Seleção de um item do menu de contexto.
  • Aceitando uma sugestão da omnibox.
  • Abrindo um pop-up de extensão.

A permissão "activeTab" permite que os usuários escolham intencionalmente executar a extensão no guia em foco dessa forma, protege a privacidade do usuário. Outro benefício é que ele não acionar um aviso de permissão.

Para usar a permissão "activeTab", adicione-a à matriz de permissões do manifesto:

{
  ...
  "permissions": ["activeTab"],
  ...
}

Etapa 4: acompanhar o estado da guia atual

Depois que o usuário clicar na ação da extensão, ela verificará se o URL corresponde a página de documentação. Em seguida, ele verifica o estado da guia atual e define o próximo estado. Adicione o método código abaixo para background.js:

const extensions = 'https://developer.chrome.com/docs/extensions';
const webstore = 'https://developer.chrome.com/docs/webstore';

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON';

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

Etapa 5: adicionar ou remover a folha de estilo

Agora é hora de alterar o layout da página. Crie um arquivo chamado focus-mode.css e inclua o seguinte código:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

Insira ou remova a folha de estilo usando a API Scripting. Comece declarando a permissão "scripting" no manifesto:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}

Por fim, em background.js, adicione o seguinte código para mudar o layout da página:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 Posso usar a API Scripting para injetar código em vez de uma folha de estilo?

Sim. Use scripting.executeScript() para injetar JavaScript.

Opcional: atribuir um atalho de teclado

Só por diversão, adicione um atalho para facilitar a ativação ou desativação do "Modo sem distrações". Adicione o método Chave "commands" ao manifesto.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

A tecla "_execute_action" executa o mesmo código que o evento action.onClicked(). código-fonte é necessário.

Testar se funciona

Verifique se a estrutura de arquivos do seu projeto é semelhante a esta:

O conteúdo da pasta do modo de foco: manifest.json, background.js,focus-mode.css e images.

Carregar sua extensão localmente

Para carregar uma extensão descompactada no modo de desenvolvedor, siga as etapas em Hello World.

Testar a extensão em uma página de documentação

Primeiro, abra uma destas páginas:

Em seguida, clique na ação de extensão. Se você configurou um atalho de teclado, é possível testá-lo pressionando Ctrl + B ou Cmd + B.

O resultado deve ser o seguinte:

Extensão do Modo sem distrações DESATIVADA
Extensão do Modo sem distrações desativada

Para:

Extensão do Modo sem distrações ATIVADA
Extensão "Modo sem distrações" ativada

🎯 Possíveis melhorias

Com base no que você aprendeu hoje, tente realizar uma das seguintes ações:

  • Melhore a folha de estilo CSS.
  • Atribua um atalho de teclado diferente.
  • Alterar o layout do seu blog ou site de documentação favorito.

Continue desenvolvendo.

Parabéns por concluir este tutorial 🎉. Continue melhorando suas habilidades concluindo outros cursos tutoriais desta série:

Extensão O que você vai aprender
Tempo de leitura Inserir um elemento em um conjunto específico de páginas automaticamente.
Gerenciador de guias Criar um pop-up que gerencie guias do navegador.

Continue descobrindo

Esperamos que você tenha gostado de criar essa extensão do Chrome e estamos animados para continuar a usá-la. e desenvolvimento de software. Recomendamos os seguintes programas de aprendizado: