Aggiorna il codice

Aggiornamenti non correlati ad altri problemi

Questa è la prima di tre sezioni che descrivono le modifiche necessarie per il codice che non fa parte del service worker dell'estensione. Questa sezione è dedicata alle modifiche al codice richieste 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 tabs.executeScript() con scripting.executeScript()

Nel manifest V3, executeScript() passa dall'API tabs all'API scripting. Oltre alle modifiche al codice, sono necessarie modifiche alle autorizzazioni nel file manifest.

Per il metodo executeScript(), hai bisogno di:

  • L'autorizzazione "scripting".
  • Le autorizzazioni host o l'autorizzazione "activeTab".

Il metodo scripting.executeScript() è simile a quello utilizzato con tabs.executeScript(). Esistono alcune differenze.

  • Mentre il vecchio metodo poteva accettare un solo file, il nuovo metodo può accettare un array di file.
  • Inoltre, passi un oggetto ScriptInjection anziché InjectDetails. Esistono diverse differenze tra i due. Ad esempio, tabId ora viene passato come membro di ScriptInjection.target anziché come argomento del metodo.

L'esempio mostra come fare.

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

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

In un file di script di sfondo.

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

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

Nel service worker dell'estensione.

Sostituisci tabs.insertCSS() e tabs.removeCSS() con scripting.insertCSS() e scripting.removeCSS()

Nel manifest V3, insertCSS() e removeCSS() vengono spostati dall'API tabs all'API scripting. Oltre alle modifiche al codice, sono necessarie modifiche alle autorizzazioni nel file manifest:

  • L'autorizzazione "scripting".
  • Le autorizzazioni host o l'autorizzazione "activeTab".

Le funzioni dell'API scripting sono simili a quelle di tabs. Esistono alcune differenze.

  • Quando chiami questi metodi, passi un oggetto CSSInjection anziché InjectDetails.
  • tabId ora viene passato come membro di CSSInjection.target anziché come argomento del metodo.

L'esempio mostra come farlo per insertCSS(). La procedura per removeCSS() è la stessa.

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

In un file di script di sfondo.

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

Nel service worker dell'estensione.

Sostituisci Azioni browser e Azioni pagina con Azioni

Le azioni del browser e le azioni della pagina erano concetti separati in Manifest V2. Sebbene inizialmente avessero ruoli distinti, le differenze tra loro sono diminuite nel tempo. In Manifest V3, questi concetti sono raggruppati nell'API Action. Ciò richiede modifiche al codice manifest.json e dell'estensione diverse da quelle che avresti inserito nello script di sfondo di Manifest V2.

Le azioni in Manifest V3 assomigliano molto alle azioni del browser; tuttavia, l'API action non fornisce hide() e show() come faceva pageAction. Se hai ancora bisogno delle 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"

In manifest.json, sostituisci i campi "browser_action" e "page_action" con il campo "action". Consulta il riferimento per informazioni sul campo "action".

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Sostituisci le API browserAction e pageAction con l'API action

Dove Manifest V2 utilizzava le API browserAction e pageAction, ora devi utilizzare l'API action.

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
browser.action.onClicked.addListener(tab => { ... });

Sostituisci i callback con le promesse

In Manifest V3, molti metodi API delle estensioni restituiscono promesse. Una promessa è un proxy o un segnaposto per un valore restituito da un metodo asincrono. Se non hai mai utilizzato le promesse, puoi scoprirne di più su MDN. Questa pagina descrive ciò che devi sapere per utilizzarli in un'estensione di Chrome.

Per la compatibilità con le versioni precedenti, molti metodi continuano a supportare i callback dopo l'aggiunta del supporto delle promesse. Tieni presente che non puoi utilizzarli entrambi nella stessa chiamata di funzione. Se passi un callback, la funzione non restituirà una promessa e, se vuoi che venga restituita una promessa, non passare un callback. Alcune funzionalità API, come i listener di eventi, continueranno a richiedere callback. Per verificare se un metodo supporta le promesse, cerca l'etichetta "Promise" nel relativo riferimento API.

Per convertire un callback in una promessa, rimuovi il callback e gestisci la promessa restituita. L'esempio riportato di seguito è tratto dall'esempio di autorizzazioni facoltative, in particolare newtab.js. La versione di callback mostra come sarebbe la chiamata dell'esempio a request() con un callback. Tieni presente che la versione della promessa potrebbe essere riscritta con async e await.

Richiamata
browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promessa
const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Sostituisci le funzioni che prevedono un contesto in background di Manifest V2

Altri contesti di estensione possono interagire con i service worker dell'estensione solo tramite il passaggio di messaggi. Di conseguenza, dovrai sostituire le chiamate che prevedono un contesto in background, in particolare:

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

Gli script delle estensioni devono utilizzare il passaggio di messaggi per comunicare tra un service worker e altre parti dell'estensione. Al momento, questa operazione può essere eseguita utilizzando sendMessage() e implementando browser.runtime.onMessage nel service worker dell'estensione. A lungo termine, dovresti pianificare di sostituire queste chiamate con postMessage() e un 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
browser.extension.connect() browser.runtime.connect()
browser.extension.connectNative() browser.runtime.connectNative()
browser.extension.getExtensionTabs() browser.extension.getViews()
browser.extension.getURL() browser.runtime.getURL()
browser.extension.lastError Se i metodi restituiscono promesse, utilizza promise.catch()
browser.extension.onConnect browser.runtime.onConnect
browser.extension.onConnectExternal browser.runtime.onConnectExternal
browser.extension.onMessage browser.runtime.onMessage
browser.extension.onRequest browser.runtime.onMessage
browser.extension.onRequestExternal browser.runtime.onMessageExternal
browser.extension.sendMessage() browser.runtime.sendMessage()
browser.extension.sendNativeMessage() browser.runtime.sendNativeMessage()
browser.extension.sendRequest() browser.runtime.sendMessage()
browser.runtime.onSuspend (script in background) Non supportato nei service worker delle estensioni. Utilizza invece l'evento del documento beforeunload.
browser.tabs.getAllInWindow() browser.tabs.query()
browser.tabs.getSelected() browser.tabs.query()
browser.tabs.onActiveChanged browser.tabs.onActivated
browser.tabs.onHighlightChanged browser.tabs.onHighlighted
browser.tabs.onSelectionChanged browser.tabs.onActivated
browser.tabs.sendRequest() browser.runtime.sendMessage()
browser.tabs.Tab.selected browser.tabs.Tab.highlighted