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 Chrome e das páginas de documentação da Chrome Web Store para que elas sejam mais fáceis de ler.
Neste guia, vamos explicar como fazer o seguinte:
- Use o worker de serviço de extensão como o coordenador de eventos.
- Preserve a privacidade do usuário com a permissão
"activeTab". - Executa o código quando o usuário clica 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
Neste guia, presumimos que você tenha experiência básica em desenvolvimento da 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 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, consulte o tutorial "Executar scripts em todas as guias", que explica os metadata e os ícones da extensão em 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 worker de serviço da extensão. Os workers de serviço são ambientes JavaScript especiais que processam eventos e são encerrados quando não são mais 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 o worker de serviço vai detectar é
runtime.onInstalled(). Esse método permite que a extensão defina um estado
inicial ou conclua algumas tarefas na instalação. As extensões podem usar a API Storage e o
IndexedDB para armazenar o estado do aplicativo. No entanto, neste caso, como estamos lidando apenas com dois estados, vamos usar o texto do selo da ação para rastrear se a extensão está "ATIVADA" ou "DESATIVADA".
Etapa 3: ativar a ação de extensão
A ação da extensão controla o ícone da barra de ferramentas da extensão. Assim, sempre que o usuário clicar no
ícone da extensão, ele vai executar algum código (como neste exemplo) ou mostrar um pop-up. Adicione o
código abaixo 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 sensíveis da
guia atual.
Essa permissão é ativada quando o usuário invocar a extensão. Nesse caso, o usuário invoca a extensão clicando na ação de extensão.
💡 Quais outras interações do usuário ativam a permissão activeTab na minha extensão?
- Pressionando uma combinação de atalho do teclado.
- Como selecionar um item do menu de contexto.
- Aceitar uma sugestão da omnibox.
- A abertura de um pop-up de extensão.
A permissão "activeTab" permite que os usuários escolham executar a extensão na guia
focada. Dessa forma, a privacidade do usuário é protegida. Outro benefício é que ele não
aciona 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 vai verificar se o URL corresponde a uma
página de documentação. Em seguida, ele vai verificar o estado da guia atual e definir o próximo estado. Adicione o
seguinte código a 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 mudar 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. É possível usar 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 de foco. Adicione a
chave "commands" ao manifesto.
{
...
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+B",
"mac": "Command+B"
}
}
}
}
A chave "_execute_action" executa o mesmo código do evento action.onClicked(). Portanto, nenhum código
adicional é necessário.
Testar se funciona
Verifique se a estrutura de arquivos do projeto tem a seguinte aparência:
Carregar a 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 das seguintes páginas:
Em seguida, clique na ação de extensão. Se você configurar um atalho de teclado, poderá testá-lo pressionando Ctrl + B ou Cmd + B.
A mudança deve ser esta:
Para:
🎯 Possíveis melhorias
Com base no que você aprendeu hoje, tente fazer o seguinte:
- Melhore a folha de estilo CSS.
- Atribuir um atalho diferente do teclado.
- Mudar 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 tutoriais desta série:
| Extensão | O que você vai aprender |
|---|---|
| Tempo de leitura | Para inserir um elemento em um conjunto específico de páginas automaticamente. |
| Gerenciador de guias | Para criar um pop-up que gerencie as guias do navegador. |
Continue descobrindo
Esperamos que você tenha gostado de criar essa extensão do Chrome e que continue sua jornada de aprendizado de desenvolvimento de extensões. Recomendamos os seguintes caminhos de aprendizagem:
- O guia para desenvolvedores tem dezenas de links adicionais para partes da documentação relevantes à criação de extensões avançadas.
- As extensões têm acesso a APIs poderosas além do que está disponível na Web aberta. A documentação das APIs do Chrome explica cada uma delas.