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:
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](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-activetab/image/focus-mode-extension-off-dc8f9326aa92b.png?authuser=9&hl=pt)
Para:
![Extensão do Modo sem distrações ATIVADA](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-activetab/image/focus-mode-extension-on-c248a59b498ea.png?authuser=9&hl=pt)
🎯 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:
- O Guia para desenvolvedores tem dezenas de links adicionais para documentações relevantes para a criação avançada de extensões.
- As extensões têm acesso a APIs poderosas além daquelas disponíveis na Web aberta. A documentação das APIs do Chrome explica cada API.