Transizione allo spazio dei nomi del browser

A partire da Chrome 148, tutte le API delle estensioni di Chrome sono disponibili nello spazio dei nomi browser oltre a quello chrome esistente. Ad esempio, browser.tabs.create({}) e chrome.tabs.create({}) sono equivalenti.

Lo spazio dei nomi è disponibile ovunque tu possa chiamare le API delle estensioni, inclusi script di contenuti, service worker e documenti fuori schermo. Punta agli stessi oggetti API di chrome, quindi chrome.tabs === browser.tabs.

Lo spazio dei nomi browser è il risultato del lavoro del WebExtensions Community Group (WECG), un gruppo della community W3C in cui i fornitori di browser collaborano su standard di estensione condivisi. Lo spazio dei nomi chrome non verrà rimosso; entrambi gli spazi dei nomi continueranno a funzionare.

Decidere se adottare lo spazio dei nomi del browser

Se utilizzi webextension-polyfill, vai alla sezione Nota per gli utenti di polyfill prima di modificare qualsiasi altra cosa: la risposta è diversa per te.

Se stai creando una nuova estensione, imposta minimum_chrome_version su "148" e utilizza browser in modo incondizionato; puoi smettere di leggere qui. Il resto di questa sezione è dedicato alle estensioni esistenti che decidono come adottare.

Controllare le versioni di Chrome utilizzate dagli utenti

Se hai un'estensione esistente, controlla le versioni di Chrome in esecuzione dagli utenti prima di passare. Chrome si aggiorna automaticamente, ma alcuni utenti disattivano gli aggiornamenti e altri utilizzano dispositivi meno recenti che non possono eseguire l'ultima versione. Conferma con i tuoi dati di analisi. Se non hai ancora configurato Analytics yet, consulta Monitorare il rendimento dell'estensione con Google Analytics 4 per iniziare.

Da qui, scegli un percorso:

Adottare in modo incondizionato

Imposta minimum_chrome_version nel manifest e utilizza browser in modo incondizionato, senza bisogno di una protezione del runtime:

{
  "minimum_chrome_version": "148"
}

Utilizza un'implementazione graduale quando aumenti minimum_chrome_version. Se si verifica un problema, puoi eseguire il rollback dell'estensione nel Chrome Web Store.

Utilizzare la protezione del runtime

Aggiungi il seguente snippet all'inizio del codice di avvio dell'estensione prima di fare riferimento a browser in qualsiasi altro punto:

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

In questo modo, browser diventa un alias di chrome nelle versioni precedenti, quindi il resto del codice può utilizzare browser in modo incondizionato.

Nota per gli utenti di polyfill

Se l'estensione utilizza webextension-polyfill, diventa un'operazione no-op su Chrome 148 e versioni successive. Il polyfill ha saltato il wrapping quando browser era già definito, presupponendo che il browser host avesse già fornito l'API.

Un tentativo precedente di distribuire lo spazio dei nomi in Chrome 136 è stato sottoposto a rollback per questo motivo: con browser appena definito, il polyfill ha smesso di eseguire il wrapping, ma browser.runtime.onMessage di Chrome non supportava ancora i listener che restituiscono promesse, che il polyfill forniva. Le estensioni che si basano su questo pattern sono state interrotte. Chrome 148 distribuisce lo spazio dei nomi e i listener onMessage nativi che restituiscono promesse insieme per evitare questo divario.

Puoi rimuovere la dipendenza dal polyfill una volta che la tua base di utenti è passata a Chrome 148.

Altre funzionalità

Risposte asincrone in runtime.sendMessage

In Chrome 148, i listener runtime.onMessage possono restituire direttamente una Promise per inviare una risposta asincrona. Questa operazione funziona sia se la chiami utilizzando chrome.* sia browser.*.

In precedenza, l'unico modo per rispondere in modo asincrono era restituire un valore letterale true dal listener e chiamare sendResponse in un secondo momento:

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

Ora puoi restituire direttamente una Promise (o utilizzare una funzione async):

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

Il pattern return true continua a funzionare, quindi non è necessario modificare il codice esistente.