Aggiorna il codice

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 non correlate ad altri problemi. Le due sezioni successive riguardano la sostituzione del blocco delle richieste web e l'ottimizzazione della sicurezza.

Sostituisci tabs.executeScript() con scripting.executeScript()

In Manifest V3, executeScript() passa dall'API tabs all'API scripting. Sono necessarie modifiche alle autorizzazioni del file manifest, oltre alle effettive modifiche al codice.

Per il metodo executeScript() ti servono:

  • L'autorizzazione "scripting".
  • Autorizzazioni host o "activeTab".

Il metodo scripting.executeScript() è simile a come funzionava con tabs.executeScript(). Esistono alcune differenze.

  • Mentre il vecchio metodo accettava solo un singolo file, il nuovo metodo può utilizzare un array di file.
  • Passi anche un oggetto ScriptInjection anziché InjectDetails. Ci sono molte differenze tra i due. Ad esempio, tabId viene ora passato come membro di ScriptInjection.target anziché come argomento del metodo.

L'esempio mostra come eseguire questa operazione.

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

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

In un file di script in background.

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

chrome.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().

In Manifest V3, insertCSS() e removeCSS() passano dall'API tabs all'API scripting. Sono necessarie modifiche alle autorizzazioni del file manifest, oltre a modifiche al codice:

  • L'autorizzazione "scripting".
  • Autorizzazioni host o "activeTab".

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

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

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

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

In un file di script in background.

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

Nel service worker dell'estensione.

Sostituisci le azioni del browser e le azioni pagina con le azioni

Le azioni del browser e le azioni nelle pagine erano concetti separati in Manifest V2. Anche se hanno iniziato con ruoli distinti, le differenze tra i vari ruoli sono diminuiti nel tempo. In Manifest V3, questi concetti vengono consolidati nell'API Action. Sono richieste modifiche al manifest.json e al 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 sulle pagine, puoi emularle utilizzando contenuti dichiarativi o chiamare enable() o disable() con un ID scheda.

Sostituisci "browser_action" e "page_action" con "action"

Nel 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

Se Manifest V2 utilizzava le API browserAction e pageAction, ora dovresti usare l'API action.

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

Sostituisci i callback con le promesse

In Manifest V3, molti metodi dell'API di estensione restituiscono promesse. Una promessa è un proxy o un segnaposto per un valore restituito da un metodo asincrono. Se non hai mai utilizzato Promises, puoi scoprire di più su MDN. In questa pagina viene descritto ciò che devi sapere per utilizzarli in un'estensione di Chrome.

Per garantire la compatibilità con le versioni precedenti, dopo aver aggiunto il supporto delle promesse, molti metodi continuano a supportare i callback. Tieni presente che non puoi utilizzare entrambe nella stessa chiamata funzione. Se passi un callback, la funzione non restituisce una promessa e se desideri che venga restituita una promessa, non devi farla. Alcune funzionalità dell'API, ad esempio i listener di eventi, continueranno a richiedere callback. Per verificare se un metodo supporta le promesse, cerca l'etichetta "Promise" nel riferimento API.

Per convertire da una richiamata 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 con asincroni e in attesa.

Richiamata
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promessa
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 Manifest V2

Altri contesti delle estensioni possono interagire solo con i Service worker delle estensioni utilizzando la trasmissione di messaggi. Di conseguenza, dovrai sostituire le chiamate che prevedono un contesto di background, 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. Attualmente 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 un gestore di eventi di messaggi del 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, usa 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.onRequest
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 supportata nei service worker delle estensioni. 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