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 worker de serviço 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 próximas seções abordam como substituir solicitações da Web bloqueadas e como melhorar a segurança.

Substituir tabs.executeScript() por scripting.executeScript()

No Manifesto V3, 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 de host ou a permissão "activeTab".

O método scripting.executeScript() é semelhante ao método tabs.executeScript(). Existem algumas diferenças.

• Enquanto o método antigo aceita apenas um arquivo, o novo método aceita 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();

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

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

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

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

No Manifesto V3, insertCSS() e removeCSS() foram movidos 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";
• 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, 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.

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

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

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

Ações do navegador e ações de página eram conceitos separados no Manifesto V2. Embora tenham começado com funções diferentes, as diferenças entre elas diminuíram com o tempo. No Manifesto 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 de segundo plano do Manifest V2.

As ações no Manifesto V3 se assemelham muito às ações do navegador. No entanto, a API action não fornece hide() e show() como pageAction. Se você ainda precisar de ações de página, poderá emulá-las usando conteúdo declarativo ou chamar enable() ou disable() com um ID de guia.

Substituir "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 de ação

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

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

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á-los em uma extensão do Chrome.

Para compatibilidade com versões anteriores, muitos métodos continuam oferecendo suporte a callbacks depois que o suporte a promessas é adicionado. Lembre-se de que não é possível usar ambos na mesma chamada de função. Se você passar um callback, a função não 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 a 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 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. A versão da promessa pode ser reescrita com async e await.

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

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 workers de serviço de extensão usando a transmissão de mensagens. Consequentemente, você precisará substituir chamadas que esperam um contexto em segundo plano, especificamente:

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

Os scripts de extensão devem usar a transmissão de mensagens para a comunicação entre um service worker e outras partes da sua extensão. No momento, isso pode ser feito usando sendMessage() e implementando chrome.runtime.onMessage no worker de serviço da extensão. A longo prazo, planeje substituir essas chamadas por postMessage() e um gerenciador de eventos de mensagem de um worker de serviço.

Substituir APIs sem suporte

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