Aggiorna il codice

Aggiornamenti non correlati ad altri problemi

Questa è la prima delle tre sezioni che descrivono le modifiche necessarie al 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 illustrano la sostituzione del blocco delle richieste web e il miglioramento della sicurezza.

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

In Manifest V3, executeScript() passa dall'API tabs all'API scripting. Ciò richiede modifiche alle autorizzazioni nel file manifest, oltre a modifiche effettive al codice.

Per il metodo executeScript() ti serve:

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

Il metodo scripting.executeScript() è simile al suo funzionamento con tabs.executeScript(). Esistono alcune differenze.

  • Mentre il vecchio metodo poteva accettare un solo file, il nuovo metodo può accettare un array di file.
  • Puoi passare anche un oggetto ScriptInjection invece di InjectDetails. Esistono molte differenze tra i due. Ad esempio, tabId viene ora passato come membro di ScriptInjection.target anziché come argomento di 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 richieste modifiche alle autorizzazioni nel file manifest, oltre a modifiche al codice:

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

Le funzioni nell'API scripting sono simili a quelle su 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 Azioni browser e Azioni pagina con azioni

Le azioni del browser e quelle sulle pagine erano concetti separati in Manifest V2. Sebbene abbiano 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 al codice dell'estensione diversi da quelle 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 nella pagina, puoi emularle utilizzando contenuti dichiarativi o chiamare enable() o disable() con un ID scheda.

Sostituisci "browser_action" e "page_action" con "azione"

Nel campo manifest.json, sostituisci i campi "browser_action" e "page_action" con il campo "action". Consulta il riferimento per le 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 il file Manifest V2 utilizzava le API browserAction e pageAction, ora devi 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 le promesse, puoi leggere informazioni in merito su MDN. In questa pagina viene descritto ciò che devi sapere per utilizzarle in un'estensione di Chrome.

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

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

Richiamata
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promesso
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 di estensioni possono interagire con i service worker di estensioni solo tramite la trasmissione dei messaggi. Di conseguenza, dovrai sostituire le chiamate che prevedono un contesto in background, in particolare:

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

Gli script delle estensioni devono utilizzare la trasmissione di messaggi per comunicare tra un service worker e altre parti dell'estensione. Al momento è possibile farlo utilizzando sendMessage() e implementando chrome.runtime.onMessage nel service worker delle estensioni. A lungo termine, dovresti pianificare la sostituzione di queste chiamate con postMessage() e con il gestore di eventi dei 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à del file 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 Dove 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 supportata nei service worker di estensione. Utilizza invece l'evento del 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