Gestire gli eventi con i service worker

Tutorial che illustra i concetti del service worker di estensione

Panoramica

Questo tutorial fornisce un'introduzione ai worker di servizio delle estensioni di Chrome. Nell'ambito di questo tutorial, creerai un'estensione che consente agli utenti di passare rapidamente alle pagine di riferimento dell'API di Chrome utilizzando la omnibox. Imparerai come:

• Registra il tuo service worker e importa i moduli.
• Esegui il debug del worker del servizio di estensione.
• Gestire lo stato e gli eventi.
• Attivare eventi periodici.
• Comunicare con gli script di contenuti.

Prima di iniziare

Questa guida presuppone che tu abbia esperienza di base nello sviluppo web. Ti consigliamo di consultare Estensioni 101 e Hello World per un'introduzione allo sviluppo delle estensioni.

Crea l'estensione

Per iniziare, crea una nuova directory denominata quick-api-reference per contenere i file di estensione o scarica il codice sorgente dal nostro repository di esempi GitHub.

Passaggio 1: registra il service worker

Crea il file manifest nella directory principale del progetto e aggiungi il seguente codice:

manifest.json:

{
  "manifest_version": 3,
  "name": "Open extension API reference",
  "version": "1.0.0",
  "icons": {
    "16": "images/icon-16.png",
    "128": "images/icon-128.png"
  },
  "background": {
    "service_worker": "service-worker.js"
  }
}

Le estensioni registrano il proprio service worker nel file manifest, che richiede un solo file JavaScript. Non è necessario chiamare navigator.serviceWorker.register(), come faresti in una pagina web.

Crea una cartella images, quindi scarica le icone al suo interno.

Consulta i primi passaggi del tutorial Tempo di lettura per scoprire di più sui metadati e sulle icone dell'estensione nel file manifest.

Passaggio 2: importa più moduli di worker di servizio

Il nostro service worker implementa due funzionalità. Per una migliore manutenibilità, implementeremo ciascuna funzionalità in un modulo separato. Innanzitutto, dobbiamo dichiarare il service worker come modulo ES nel nostro file manifest, che ci consente di importare moduli nel nostro service worker:

manifest.json:

{
 "background": {
    "service_worker": "service-worker.js",
    "type": "module"
  },
}

Crea il file service-worker.js e importa due moduli:

import './sw-omnibox.js';
import './sw-tips.js';

Crea questi file e aggiungi un log della console a ciascuno.

sw-omnibox.js:

console.log("sw-omnibox.js");

sw-tips.js:

console.log("sw-tips.js");

Consulta Importazione di script per scoprire altri modi per importare più file in un servizio worker.

Suggerimento: ricordati di impostare "type.module" quando utilizzi un framework di aggregazione dei moduli moderno, come il plug-in Vite di CRXjs.

(Facoltativo) Debug del service worker

Ti spiegherò come trovare i log del servizio worker e sapere quando è stato terminato. Innanzitutto, segui le istruzioni per caricare un'estensione non scompattata.

Dopo 30 secondi viene visualizzato il messaggio "service worker (inactive)", che indica che il service worker è stato terminato. Fai clic sul link "Service worker (non attivo)" per ispezionarlo. L'animazione seguente mostra l'immagine.

Hai notato che l'ispezione del service worker lo ha svegliato? L'apertura del service worker in DevTools lo manterrà attivo. Per assicurarti che l'estensione si comporti correttamente al termine del servizio worker, ricordati di chiudere DevTools.

Ora suddividi l'estensione per scoprire dove individuare gli errori. Un modo per farlo è eliminare ".js" dall'importazione './sw-omnibox.js' nel file service-worker.js. Chrome non potrà registrare il service worker.

Torna a chrome://extensions e aggiorna l'estensione. Visualizzerai due errori:

Service worker registration failed. Status code: 3.

An unknown error occurred when fetching the script.

Per scoprire altri modi per eseguire il debug del worker del servizio dell'estensione, consulta Eseguire il debug delle estensioni.

Attenzione: non dimenticare di correggere il nome file prima di procedere.

Passaggio 4: inizializza lo stato

Chrome arresterà i worker di servizio se non sono necessari. Utilizziamo l'API chrome.storage per mantenere lo stato nelle sessioni dei worker di servizio. Per accedere allo spazio di archiviazione, dobbiamo richiedere l'autorizzazione nel manifest:

manifest.json:

{
  ...
  "permissions": ["storage"],
}

Innanzitutto, salva i suggerimenti predefiniti nello spazio di archiviazione. Possiamo inizializzare lo stato al momento dell'installazione dell'estensione ascoltando l'evento runtime.onInstalled():

sw-omnibox.js:

...
// Save default API suggestions
chrome.runtime.onInstalled.addListener(({ reason }) => {
  if (reason === 'install') {
    chrome.storage.local.set({
      apiSuggestions: ['tabs', 'storage', 'scripting']
    });
  }
});

