Questa guida è incentrata sulle modifiche non compatibili introdotte nella versione 4 di Workbox, con esempi delle modifiche da apportare durante l'upgrade dalla versione 3 di Workbox.
Modifiche che provocano un errore
workbox-precaching
La convenzione di denominazione per le voci prememorizzate nella cache è stata aggiornata. Per le voci i cui URL necessitano di informazioni di revisione (ovvero quelle che contengono un campo revision nel manifest della pre-cache), queste informazioni sul controllo delle versioni verranno archiviate come parte della chiave cache, in uno speciale parametro di query dell'URL __WB_REVISION__ aggiunto all'URL originale. In precedenza, queste informazioni venivano archiviate separatamente dalle chiavi della cache utilizzando IndexedDB.
Gli sviluppatori che sfruttano la memorizzazione nella cache tramite workbox.precaching.precacheAndRoute(), che è il caso d'uso più comune, non devono apportare alcuna modifica alla configurazione del service worker; dopo l'upgrade a Workbox v4, gli asset memorizzati nella cache degli utenti verranno automaticamente migrati al nuovo formato della chiave cache e, in futuro, le risorse pre-memorizzate nella cache continueranno a essere pubblicate come prima.
Utilizzo diretto delle chiavi di cache
Alcuni sviluppatori potrebbero dover accedere direttamente alle voci di precache, al di fuori del contesto di workbox.precaching.precacheAndRoute(). Ad esempio, potresti precache un'immagine che poi utilizzerai come risposta "di riserva" quando non è possibile recuperare un'immagine effettiva dalla rete.
Se utilizzi gli asset prememorizzati in questo modo, a partire da Workbox v4, dovrai eseguire un passaggio aggiuntivo per tradurre un URL originale nella chiave cache corrispondente che può essere utilizzata per leggere la voce memorizzata nella cache. A questo scopo, chiama workbox.precaching.getCacheKeyForURL(originURL).
Ad esempio, se sai che 'fallback.png' è prememorizzato nella cache:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Pulisci i vecchi dati prememorizzati nella cache
Le modifiche apportate alla pre-memorizzazione nella cache in Workbox v4 significano che le pre-cache più vecchie, create da versioni precedenti di Workbox, non sono compatibili. Per impostazione predefinita, vengono lasciate invariate e, se esegui l'upgrade dalla versione 3 a quella 4 di Workbox, avrai due copie di tutte le risorse pre-cache.
Per evitare che questo accada, puoi aggiungere una chiamata a workbox.precaching.cleanupOutdatedCaches() direttamente ai service worker oppure impostare la nuova opzione cleanupOutdatedCaches: true se utilizzi uno strumento di creazione in modalità GenerateSW. Poiché la logica di pulizia della cache opera sulle convenzioni di denominazione della cache per trovare precache meno recenti e poiché gli sviluppatori hanno la possibilità di ignorare queste convenzioni, abbiamo preferito la cautela e non l'abbiamo attivata per impostazione predefinita.
Invitiamo gli sviluppatori che riscontrano problemi durante l'utilizzo di questa funzionalità, ad esempio falsi positivi relativi all'eliminazione, a comunicarcelo.
Maiuscole dei parametri
Due parametri facoltativi che possono essere passati a workbox.precaching.precacheAndRoute() e workbox.precaching.addRoute() sono stati rinominati per standardizzare la convenzione di utilizzo delle maiuscole. ignoreUrlParametersMatching è diventato ignoreURLParametersMatching e cleanUrls è diventato cleanURLs.
strategie-workbox
Esistono due modi approssimativamente equivalenti per creare un'istanza di un gestore in workbox-strategies. Stiamo ritirando il metodo factory a favore della chiamata esplicita del costruttore della strategia.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
Sebbene la sintassi del metodo di fabbrica continuerà a funzionare nella versione 4, il suo utilizzo registrerà un avviso e invitiamo gli sviluppatori a eseguire la migrazione prima della rimozione del supporto nella futura release 5.
workbox-background-sincronizzazione
La classe workbox.backgroundSync.Queue è stata riscritta per offrire agli sviluppatori maggiore flessibilità e controllo sul modo in cui le richieste vengono aggiunte alla coda e riprodotte.
Nella versione 3, la classe Queue aveva un unico modo per aggiungere richieste alla coda (il metodo addRequest()), ma non aveva alcun modo per modificare la coda o rimuovere le richieste.
Nella versione 4, il metodo addRequests() è stato rimosso e sono stati aggiunti i seguenti metodi simili agli array:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Nella versione 3, la classe Queue accettava anche diversi callback che consentivano di osservare quando le richieste venivano riprodotte (requestWillEnqueue, requestWillReplay, queueDidReplay), ma la maggior parte degli sviluppatori ha riscontrato che, oltre all'osservazione, voleva avere il controllo sul modo in cui la coda veniva riprodotta, inclusa la possibilità di modificare, riordinare o addirittura annullare dinamicamente le singole richieste.
Nella versione 4, questi callback sono stati rimossi a favore di un singolo callback onSync, che viene richiamato ogni volta che il browser tenta di riprodurre di nuovo. Per impostazione predefinita, il callback onSync richiama replayRequests(), ma se hai bisogno di un maggiore controllo sul processo di ripetizione, puoi utilizzare i metodi di tipo array sopra elencati per riprodurre la coda come preferisci.
Ecco un esempio di logica di ripetizione personalizzata:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
Analogamente, la classe workbox.backgroundSync.Plugin accetta gli stessi argomenti della classe Queue (poiché crea un'istanza Queue internamente), quindi è cambiata nello stesso modo.
scadenza casella di lavoro
Il pacchetto npm è stato rinominato workbox-expiration, in base alla convenzione di denominazione utilizzata per gli altri moduli. Questo pacchetto è funzionalmente equivalente al precedente pacchetto workbox-cache-expiration, che ora è deprecato.
workbox-broadcast-update
Il pacchetto npm è stato rinominato workbox-broadcast-update, in linea con la convenzione di denominazione utilizzata per gli altri moduli. Questo pacchetto è funzionalmente equivalente al precedente pacchetto workbox-broadcast-cache-update, che ora è deprecato.
workbox-core
In Workbox 3 la modalità dettagliata dei livelli di log poteva essere controllata tramite il metodo workbox.core.setLogLevel(), a cui veniva passato uno dei valori dell'enum workbox.core.LOG_LEVELS. Puoi anche leggere l'attuale livello di log tramite workbox.core.logLevel.
In Workbox 4, tutti questi parametri sono stati rimossi perché tutti gli strumenti per sviluppatori moderni ora sono dotati di funzionalità di filtro dei log avanzate (vedi Filtro dell'output della console per gli Strumenti per sviluppatori di Chrome).
workbox-sw
Due metodi che in precedenza erano esposti direttamente nello spazio dei nomi workbox (che corrisponde al modulo workbox-sw) sono stati spostati in workbox.core. workbox.skipWaiting() è diventato workbox.core.skipWaiting() e, analogamente, workbox.clientsClaim() è diventato workbox.core.clientsClaim().
Configurazione dello strumento di compilazione
La denominazione di alcune opzioni che possono essere passate a workbox-cli, workbox-build o workbox-webpack-plugin è cambiata. Ogni volta che "Url" veniva utilizzato nel nome di un'opzione, è stato ritirato a favore di "URL". Ciò significa che è preferibile utilizzare i seguenti nomi di opzioni:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variante "Url" di questi nomi di opzione funziona ancora nella versione 4, ma verrà visualizzato un messaggio di avviso. Consigliamo agli sviluppatori di eseguire la migrazione prima del rilascio della versione 5.
Nuova funzionalità
workbox-window
Il nuovo modulo workbox-window semplifica la procedura di registrazione e rilevamento degli aggiornamenti dei worker di servizio e fornisce un mezzo di comunicazione standard tra il codice in esecuzione nel worker di servizio e il codice in esecuzione nel contesto window dell'app web.
L'utilizzo di workbox-window è facoltativo, ma ci auguriamo che gli sviluppatori lo trovino utile e valutano la possibilità di migrare parte della loro logica scritta a mano per usarla quando appropriato. Puoi scoprire di più sull'utilizzo di workbox-window nella guida del modulo.
Migrazione di esempio
Un esempio di migrazione reale da Workbox v3 a v4 è disponibile in questa richiesta pull.
Richiesta di aiuto
Prevediamo che la maggior parte delle migrazioni sia semplice. Se riscontri problemi non trattati in questa guida, comunicacelo aprendo un problema su GitHub.