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 deInjectDetails
. Há várias diferenças entre as duas. Por exemplo, otabId
agora é transmitido como membro deScriptInjection.target
em vez de como 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'] });
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 deInjectDetails
. - O
tabId
agora é transmitido como membro deCSSInjection.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 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"
.
{ ... "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 Manifest 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á-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.
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 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 |