I worker di servizio non hanno accesso diretto all'oggetto window e pertanto non possono utilizzare window.localStorage per memorizzare i valori. Inoltre, i service worker sono ambienti di esecuzione di breve durata; vengono interrotti ripetutamente durante la sessione del browser di un utente, il che li rende incompatibili con le variabili globali. Utilizza invece chrome.storage.local, che memorizza i dati sulla macchina locale.

Per saperne di più sulle altre opzioni di archiviazione per i service worker di estensione, consulta l'articolo Persistere i dati anziché utilizzare le variabili globali.

Passaggio 5: registra i tuoi eventi

Tutti i listener di eventi devono essere registrati in modo statico nell'ambito globale del service worker. In altre parole, i listener di eventi non devono essere nidificati nelle funzioni asincrone. In questo modo, Chrome può assicurarsi che tutti i gestori degli eventi vengano ripristinati in caso di riavvio del servizio worker.

In questo esempio utilizzeremo l'API chrome.omnibox, ma prima dobbiamo dichiarare l'attivatore della parola chiave omnibox nel file manifest:

manifest.json:

{
  ...
  "minimum_chrome_version": "102",
  "omnibox": {
    "keyword": "api"
  },
}

Punto chiave: il riferimento "minimum_chrome_version" spiega il comportamento di questa chiave quando un utente tenta di installare la tua estensione, ma non utilizza una versione compatibile di Chrome.

Ora, registra gli ascoltatori di eventi dell'omnibox al livello superiore dello script. Quando l'utente inserisce la parola chiave omnibox (api) nella barra degli indirizzi seguita da una scheda o da uno spazio, Chrome mostra un elenco di suggerimenti basati sulle parole chiave nello spazio di archiviazione. L'evento onInputChanged(), che prende l'input dell'utente corrente e un oggetto suggestResult, è responsabile della compilazione di questi suggerimenti.

sw-omnibox.js:

...
const URL_CHROME_EXTENSIONS_DOC =
  'https://developer.chrome.com/docs/extensions/reference/';
const NUMBER_OF_PREVIOUS_SEARCHES = 4;

// Display the suggestions after user starts typing
chrome.omnibox.onInputChanged.addListener(async (input, suggest) => {
  await chrome.omnibox.setDefaultSuggestion({
    description: 'Enter a Chrome API or choose from past searches'
  });
  const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
  const suggestions = apiSuggestions.map((api) => {
    return { content: api, description: `Open chrome.${api} API` };
  });
  suggest(suggestions);
});

Dopo che l'utente ha selezionato un suggerimento, onInputEntered() aprirà la pagina di riferimento dell'API Chrome corrispondente.

sw-omnibox.js:

...
// Open the reference page of the chosen API
chrome.omnibox.onInputEntered.addListener((input) => {
  chrome.tabs.create({ url: URL_CHROME_EXTENSIONS_DOC + input });
  // Save the latest keyword
  updateHistory(input);
});

La funzione updateHistory() acquisisce l'input dell'omnibox e lo salva in storage.local. In questo modo, il termine di ricerca più recente può essere utilizzato in un secondo momento come suggerimento dell'omnibox.

sw-omnibox.js:

...
async function updateHistory(input) {
  const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
  apiSuggestions.unshift(input);
  apiSuggestions.splice(NUMBER_OF_PREVIOUS_SEARCHES);
  return chrome.storage.local.set({ apiSuggestions });
}

Punto chiave: i worker di servizio delle estensioni possono utilizzare sia le API web che le API di Chrome, con alcune eccezioni. Per ulteriori informazioni, consulta la sezione Eventi dei service worker.

Passaggio 6: configura un evento ricorrente

I metodi setTimeout() o setInterval() vengono comunemente utilizzati per eseguire attività ritardate o periodiche. Tuttavia, queste API possono non riuscire perché il programmatore annulla i timer al termine del servizio lavorare. Le estensioni possono invece utilizzare l'API chrome.alarms.

Inizia richiedendo l'autorizzazione "alarms" nel file manifest. Inoltre, per recuperare i suggerimenti per le estensioni da una posizione ospitata in remoto, devi richiedere l'autorizzazione host:

manifest.json:

{
  ...
  "permissions": ["storage"],
  "permissions": ["storage", "alarms"],
  "host_permissions": ["https://extension-tips.glitch.me/*"],
}

L'estensione recupererà tutti i suggerimenti, ne sceglierà uno a caso e lo salverà nello spazio di archiviazione. Creeremo una sveglia che verrà attivata una volta al giorno per aggiornare il suggerimento. Gli allarmi non vengono salvati quando chiudi Chrome. Dobbiamo quindi verificare se l'allarme esiste e crearlo se non è presente.

sw-tips.js:

// Fetch tip & save in storage
const updateTip = async () => {
  const response = await fetch('https://extension-tips.glitch.me/tips.json');
  const tips = await response.json();
  const randomIndex = Math.floor(Math.random() * tips.length);
  return chrome.storage.local.set({ tip: tips[randomIndex] });
};

const ALARM_NAME = 'tip';

