Aggiornamenti non correlati ad altri problemi
Questa è la prima delle tre sezioni che descrivono le modifiche necessarie per il codice che non fa parte del service worker dell'estensione. Questa sezione riguarda le modifiche obbligatorie al codice che non sono correlate ad altri problemi. Le due sezioni successive riguardano la sostituzione del blocco delle richieste web e il miglioramento della sicurezza.
Sostituisci tabulazioni.executeScript() con scripting.executeScript()
In Manifest V3, l'elemento executeScript()
passa dall'API tabs
all'API scripting
. Ciò richiede delle modifiche alle autorizzazioni nel file manifest, oltre alle effettive modifiche al codice.
Per il metodo executeScript()
hai bisogno di:
- L'autorizzazione
"scripting"
. - Occorre concedere le autorizzazioni dell'host o l'autorizzazione
"activeTab"
.
Il metodo scripting.executeScript()
è simile al funzionamento con tabs.executeScript()
. Esistono alcune differenze.
- Mentre il metodo precedente era in grado di utilizzare solo un singolo file, il nuovo metodo può utilizzare un array di file.
- Passi anche un oggetto
ScriptInjection
anzichéInjectDetails
. Ci sono diverse differenze tra i due. Ad esempio,tabId
ora viene passato come membro diScriptInjection.target
anziché come argomento di metodo.
L'esempio mostra come eseguire questa operazione.
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'] });
Sostituisci tabulazioni.insertCSS() e tabs.removeCSS() con scripting.insertCSS() e scripting.removeCSS().
In Manifest V3, insertCSS()
e removeCSS()
passano dall'API tabs
all'API scripting
. Sono necessarie modifiche alle autorizzazioni nel file manifest, oltre a modifiche al codice:
- L'autorizzazione
"scripting"
. - Occorre concedere le autorizzazioni dell'host o l'autorizzazione
"activeTab"
.
Le funzioni nell'API scripting
sono simili a quelle dell'API tabs
. Esistono alcune differenze.
- Quando chiami questi metodi, passi un oggetto
CSSInjection
anzichéInjectDetails
. tabId
viene ora passato come membro diCSSInjection.target
anziché come argomento di metodo.
L'esempio mostra come eseguire questa operazione per insertCSS()
. La procedura per removeCSS()
è la stessa.
chrome.tabs.insertCSS(tabId, injectDetails, () => { // callback code });
const insertPromise = await chrome.scripting.insertCSS({ files: ["style.css"], target: { tabId: tab.id } }); // Remaining code.
Sostituisci Azioni del browser e Azioni pagina con Azioni
Le azioni del browser e le azioni sulle pagine erano concetti separati in Manifest V2. Anche se hanno iniziato con ruoli distinti, le differenze tra loro sono diminuite nel tempo. In Manifest V3, questi concetti vengono consolidati nell'API Action. Sono necessarie modifiche in manifest.json
e nel codice dell'estensione diverso da quello che avresti inserito nello script in background di Manifest V2.
Le azioni in Manifest V3 sono molto simili a quelle del browser; tuttavia, l'API action
non fornisce hide()
e show()
come ha fatto pageAction
. Se hai ancora bisogno di azioni sulla pagina, puoi emularle utilizzando contenuti dichiarativi o chiamare enable()
o disable()
con un ID scheda.
Sostituisci "browser_action" e "page_action" con "action"
Nel campo manifest.json
, sostituisci i campi "browser_action"
e "page_action"
con il campo "action"
. Consulta il riferimento per informazioni sul campo "action"
.
{ ... "page_action": { ... }, "browser_action": { "default_popup": "popup.html" } ... }
{ ... "action": { "default_popup": "popup.html" } ... }
Sostituisci le API browserAction e pageAction con l'API action
Se il file Manifest V2 utilizzava le API browserAction
e pageAction
, ora dovresti usare l'API action
.
chrome.browserAction.onClicked.addListener(tab => { ... }); chrome.pageAction.onClicked.addListener(tab => { ... });
chrome.action.onClicked.addListener(tab => { ... });
Sostituisci i callback con le promesse
In Manifest V3, molti metodi dell'API delle estensioni restituiscono promesse. Un promise è un proxy o un segnaposto per un valore restituito da un metodo asincrono. Se non hai mai utilizzato Promises, puoi leggere informazioni su di loro su MDN. In questa pagina viene spiegato ciò che devi sapere per utilizzarli in un'estensione di Chrome.
Per garantire la compatibilità con le versioni precedenti, molti metodi continuano a supportare i callback dopo aver aggiunto il supporto delle promesse. Ricorda che non puoi utilizzarli entrambi nella stessa chiamata di funzione. Se passi un callback, la funzione non restituirà una promessa e se desideri che venga restituita una promessa non devi passare il callback. Alcune funzionalità dell'API, come i listener di eventi, continueranno a richiedere callback. Per verificare se un metodo supporta le promesse, cerca l'etichetta "Promise" nel riferimento dell'API.
Per convertire da un callback a una promessa, rimuovi il callback e gestisci la promessa restituita. L'esempio seguente è tratto dall'esempio di autorizzazioni facoltative, in particolare newtab.js
. La versione di callback mostra l'aspetto della chiamata del campione a request()
con un callback. Tieni presente che la versione promessa potrebbe essere riscritta in modo asincrono e attendere.
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'); } });
Sostituisci le funzioni che prevedono un contesto in background in Manifest V2
Altri contesti delle estensioni possono interagire solo con i service worker dell'estensione utilizzando la trasmissione di messaggi. Di conseguenza, dovrai sostituire le chiamate che richiedono un contesto di base, in particolare:
chrome.runtime.getBackgroundPage()
chrome.extension.getBackgroundPage()
chrome.extension.getExtensionTabs()
Gli script delle estensioni devono utilizzare la trasmissione dei messaggi per comunicare tra un service worker e altre parti dell'estensione. Al momento ciò comporta l'utilizzo di sendMessage()
e l'implementazione di chrome.runtime.onMessage
nel service worker dell'estensione. A lungo termine, dovresti pianificare di sostituire queste chiamate con postMessage()
e con il gestore di eventi di messaggi di un service worker.
Sostituisci le API non supportate
I metodi e le proprietà elencati di seguito devono essere modificati in Manifest V3.
Metodo o proprietà Manifest V2 | Sostituisci con |
---|---|
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 |
Se i metodi restituiscono promesse, utilizza 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 (script in background) |
Non supportato nei service worker dell'estensione. Utilizza invece l'evento 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 |