Atualizar seu código

Atualizações não relacionadas a outros problemas

Esta é a primeira das 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 é para mudanças de código necessárias não relacionadas a outros problemas. As próximas duas seções abordam como substituir solicitações da Web de bloqueio e melhorar a segurança.

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

No Manifesto V3, o executeScript() muda 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.

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

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

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

  • Embora o método antigo só aceitasse um arquivo, o novo método podia usar uma matriz de arquivos.
  • Você também transmite um objeto ScriptInjection em vez de InjectDetails. Existem várias diferenças entre as duas. Por exemplo, o tabId agora é transmitido como um 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 Planilhas.removeCSS() por scripting.insertCSS() e scripting.removeCSS()

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

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

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

  • Ao chamar esses métodos, você transmite um objeto CSSInjection em vez de InjectDetails.
  • O tabId agora é transmitido como um 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 de página por ações

Ações do navegador e 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 do que você colocaria no script em segundo plano do Manifest V2.

As ações no Manifest V3 são mais 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 na 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 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

Nos locais em que o Manifest V2 usava as APIs browserAction e pageAction, use 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 Promise é 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á-los 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 promessas é adicionado. Esteja ciente de que não é possível usar ambos na mesma chamada de função. Se você transmitir um callback, a função não vai retornar uma promessa. 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 do exemplo de permissões opcionais (link em inglês), especificamente newtab.js. A versão do callback mostra como seria a chamada do exemplo para request() com um callback. Observe que a versão da promessa pode ser reescrita com as funções async e await.

Callback
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 usando a transmissão de mensagens. Consequentemente, será necessário substituir as chamadas que esperam um contexto em segundo plano, especificamente:

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

Os 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 o uso de sendMessage() e a implementação de chrome.runtime.onMessage no service worker de extensão. Em longo prazo, planeje substituir essas chamadas por postMessage() e pelo manipulador de eventos de mensagem de um service worker.

Substituir APIs sem suporte

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

Método ou propriedade do Manifesto V2 Substitua 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 retornarem 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.onRequest
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) Não suportado 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