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 da extensão. Esta seção é para mudanças de código obrigatórias que não estão relacionadas a outros problemas. As duas seções a seguir abordam substituir solicitações da Web de bloqueio e melhorar a segurança.

Substitua tabs.executeScript() por scripting.executeScript()

No Manifesto V3, executeScript() passa 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:

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

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

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

O exemplo mostra como fazer isso.

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

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

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

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

Substitua tabs.insertCSS() e tabs.removeCSS() por scripting.insertCSS() e scripting.removeCSS()

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

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

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

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

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

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

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

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

As ações do navegador e da página eram conceitos separados no Manifest V2. Embora tenham começado com funções distintas, as diferenças entre elas diminuíram com o tempo. No Manifest V3, esses conceitos são consolidados na API Action. Isso exige mudanças no seu manifest.json e no código da extensão, que são diferentes do que você teria colocado no script em segundo plano do Manifesto 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 fazia. 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"

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

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Substituir as APIs browserAction e pageAction pela API action

Agora, use a API action em vez das APIs browserAction e pageAction do Manifest V2.

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

browser.action.onClicked.addListener(tab => { ... });

Substituir callbacks por promessas

No Manifest V3, muitos métodos da 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 Promises, leia sobre elas na 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 aceitando callbacks depois que o suporte a promessas é adicionado. 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. Se quiser que uma promessa seja retornada, não transmita um callback. Alguns recursos da API, como listeners de eventos, ainda vão exigir callbacks. Para verificar se um método oferece suporte a promessas, procure o rótulo "Promise" na referência da API.

Para converter de um callback para uma promessa, remova o callback e processe a promessa retornada. O exemplo abaixo foi extraído da amostra de permissões opcionais, especificamente newtab.js. A versão de callback mostra como seria a chamada da amostra para request() com um callback. A versão da promessa pode ser reescrita com async e await.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

const newPerms = { permissions: ['topSites'] };
browser.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 service workers de extensão usando transmissão de mensagens. Consequentemente, você precisará substituir as chamadas que esperam um contexto em segundo plano, especificamente:

• browser.runtime.getBackgroundPage()
• browser.extension.getBackgroundPage()
• browser.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 extensão. No momento, isso pode ser feito usando sendMessage() e implementando browser.runtime.onMessage no service worker da extensão. A longo prazo, planeje substituir essas chamadas por postMessage() e um manipulador de eventos de mensagem do service worker.

Substituir APIs sem suporte

Os métodos e propriedades listados abaixo precisam mudar no Manifest V3.