Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Tutorial: migrar para o Manifest V2

A versão 1 do manifesto foi descontinuada no Chrome 18, e o suporte será desativado de acordo com a programação de suporte da versão 1 do manifesto. As mudanças da versão 1 para a versão 2 se enquadram em duas categorias amplas: mudanças na API e mudanças na segurança.

Este documento fornece checklists para migrar suas extensões do Chrome do manifesto versão 1 para a versão 2, seguidos por resumos mais detalhados do que essas mudanças significam e por que foram feitas.

Lista de verificação de mudanças na API

Você está usando a propriedade browser_actions ou a API chrome.browserActions?
Substitua browser_actions pela propriedade browser_action singular.
Substitua chrome.browserActions por chrome.browserAction.
Substitua a propriedade icons por default_icon.
Substitua a propriedade name por default_title.
Substitua a propriedade popup por default_popup (que agora precisa ser uma string).
Você está usando a propriedade page_actions ou a API chrome.pageActions?
Substitua page_actions por page_action.
Substitua chrome.pageActions por chrome.pageAction.
Substitua a propriedade icons por default_icon.
Substitua a propriedade name por default_title.
Substitua a propriedade popup por default_popup (que agora precisa ser uma string).
Você está usando a propriedade chrome.self?
Substitua por chrome.extension.
Você está usando a propriedade Port.tab?
Substitua por Port.sender.
Você está usando as APIs chrome.extension.getTabContentses() ou chrome.extension.getExtensionTabs()?
Substitua por chrome.extension.getViews( { "type" : "tab" } ).
Sua extensão usa uma página em segundo plano?
Substitua a propriedade background_page por uma propriedade background.
Adicione uma propriedade scripts ou page que contenha o código da página.
Adicione uma propriedade persistent e defina como false para converter a página em segundo plano em uma página de evento.

Lista de verificação de mudanças na segurança

Você está usando blocos de script inline em páginas HTML?
Remova o código JS contido nas tags <script> e coloque-o em um arquivo JS externo.
Você está usando manipuladores de eventos inline (como onclick etc.)?
Remova-os do código HTML, mova-os para um arquivo JS externo e use addEventListener().
Sua extensão injeta scripts de conteúdo em páginas da Web que precisam acessar recursos (como imagens e scripts) contidos no pacote da extensão?
Defina a propriedade web_accessible_resources e liste os recursos (e, opcionalmente, uma Política de segurança de conteúdo separada para esses recursos).
Sua extensão incorpora páginas da Web externas?
Defina a propriedade sandbox.
Seu código ou biblioteca está usando eval(), novos Function(), innerHTML, setTimeout() ou transmitindo strings de código JS que são avaliadas dinamicamente?
Use JSON.parse() se você estiver analisando o código JSON em um objeto.
Use uma biblioteca compatível com CSP, por exemplo, AngularJS.
Crie uma entrada de sandbox no manifesto e execute o código afetado no sandbox usando postMessage() para se comunicar com a página em sandbox.
Você está carregando código externo, como jQuery ou Google Analytics?
Considere fazer o download da biblioteca e empacotá-la na sua extensão. Depois, carregue-a do pacote local.
Adicione à lista de permissões o domínio HTTPS que veicula o recurso na parte "content_security_policy" do manifesto.

Resumo das mudanças na API

A versão 2 do manifesto introduz algumas mudanças nas APIs de ação do navegador e da página, além de substituir algumas APIs antigas por outras mais recentes.

Mudanças nas ações do navegador

A API Browser Actions introduz algumas mudanças de nomenclatura:

As propriedades browser_actions e chrome.browserActions foram substituídas pelas contrapartes singulares browser_action e chrome.browserAction.
Na propriedade browser_actions antiga, havia propriedades icons, name e popup. Eles foram substituídos por:
default_icon para o ícone do selo de ação do navegador
default_name para o texto que aparece na dica quando você passa o cursor sobre o selo
default_popup para a página HTML que representa a interface da ação do navegador. Agora, isso precisa ser uma string, não um objeto.

Mudanças nas ações da página

Assim como as mudanças nas ações do navegador, a API Page Actions também mudou:

As propriedades page_actions e chrome.pageActions foram substituídas pelas contrapartes singulares page_action e chrome.pageAction.
Na propriedade page_actions antiga, havia propriedades icons, name e popup. Elas foram substituídas por:
default_icon para o ícone do selo de ação na página
default_name para o texto que aparece na dica quando você passa o cursor sobre o selo
default_popup para a página HTML que representa a interface da ação na página. Agora, isso precisa ser uma string, não um objeto.

