Anatomia de uma WebExtension

Uma WebExtension consiste de uma coleção de arquivos, empacotados para distribuição e instalação. Nesse artigo vamos falar rapidamente sobre os arquivos que podem estar presentes em uma WebExtension.

Toda WebExtension contém um arquivo chamado "manifest.json". Ele pode conter ponteiros para quatro outros tipos de arquivos:

background pages: implementação de lógica de longa duração
content scripts: executado no contexto de páginas web
browser action files: implementação de botões na toolbar
web accessible resources: torna o conteúdo do pacote acessível a páginas web e scripts de conteúdo

manifest.json

Esse é o único arquivo que está presente em toda WebExtension. Ele contém metadados básicos sobre a extensão, tais como o nome, a versão e as permissões que ela necessita. Também provê ponteiros para outros arquivos na extensão.

Para mais detalhes sobre o arquivo "manifest.json", acesse a página de referência.

Background pages

Muitas vezes as WebExtensions precisam manter um estado ou performance operativa de longa duração, independentemente do ciclo de vida das páginas ou janelas do navegador. As background pages e os scripts servem pra isso.

Background scripts são carregados assim que a extensão tem sua carga concluída, e permanecem carregados até que ela seja desativada ou desinstalada. No script você pode fazer uso de qualquer uma das WbExtensions APIs.

Os background scripts não possuem acesso direto às páginas web. No entanto, ele podem carregar scripts de conteúdo na página, e podem se comunicar com os scripts de conteúdo usando uma API de envio de mensagens.

Você pode incluir uma background page usando a chave background no "manifest.json". Você não precisa informar a sua própria background page. Se você incluir uma background page, um arquivo vazio será criado.

// manifest.json

"background": {
  "scripts": ["background-script.js"]
}

No entanto, você pode escolher informar a background page como um arquivo HTML a parte:

// manifest.json

"background": {
  "page": "background-page.html"
}

Content scripts

Use os content scripts para acessar e manipular páginas web. Content scripts são carregados dentro das páginas web e executados em um contexto particular nessa página.

Eles podem ver e manipular páginas DOM,

Content scripits pode ver e manipular o DOM das páginas, da mesma forma como os scripts normais carregados pela página.

Ao contrário dos scripts normais, os content scripts podem:

fazer requisições XHR cross-domain
utilizar um pequeno subconjunto de WebExtension APIs
trocar mensagens com os background scripts e acessar indiretamente todas as WebExtensions APIs.

Content Script não podem acessar diretamente os scripts normais da página, mas podem trocar mensagens com eles através do uso da API window.postMessage.

Normalmente, quando falamos de content scripts, estamos nos referindo a JavaScript, mas é possível injetar CSS em paginas web que utilizam o mesmo mecanismo.

Você pode injetar content scripts em páginas web de duas formas: anexando os scripts para todas as páginas correspondentes a um padrão de URL, ou através de programação a partir de um background script.

Para injetar scripts em páginas com base na URL, use a chave content_scripts no "manifest.json", informando um ou mais scripts e um array com os padrões:

// manifest.json

"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["my-script.js"]
  }
]

Se a URL da página corresponder aos padrões passados na chave matches, os scripts passados na chave js serão carregados.

Para injetar os scripts na página via programação(por exemplo, quando o usuário clicar em um botão) use a API tabs:

// background.js

chrome.tabs.executeScript({
  file: "my-script.js"
});

Aprenda mais sobre content scripts lendo sua documentação.

Browser actions

Um "browser action"é um botão que você pode adicionar na toolbar do Firefox. O botão tem um ícone. Você pode informar múltiplos ícones em diferentes tamanhos: fazendo isso, o navegador irá selecionar o ícone mais adequado para a densidade de pixels da tela.

Opcionalmente, você pode definir um popup para o botão usando HTML, CSS e JavaScript.

Se você não definir um popup, quando o usuário clicar no botão um evento será disparado, que pode ser ouvido nos background scripts.

Se você define um popup, o evento não é disparado: ao invés disso, o popup será mostrado para que o usuário possa interagir. Os scripts executados em popup são capazes de utilizar WebExtension APIs.

Para aprender mais sobre browser actions, consulte a página da API.

Web accessible resources

Web accessible resources, ou recursos acessíveis na web, são recursos como imagens, HTML, CSS, JavaScript, que podem ser incluídos na extensão e quer tornar acessível aos content scripts e scripts da página. Eles podem ser referenciados a partir de scripts de página e conteúdo, usando um URI scheme especial.

Por exemplo, se um content script quer inserir algumas imagens em páginas da web, você pode incluií-los na extensão e torná-los acessíveis na web. Em seguida o content script pode criar e acrescentar tags img que fazem referência às imagens através do atributo src.