As extensões são feitas de componentes diferentes, mas coesos. Os componentes podem incluir scripts em segundo plano, scripts de conteúdo, uma página de opções, elementos da interface e vários arquivos de lógica. Os componentes de extensão são criados com tecnologias de desenvolvimento da Web: HTML, CSS e JavaScript. Os componentes de uma extensão dependem de sua funcionalidade e podem não exigir todas as opções.
Este tutorial criará uma extensão que permite ao usuário alterar a cor de fundo de qualquer página em developer.chrome.com. Muitos componentes principais serão usados para fornecer uma demonstração introdutória das relações entre eles.
Para começar, crie um novo diretório para armazenar os arquivos da extensão.
A extensão completa pode ser encontrada aqui.
Criar o manifesto
As extensões começam pelo manifesto. Crie um arquivo chamado manifest.json e inclua o
código a seguir.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"manifest_version": 2
}
O diretório que contém o arquivo de manifesto pode ser adicionado como uma extensão no modo de desenvolvedor no estado atual.
- Abra a página "Gerenciamento de extensões" em
chrome://extensions.- Também é possível abrir a página "Gerenciamento de extensões" clicando no menu do Google Chrome, passando o cursor sobre Mais ferramentas e selecionando Extensões.
- Ative o modo de desenvolvedor clicando na chave ao lado de Modo de desenvolvedor.
- Clique no botão LOAD UNPACKED e selecione o diretório de extensão.
Pronto! A extensão foi instalada. Como nenhum ícone foi incluído no manifesto, um ícone genérico da barra de ferramentas será criado para a extensão.
Adicionar instrução
Embora a extensão tenha sido instalada, ela não tem instruções. Introduza um script em segundo plano
criando um arquivo intitulado background.js e colocando-o dentro do
diretório de extensões.
Os scripts em segundo plano e muitos outros componentes importantes precisam ser registrados no manifesto. O registro de um script de segundo plano no manifesto informa à extensão qual arquivo deve ser referenciado e como esse arquivo deve se comportar.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"background": {
"scripts": ["background.js"],
"persistent": false
},
"manifest_version": 2
}
A extensão agora está ciente de que inclui um script em segundo plano não persistente e verificará o arquivo registrado em busca de eventos importantes que ele precisa detectar.
Esta extensão precisará de informações de uma variável persistente assim que for instalada. Comece
incluindo um evento de detecção para runtime.onInstalled no script em segundo plano. Dentro do listener onInstalled, a extensão definirá um valor usando a API storage. Isso permitirá que vários componentes de extensão acessem esse valor e o atualizem.
chrome.runtime.onInstalled.addListener(function() {
chrome.storage.sync.set({color: '#3aa757'}, function() {
console.log("The color is green.");
});
});
A maioria das APIs, incluindo a API storage, precisa ser registrada no campo "permissions" no manifesto para que a extensão as use.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"permissions": ["storage"],
"background": {
"scripts": ["background.js"],
"persistent": false
},
"manifest_version": 2
}
Volte para a página de gerenciamento de extensões e clique no link Atualizar. Um novo campo, Inspecionar visualizações, fica disponível com um link azul, página de plano de fundo.
Clique no link para visualizar o registro do console do script de plano de fundo, "The color is green."
Apresentar uma interface do usuário
As extensões podem ter várias formas de interface do usuário, mas esta usará um pop-up.
Crie e adicione um arquivo intitulado popup.html ao diretório. Essa
extensão usa um botão para mudar a cor do plano de fundo.
<!DOCTYPE html>
<html>
<head>
<style>
button {
height: 30px;
width: 30px;
outline: none;
}
</style>
</head>
<body>
<button id="changeColor"></button>
</body>
</html>
Assim como o script em segundo plano, esse arquivo precisa ser designado como um pop-up no manifesto em
page_action.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"permissions": ["storage"],
"background": {
"scripts": ["background.js"],
"persistent": false
},
"page_action": {
"default_popup": "popup.html"
},
"manifest_version": 2
}
A designação para ícones da barra de ferramentas também está incluída em page_action no campo default_icons.
Faça o download da pasta de imagens aqui, descompacte-a e coloque-a no diretório da extensão. Atualize o manifesto para que a extensão saiba como usar as imagens.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"permissions": ["storage"],
"background": {
"scripts": ["background.js"],
"persistent": false
},
"page_action": {
"default_popup": "popup.html",
"default_icon": {
"16": "images/get_started16.png",
"32": "images/get_started32.png",
"48": "images/get_started48.png",
"128": "images/get_started128.png"
}
},
"manifest_version": 2
}
As extensões também exibem imagens na página de gerenciamento de extensões, no aviso de permissões e no favicon. Essas imagens são designadas no manifesto em icons.
{
"name": "Getting Started Example",
"version": "1.0",
"description": "Build an Extension!",
"permissions": ["storage"],
"background": {
"scripts": ["background.js"],
"persistent": false
},
"page_action": {
"default_popup": "popup.html",
"default_icon": {
"16": "images/get_started16.png",
"32": "images/get_started32.png",
"48": "images/get_started48.png",
"128": "images/get_started128.png"
}
},
"icons": {
"16": "images/get_started16.png",
"32": "images/get_started32.png",
"48": "images/get_started48.png",
"128": "images/get_started128.png"
},
"manifest_version": 2
}
Se a extensão for recarregada nessa etapa, ela incluirá um ícone em escala de cinza, mas não conterá diferenças de funcionalidade. Como page_action é declarado no manifesto, cabe à
extensão informar ao navegador quando o usuário pode interagir com popup.html.
Adicione as regras declaradas ao script em segundo plano com a API declarativeContent no
evento de listener runtime.onInstalled.
chrome.runtime.onInstalled.addListener(function() {
chrome.storage.sync.set({color: '#3aa757'}, function() {
console.log('The color is green.');
});
chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
chrome.declarativeContent.onPageChanged.addRules([{
conditions: [new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostEquals: 'developer.chrome.com'},
})
],
actions: [new chrome.declarativeContent.ShowPageAction()]
}]);
});
});
A extensão precisa de permissão para acessar a API declarativeContent no manifesto.
{
"name": "Getting Started Example",
...
"permissions": ["declarativeContent", "storage"],
...
}
O navegador agora mostra um ícone de ação da página em cores na barra de ferramentas quando os usuários navegam
para um URL que contém "developer.chrome.com". Quando o ícone está colorido, os usuários podem clicar nele para
visualizar pop-up.html.
A última etapa da interface pop-up é adicionar cor ao botão. Crie e adicione um arquivo chamado popup.js com o código a seguir ao diretório de extensão.
let changeColor = document.getElementById('changeColor');
chrome.storage.sync.get('color', function(data) {
changeColor.style.backgroundColor = data.color;
changeColor.setAttribute('value', data.color);
});
Esse código pega o botão de popup.html e solicita o valor da cor do armazenamento. Em seguida,
a cor é aplicada como plano de fundo do botão. Inclua uma tag de script para popup.js em popup.html.
<!DOCTYPE html>
<html>
...
<body>
<button id="changeColor"></button>
<script src="popup.js"></script>
</body>
</html>
Atualize a extensão para conferir o botão verde.
Lógica de camada
A extensão agora sabe que o pop-up precisa estar disponível para os usuários no developer.chrome.com e
mostra um botão colorido, mas precisa de lógica para mais interações. Atualize popup.js para
incluir o código abaixo.
let changeColor = document.getElementById('changeColor');
...
changeColor.onclick = function(element) {
let color = element.target.value;
chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
chrome.tabs.executeScript(
tabs[0].id,
{code: 'document.body.style.backgroundColor = "' + color + '";'});
});
};
O código atualizado adiciona um evento onclick ao botão, que aciona um script de conteúdo injetado
programaticamente. Isso deixa a cor de fundo da página igual à do botão. O uso
da injeção programática permite scripts de conteúdo invocados pelo usuário em vez da inserção automática
de códigos indesejados em páginas da Web.
O manifesto vai precisar da permissão activeTab para autorizar o acesso temporário da extensão à
API tabs. Isso permite que a extensão chame tabs.executeScript.
{
"name": "Getting Started Example",
...
"permissions": ["activeTab", "declarativeContent", "storage"],
...
}
A extensão agora está totalmente funcional. Atualize a extensão, atualize a página, abra o pop-up e clique no botão para que ele fique verde. No entanto, alguns usuários podem querer mudar o plano de fundo para uma cor diferente.
Oferecer opções aos usuários
No momento, a extensão só permite que os usuários alterem o plano de fundo para verde. A inclusão de uma página de opções oferece aos usuários mais controle sobre a funcionalidade da extensão, personalizando ainda mais a experiência de navegação.
Comece criando um arquivo no diretório chamado options.html e inclua o código a seguir.
<!DOCTYPE html>
<html>
<head>
<style>
button {
height: 30px;
width: 30px;
outline: none;
margin: 10px;
}
</style>
</head>
<body>
<div id="buttonDiv">
</div>
<div>
<p>Choose a different background color!</p>
</div>
</body>
<script src="options.js"></script>
</html>
Depois, registre a página de opções no manifesto
{
"name": "Getting Started Example",
...
"options_page": "options.html",
...
"manifest_version": 2
}
Atualize a extensão e clique em DETALHES.
Role a página de detalhes para baixo e selecione Opções de extensão para ver a página de opções, embora ela apareça em branco no momento.
A última etapa é adicionar a lógica de opções. Crie um arquivo chamado options.js no diretório de extensão
com o código a seguir.
let page = document.getElementById('buttonDiv');
const kButtonColors = ['#3aa757', '#e8453c', '#f9bb2d', '#4688f1'];
function constructOptions(kButtonColors) {
for (let item of kButtonColors) {
let button = document.createElement('button');
button.style.backgroundColor = item;
button.addEventListener('click', function() {
chrome.storage.sync.set({color: item}, function() {
console.log('color is ' + item);
})
});
page.appendChild(button);
}
}
constructOptions(kButtonColors);
Quatro opções de cor são fornecidas e geradas como botões na página de opções com listeners de eventos "onclick". Quando o usuário clica em um botão, ele atualiza o valor da cor no armazenamento global da extensão. Como todos os arquivos da extensão extraem as informações de cor do armazenamento global, nenhum outro valor precisa ser atualizado.
Vá além
Parabéns! Agora o diretório tem uma extensão do Chrome totalmente funcional, embora simplista.
Qual é a próxima etapa?
- A Visão geral da extensão do Chrome faz um backup e preenche muitos detalhes sobre a arquitetura de extensões em geral, e alguns conceitos específicos com os quais os desenvolvedores vão querer conhecer.
- Saiba mais sobre as opções disponíveis para depurar extensões no tutorial de depuração.
- As extensões do Chrome têm acesso a APIs avançadas, tudo o que está disponível na Web aberta. A interface chrome.* documentação das APIs explicará cada API.
- O Guia para desenvolvedores tem dezenas de links adicionais para partes da documentação relevantes para a criação de extensões avançadas.