APIs removidas e alteradas

Algumas APIs de extensão foram removidas e substituídas por novas equivalentes:

A propriedade background_page foi substituída por background.
A propriedade chrome.self foi removida. Use chrome.extension.
A propriedade Port.tab foi substituída por Port.sender.
As APIs chrome.extension.getTabContentses() e chrome.extension.getExtensionTabs() foram substituídas por chrome.extension.getViews( { "type" : "tab" } ).

Resumo das mudanças de segurança

Há várias mudanças relacionadas à segurança que acompanham a migração da versão 1 para a versão 2 do manifesto. Muitas dessas mudanças decorrem da adoção da Política de Segurança de Conteúdo pelo Chrome. Leia mais sobre essa política para entender as implicações dela.

Scripts inline e manipuladores de eventos não permitidos

Devido ao uso da Política de Segurança de Conteúdo, não é mais possível usar tags <script> inline com o conteúdo HTML. Eles precisam ser movidos para arquivos JS externos. Além disso, manipuladores de eventos inline também estão indisponíveis. Por exemplo, suponha que você tenha o seguinte código na sua extensão:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

Esse código causaria um erro durante a execução. Para corrigir isso, mova o conteúdo da tag <script> para arquivos externos e faça referência a eles com um atributo src='path_to_file.js'.

Da mesma forma, os manipuladores de eventos inline, que são um recurso comum e conveniente usado por muitos desenvolvedores da Web, não serão executados. Por exemplo, considere instâncias comuns como:

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

Elas não funcionam em extensões do Manifest V2. Remova os manipuladores de eventos inline, coloque-os no seu arquivo JS externo e use addEventListener() para registrar manipuladores de eventos para eles. Por exemplo, no seu código JS, use:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

Essa é uma maneira muito mais limpa de separar o comportamento da extensão da marcação da interface do usuário.

Incorporar conteúdo

Há alguns cenários em que sua extensão pode incorporar conteúdo que pode ser usado externamente ou vir de uma fonte externa.

Conteúdo da extensão em páginas da Web:se a extensão incorporar recursos (como imagens, scripts, estilos CSS etc.) usados em scripts de conteúdo injetados em páginas da Web, use a propriedade web_accessible_resources para permitir esses recursos e que páginas da Web externas possam usá-los:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Incorporação de conteúdo externo:a Política de Segurança de Conteúdo permite que apenas scripts e objetos locais sejam carregados do seu pacote, o que impede que invasores externos introduzam códigos desconhecidos na sua extensão. No entanto, há momentos em que você quer carregar recursos veiculados externamente, como o jQuery ou o código do Google Analytics. Há duas maneiras de fazer isso:

Faça o download da biblioteca relevante localmente (como jQuery) e empacote-a com sua extensão.
É possível flexibilizar a CSP de forma limitada ao permitir origens HTTPS na seção "content_security_policy" do manifesto. Para incluir uma biblioteca como o Google Analytics, siga esta abordagem:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Como usar a avaliação dinâmica de scripts

Talvez uma das maiores mudanças no novo esquema do Manifest v2 seja que as extensões não podem mais usar técnicas de avaliação de script dinâmico, como eval() ou novo Function(), nem transmitir strings de código JS para funções que vão causar o uso de um eval(), como setTimeout(). Além disso, algumas bibliotecas JavaScript usadas com frequência, como o Google Maps e determinadas bibliotecas de modelos, usam algumas dessas técnicas.

O Chrome oferece um sandbox para que as páginas sejam executadas na própria origem, que não tem acesso a chrome.*. APIs Para usar eval() e similares na nova política de segurança de conteúdo:

Crie uma entrada de sandbox no arquivo de manifesto.
Na entrada da sandbox, liste as páginas que você quer executar nela.
Use a transmissão de mensagens via postMessage() para se comunicar com a página em sandbox.

Para mais detalhes sobre como fazer isso, consulte a documentação Sandboxing Eval (em inglês).

Leitura adicional

As mudanças na versão 2 do manifesto foram projetadas para orientar os desenvolvedores a criar extensões e apps mais seguros e com arquitetura robusta. Para conferir uma lista completa de mudanças da versão 1 para a versão 2 do manifesto, consulte a documentação do arquivo de manifesto. Para mais informações sobre como usar o sandbox para isolar códigos não seguros, leia o artigo sandbox de avaliação. Saiba mais sobre a Política de Segurança de Conteúdo no tutorial relacionado a extensões e em uma boa introdução no HTML5Rocks.