// Check if alarm exists to avoid resetting the timer.
// The alarm might be removed when the browser session restarts.
async function createAlarm() {
  const alarm = await chrome.alarms.get(ALARM_NAME);
  if (typeof alarm === 'undefined') {
    chrome.alarms.create(ALARM_NAME, {
      delayInMinutes: 1,
      periodInMinutes: 1440
    });
    updateTip();
  }
}

createAlarm();

// Update tip once a day
chrome.alarms.onAlarm.addListener(updateTip);

Punto chiave: tutti i metodi e gli ascoltatori di eventi dell'API Chrome riavviano il timer di interruzione di 30 secondi del servizio worker. Per ulteriori informazioni, consulta il ciclo di vita dei worker di servizio delle estensioni.

Passaggio 7: comunica in altri contesti

Le estensioni utilizzano gli script di contenuti per leggere e modificare i contenuti della pagina. Quando un utente visita una pagina di riferimento dell'API di Chrome, lo script dei contenuti dell'estensione aggiorna la pagina con il suggerimento del giorno. Invia un messaggio per richiedere la mancia del giorno al service worker.

Inizia dichiarando lo script dei contenuti nel file manifest e aggiungi il pattern di corrispondenza corrispondente alla documentazione di riferimento dell'API Chrome.

manifest.json:

{
  ...
  "content_scripts": [
    {
      "matches": ["https://developer.chrome.com/docs/extensions/reference/*"],
      "js": ["content.js"]
    }
  ]
}

Crea un nuovo file di contenuti. Il codice seguente invia un messaggio al service worker che richiede il suggerimento. Aggiungi un pulsante che apra un popup contenente il suggerimento dell'estensione. Questo codice utilizza la nuova API Popup della piattaforma web.

content.js:

(async () => {
  // Sends a message to the service worker and receives a tip in response
  const { tip } = await chrome.runtime.sendMessage({ greeting: 'tip' });

  const nav = document.querySelector('.upper-tabs > nav');
  
  const tipWidget = createDomElement(`
    <button type="button" popovertarget="tip-popover" popovertargetaction="show" style="padding: 0 12px; height: 36px;">
      <span style="display: block; font: var(--devsite-link-font,500 14px/20px var(--devsite-primary-font-family));">Tip</span>
    </button>
  `);

  const popover = createDomElement(
    `<div id='tip-popover' popover style="margin: auto;">${tip}</div>`
  );

  document.body.append(popover);
  nav.append(tipWidget);
})();

function createDomElement(html) {
  const dom = new DOMParser().parseFromString(html, 'text/html');
  return dom.body.firstElementChild;
}

Il passaggio finale consiste nell'aggiungere al nostro service worker un gestore dei messaggi che invii una risposta allo script dei contenuti con il suggerimento giornaliero.

sw-tips.js:

...
// Send tip to content script via messaging
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.greeting === 'tip') {
    chrome.storage.local.get('tip').then(sendResponse);
    return true;
  }
});

Verifica che funzioni

Verifica che la struttura del file del progetto sia la seguente:

Carica l'estensione localmente

Per caricare un'estensione non pacchettizzata in modalità sviluppatore, segui i passaggi descritti in Hello world.

Aprire una pagina di riferimento

1. Inserisci la parola chiave "api" nella barra degli indirizzi del browser.
2. Premi "Tab" o "Barra spaziatrice".
3. Inserisci il nome completo dell'API.
   • OPPURE scegli da un elenco di ricerche passate
4. Si aprirà una nuova pagina con il riferimento all'API Chrome.

Dovrebbe avere il seguente aspetto:

Estensione API rapida che apre l'API Runtime.

Aprire il suggerimento del giorno

Fai clic sul pulsante Suggerimento nella barra di navigazione per aprire il suggerimento dell'estensione.

Estensione API rapida che apre il suggerimento del giorno.

Nota: l'API Popover è stata lanciata in Chrome 114.

🎯 Potenziali miglioramenti

In base a quanto appreso oggi, prova a svolgere una delle seguenti attività:

• Scopri un altro modo per implementare i suggerimenti dell'omnibox.
• Crea la tua finestra modale personalizzata per visualizzare il suggerimento per l'estensione.
• Apri un'altra pagina delle pagine API di riferimento delle estensioni web di MDN.

Continua a costruire!

Complimenti per aver completato questo tutorial 🎉. Continua a migliorare le tue competenze completando altri tutorial per principianti:

Estensione	Cosa imparerai a fare
Tempo di lettura	Per inserire automaticamente un elemento in un insieme specifico di pagine.
Tabs Manager	Per creare un popup che gestisce le schede del browser.
Modalità Niente distrazioni	Per eseguire il codice nella pagina corrente dopo aver fatto clic sull'azione dell'estensione.

Continua a esplorare

Per continuare il tuo percorso di apprendimento degli addetti ai servizi di estensione, ti consigliamo di consultare i seguenti articoli:

• Informazioni sui service worker delle estensioni.
• Il ciclo di vita del Service worker delle estensioni.
• Eventi nei service worker