Esta página foi traduzida pela API Cloud Translation.

Tutorial: migrar para o Manifest V2

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

Este documento apresenta listas de verificação para migrar as extensões do Chrome da versão 1 para a versão 2 do manifesto, seguidas de resumos mais detalhados do que essas mudanças significam e por que elas 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.
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-a como false para converter sua página de plano de fundo em uma página de eventos.

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

Você está usando blocos de script in-line 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(), novo Function(), innerHTML, setTimeout() ou transmitindo strings de código JS que são avaliadas dinamicamente?
Use JSON.parse() ao analisar o código JSON em um objeto.
Use uma biblioteca compatível com CSP, por exemplo, AngularJS.
Crie uma entrada do sandbox no manifesto e execute o código afetado no sandbox usando postMessage() para se comunicar com a página no modo sandbox.
Você está carregando código externo, como jQuery ou Google Analytics?
Considere fazer o download da biblioteca e empacotá-la na extensão e, em seguida, carregá-la do pacote local.
Autorize o domínio HTTPS que exibe o recurso na parte "content_security_policy" do seu manifesto.

Resumo das mudanças na API

A versão 2 do manifesto introduz algumas mudanças nas APIs de ações do navegador e de página e substitui algumas APIs antigas por outras mais recentes.

Mudanças nas ações do navegador

A API de ações do navegador traz algumas mudanças na nomenclatura:

As propriedades browser_actions e chrome.browserActions foram substituídas pelas equivalentes browser_action e chrome.browserAction.
Na antiga propriedade browser_actions, havia icons, name e popup. Eles foram substituídos por:
default_icon do ícone de 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 IU para a ação do navegador (agora precisa ser uma string, e não um objeto).

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

Assim como nas ações do navegador, a API de ações da página também mudou:

As propriedades page_actions e chrome.pageActions foram substituídas pelas contrapartes únicas page_action e chrome.pageAction.
Na antiga propriedade page_actions, havia icons, name e popup. Eles foram substituídos por:
default_icon para o ícone de selo de ação da 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 da página (agora precisa ser uma string, e não um objeto).

APIs removidas e alteradas

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

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 na segurança

Há várias mudanças relacionadas à segurança que acompanham a mudança da versão 1 do manifesto para a versão 2. Muitas dessas mudanças são resultado 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.

Scripts in-line 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, não há compatibilidade com manipuladores de eventos inline. Por exemplo, suponha que você tenha o seguinte código em 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 de ocorrência e conveniência usados 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">

Eles não vão funcionar nas extensões do Manifest V2. Remova os manipuladores de eventos inline, coloque-os no 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 simples de separar o comportamento da extensão da marcação da interface do usuário.

Incorporação de conteúdo

Existem 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 de extensão em páginas da Web: se a extensão incorporar recursos (como imagens, script, estilos CSS etc.) que são usados em scripts de conteúdo injetados em páginas da Web, você precisará usar a propriedade web_accessible_resources para autorizar esses recursos a fim de que as páginas da Web externas possam usá-los:

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

Incorporar conteúdo externo: a Política de Segurança de Conteúdo permite apenas o carregamento de scripts e objetos locais do pacote, o que impede que invasores externos introduzam código desconhecido na extensão. No entanto, há momentos em que você quer carregar recursos veiculados externamente, como jQuery ou 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.
Você pode relaxar a CSP de maneira limitada, colocando origens HTTPS na lista de permissões na seção "content_security_policy" do manifesto. Para incluir uma biblioteca como o Google Analytics, esta é a abordagem a ser adotada:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Como usar a avaliação de script dinâmico

Talvez uma das maiores mudanças no novo esquema do manifesto v2 seja que as extensões não podem mais usar técnicas de avaliação de script dinâmico, como eval() ou o novo Function(), ou transmitir strings de código JS para funções que farão com que um eval() seja usado, como setTimeout(). Além disso, algumas bibliotecas JavaScript comumente usadas, como o Google Maps e algumas 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 têm acesso ao Chrome.* APIs Para usar eval() e conteúdo semelhante na nova Política de Segurança de Conteúdo:

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

Para mais detalhes sobre como fazer isso, consulte a documentação Avaliação de sandbox.