Atualizar seu código

Atualizações não relacionadas a outros problemas

Esta é a primeira de três seções que descrevem as mudanças necessárias para o código que não faz parte do service worker de extensão. Esta seção é sobre as mudanças necessárias de código que não estão relacionadas a outros problemas. As próximas duas seções abordam a substituição de solicitações da Web bloqueadas e o aumento da segurança.

Substituição de tabs.executeScript() por scripting.executeScript()

No Manifesto V3, o executeScript() é movido da API tabs para a API scripting. Isso exige mudanças nas permissões do arquivo de manifesto, além das mudanças reais no código.

Para o método executeScript(), você precisa de:

  • A permissão "scripting";
  • Permissões do host ou "activeTab".

O método scripting.executeScript() é semelhante a como funcionava com tabs.executeScript(). Há algumas diferenças.

  • Embora o método antigo só pudesse ter um único arquivo, o novo método pode usar uma matriz de arquivos.
  • Você também transmite um objeto ScriptInjection em vez de InjectDetails. Há várias diferenças entre as duas. Por exemplo, o tabId agora é transmitido como membro de ScriptInjection.target em vez de como um argumento de método.

O exemplo mostra como fazer isso.

Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

chrome.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

Em um arquivo de script em segundo plano.

Manifesto V3
async function getCurrentTab()
let tab = await getCurrentTab();

chrome.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

No service worker de extensão.

Substituição de tabs.insertCSS() e tabs.removeCSS() por scripting.insertCSS() e scripting.removeCSS()

No Manifesto V3, insertCSS() e removeCSS() são movidos da API tabs para a API scripting. Isso exige mudanças nas permissões do arquivo de manifesto, além de mudanças no código:

  • A permissão "scripting";
  • Permissões do host ou "activeTab".

As funções na API scripting são semelhantes às funções em tabs. Há algumas diferenças.

  • Ao chamar esses métodos, você transmite um objeto CSSInjection em vez de InjectDetails.
  • O tabId agora é transmitido como membro de CSSInjection.target em vez de como um argumento de método

O exemplo mostra como fazer isso para insertCSS(). O procedimento para removeCSS() é o mesmo.

Manifest V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

Em um arquivo de script em segundo plano.

Manifesto V3
const insertPromise = await chrome.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

No service worker de extensão.

Substituir ações do navegador e ações da página por ações

Ações do navegador e ações da página eram conceitos separados no Manifesto V2. Embora tenham começado com papéis distintos, as diferenças entre eles diminuíram com o tempo. No Manifest V3, esses conceitos são consolidados na API Action. Isso exige mudanças no manifest.json e no código da extensão diferentes das que você colocaria no script em segundo plano do Manifest V2.

As ações no Manifest V3 são muito parecidas com as ações do navegador. No entanto, a API action não fornece hide() e show() como o pageAction. Se você ainda precisar de ações da página, emule-as usando conteúdo declarativo ou chame enable() ou disable() com um ID de guia.

Substitua "browser_action" e "page_action" por "action"

Em manifest.json, substitua os campos "browser_action" e "page_action" pelo campo "action". Consulte a referência para ver informações sobre o campo "action".

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifesto V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Substituir as APIs browserAction e pageAction pela API de ação

Onde o Manifest V2 usava as APIs browserAction e pageAction, agora você precisa usar a API action.

Manifest V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
Manifesto V3
chrome.action.onClicked.addListener(tab => { ... });

Substituir callbacks por promessas

No Manifest V3, muitos métodos de API de extensão retornam promessas. Uma promessa é um proxy ou marcador de posição para um valor retornado por um método assíncrono. Se você nunca usou promessas, leia sobre elas no MDN. Esta página descreve o que você precisa saber para usá-las em uma extensão do Chrome.

Para compatibilidade com versões anteriores, muitos métodos continuam a oferecer suporte a callbacks depois que o suporte a promessa é adicionado. Saiba que não é possível usar os dois na mesma chamada de função. Se você transmitir um callback, a função não vai retornar uma promessa e, se você quiser que uma promessa seja retornada, não transmita um callback. Alguns recursos da API, como listeners de eventos, continuarão exigindo callbacks. Para verificar se um método é compatível com promessas, procure o rótulo "Promise" na referência da API.

Para converter um callback em uma promessa, remova o callback e processe a promessa retornada. O exemplo abaixo foi retirado de um exemplo de permissões opcionais, especificamente newtab.js. A versão do callback mostra como ficaria a chamada de exemplo para request() com um callback. Observe que a versão da promessa pode ser reescrita com as funções async e await.

Chamada de retorno
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promise
const newPerms = { permissions: ['topSites'] };
chrome.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Substituir funções que esperam um contexto em segundo plano do Manifest V2

Outros contextos de extensão só podem interagir com os service workers de extensão usando a transmissão de mensagens. Por isso, é necessário substituir as chamadas que esperam um contexto em segundo plano, especificamente:

  • chrome.runtime.getBackgroundPage()
  • chrome.extension.getBackgroundPage()
  • chrome.extension.getExtensionTabs()

Seus scripts de extensão precisam usar a transmissão de mensagens para se comunicar entre um service worker e outras partes da sua extensão. Atualmente, isso envolve usar sendMessage() e implementar chrome.runtime.onMessage no service worker de extensão. Em longo prazo, planeje a substituição dessas chamadas por postMessage() e pelo manipulador de eventos de mensagem de um service worker.

Substituir APIs sem suporte

Os métodos e propriedades listados abaixo precisam ser alterados no Manifesto V3.

Método ou propriedade do Manifest V2 Substituir por
chrome.extension.connect() chrome.runtime.connect()
chrome.extension.connectNative() chrome.runtime.connectNative()
chrome.extension.getExtensionTabs() chrome.extension.getViews()
chrome.extension.getURL() chrome.runtime.getURL()
chrome.extension.lastError Quando os métodos retornam promessas, use promise.catch().
chrome.extension.onConnect chrome.runtime.onConnect
chrome.extension.onConnectExternal chrome.runtime.onConnectExternal
chrome.extension.onMessage chrome.runtime.onMessage
chrome.extension.onRequest chrome.runtime.onMessage
chrome.extension.onRequestExternal chrome.runtime.onMessageExternal
chrome.extension.sendMessage() chrome.runtime.sendMessage()
chrome.extension.sendNativeMessage() chrome.runtime.sendNativeMessage()
chrome.extension.sendRequest() chrome.runtime.sendMessage()
chrome.runtime.onSuspend (scripts em segundo plano) Indisponível em service workers de extensão. Use o evento de documento beforeunload.
chrome.tabs.getAllInWindow() chrome.tabs.query()
chrome.tabs.getSelected() chrome.tabs.query()
chrome.tabs.onActiveChanged chrome.tabs.onActivated
chrome.tabs.onHighlightChanged chrome.tabs.onHighlighted
chrome.tabs.onSelectionChanged chrome.tabs.onActivated
chrome.tabs.sendRequest() chrome.runtime.sendMessage()
chrome.tabs.Tab.selected chrome.tabs.Tab.highlighted