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 versão 2 se enquadram em dois categorias amplas: alterações de API e alterações de segurança.

Este documento contém listas de verificação para a migração das extensões do Chrome da versão 1 do manifesto para a versão 2, seguida por resumos mais detalhados do que significam essas alterações e por que elas foram feitas.

Lista de verificação de alterações de 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 o chrome.extension.getTabContentses() ou o chrome.extension.getExtensionTabs() APIs?
Substitua por chrome.extension.getViews( { "type" : "tab" } ).
Sua extensão usa uma página de plano de fundo?
Substitua a propriedade background_page por uma background.
Adicione uma propriedade scripts ou page que contenha o código da página.
Adicione uma propriedade persistent e a defina como false para converter sua página de plano de fundo em um evento página

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 in-line (como "onclick" etc.)?
Remova-os do código HTML, mova-os para um arquivo JS externo e use addEventListener(). como alternativa.
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, se quiser, um 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 passando 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 a CSP, por exemplo, AngularJS.
Crie uma entrada de sandbox em seu 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 sua extensão. Em seguida, carregue-a a partir do pacote local.
Autorize o domínio HTTPS que veicula o recurso na "content_security_policy" parte da sua manifesto do aplicativo.

Resumo das mudanças na API

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

Mudanças nas ações do navegador

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

As propriedades browser_actions e chrome.browserActions foram substituídas pelas respectivas propriedades correspondentes no singular browser_action e chrome.browserAction.
Na antiga propriedade browser_actions, havia as propriedades icons, name e popup. Estes 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 (e agora isso precisa ser ser uma string, não pode ser 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 propriedades singulares page_action e chrome.pageAction.
Na antiga propriedade page_actions, havia as propriedades icons, name e popup. Esses 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 da página (e agora precisa ser uma string, não pode ser um objeto)

APIs removidas e alteradas

Algumas APIs de extensão foram removidas e substituídas por novas versões:

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() têm foi substituído por chrome.extension.getViews( { "type" : "tab" } ).

Resumo das mudanças de 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 provenientes da adoção da Política de Segurança de Conteúdo pelo Chrome; você leia mais sobre essa política para entender suas 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 devem ser movidos para arquivos JS externos. Além disso, os manipuladores de evento inline não são suportados. Por exemplo, suponha que você tivesse o seguinte código na sua extensão:

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

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

Da mesma forma, manipuladores de eventos inline, que são um recurso comum de ocorrência e de conveniência usado por muitos Os desenvolvedores Web não vão executar. Por exemplo, considere instâncias comuns como estas:

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

Elas não funcionam nas extensões do Manifest V2. Remova os manipuladores de eventos inline, coloque-os na sua arquivo JS externo e use addEventListener() para registrar manipuladores de eventos para eles. Para 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 sua extensão da marcação da interface do usuário.

Como incorporar conteúdo

Em alguns cenários, sua extensão pode incorporar conteúdo que pode ser usado externamente ou vêm de uma fonte externa.

Conteúdo de extensão em páginas da Web: Se sua extensão incorpora recursos (como imagens, script, estilos CSS etc.) que são usados no conteúdo scripts que são injetados em páginas da Web, você precisa usar a propriedade web_accessible_resources adicionar esses recursos à lista de permissões para que 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 só permite que scripts e objetos locais carreguem do seu pacote, o que impede que invasores externos introduzam código desconhecido na sua extensão. No entanto, existem momentos em que você deseja carregar recursos fornecidos externamente, como códigos jQuery ou 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 o CSP de forma limitada, colocando origens HTTPS na lista de permissões "content_security_policy" do manifesto. Para incluir uma biblioteca como o Google Analytics, esta é a abordagem a ser tomada:
```
{
  ...,
  "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 Manifest V2 é que as extensões não podem mais use técnicas de avaliação de script dinâmico, como eval() ou nova Function(), ou transmita strings de JS código para funções que farão com que um eval() seja usado, como setTimeout(). Além disso, alguns As bibliotecas JavaScript usadas com frequência, como o Google Maps e algumas bibliotecas de modelos, são conhecidas algumas dessas técnicas.

O Chrome oferece um sandbox para páginas que podem ser executadas na origem delas, sem acesso ao Chrome.* APIs Para usar eval() e recursos semelhantes 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.
Use a transmissão de mensagens por 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.

Leitura adicional

As alterações na versão 2 do manifesto foram desenvolvidas para orientar os desenvolvedores a criar aplicativos extensões e apps com arquitetura robusta. Para acessar uma lista completa das alterações da versão 1 do manifesto para a versão 2, 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 de avaliação de sandbox. Saiba mais sobre conteúdo Política de Segurança visitando nosso tutorial relacionado a extensões e uma boa introdução ao HTML5Rocks (link em inglês).