Questa guida si concentra sulle modifiche che provocano un errore introdotte in Workbox v4, con esempi delle modifiche che dovresti apportare quando esegui l'upgrade da Workbox v3.
Modifiche che provocano un errore
pre-memorizzazione nella cache di lavoro
La convenzione di denominazione per le voci prememorizzate nella cache è stata aggiornata. Ora, per le voci i cui URL richiedono informazioni sulla revisione (ovvero le voci che contengono un campo revision nel manifest precache), 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 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 modifiche alla configurazione del service worker; in seguito all'upgrade a Workbox v4, gli asset memorizzati nella cache degli utenti verranno migrati automaticamente 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 cache
Alcuni sviluppatori potrebbero dover accedere direttamente alle voci di pre-cache, al di fuori del contesto di workbox.precaching.precacheAndRoute(). Ad esempio, puoi pre-memorizzare nella cache un'immagine che finisci per utilizzare come risposta di "riserva" quando non è possibile recuperare un'immagine effettiva dalla rete.
Se utilizzi gli asset pre-memorizzati nella cache in questo modo, a partire da Workbox v4 dovrai eseguire un passaggio aggiuntivo per tradurre un URL originale nella chiave cache corrispondente, che potrà essere utilizzata per leggere la voce memorizzata nella cache. Per farlo, chiama il numero 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...
}
});
Pulizia di vecchi dati prememorizzati nella cache
Le modifiche apportate alla pre-cache in Workbox v4 indicano che le pre-cache meno recenti, create dalle versioni precedenti di Workbox, non sono compatibili. Per impostazione predefinita, vengono lasciate così com'è e, se esegui l'upgrade da Workbox v3 a Workbox v4, riceverai due copie di tutte le risorse pre-memorizzate nella cache.
Per evitare che questo accada, puoi aggiungere la chiamata a workbox.precaching.cleanupOutdatedCaches() direttamente ai service worker oppure puoi impostare la nuova opzione cleanupOutdatedCaches: true se utilizzi uno strumento di creazione in modalità GenerateSW. Poiché la logica di pulizia della cache opera in base a convenzioni di denominazione della cache per trovare le pre-cache meno recenti e gli sviluppatori hanno la possibilità di ignorare queste convenzioni, siamo andati per sicurezza e non abbiamo attivato questa funzionalità per impostazione predefinita.
Invitiamo gli sviluppatori che riscontrano problemi durante l'utilizzo di questa tecnologia, ad esempio falsi positivi relativi all'eliminazione, a comunicarcelo.
Lettere maiuscole dei parametri
Due parametri facoltativi che possono essere trasmessi a workbox.precaching.precacheAndRoute() e workbox.precaching.addRoute() sono stati rinominati per standardizzare la nostra convenzione generale sull'uso delle lettere maiuscole. ignoreUrlParametersMatching ora è ignoreURLParametersMatching e cleanUrls ora è cleanURLs.
strategie-workbox
Esistono due modi circa equivalenti per creare un'istanza di un gestore in workbox-strategies. Stiamo ritirando il metodo di produzione per favorire il richiamo esplicito 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({...});
Anche se la sintassi del metodo di fabbrica continuerà a funzionare nella versione 4, il suo utilizzo registrerà un avviso; invitiamo gli sviluppatori a eseguire la migrazione prima di rimuovere il supporto nella versione futura v5.
casella di lavoro-sincronizzazione-in-fondo
La classe workbox.backgroundSync.Queue è stata riscritta per offrire agli sviluppatori maggiore flessibilità e controllo sulle modalità con cui le richieste vengono aggiunte alla coda e riprodotte.
Nella versione 3, la classe Queue offriva un solo modo per aggiungere richieste alla coda (il metodo addRequest()), ma non per modificare la coda o rimuovere le richieste.
Nella versione 4, il metodo addRequests() è stato rimosso e sono stati aggiunti i seguenti metodi simili a un 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). Tuttavia, la maggior parte degli sviluppatori voleva controllare le modalità di riproduzione della coda, oltre all'osservazione, per poter modificare, riordinare o addirittura annullare in modo dinamico 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 effettua un tentativo di riproduzione. Per impostazione predefinita, il callback onSync richiama replayRequests(), ma se hai bisogno di un maggiore controllo sul processo di riproduzione, puoi utilizzare i metodi array elencati sopra 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), pertanto è cambiata nello stesso modo.
scadenza workstation
Il pacchetto npm è stato rinominato workbox-expiration, seguendo la convenzione di denominazione utilizzata per altri moduli. Questo pacchetto è equivalente al precedente pacchetto workbox-cache-expiration, che ora è deprecato.
aggiornamento-casella-di-lavoro
Il pacchetto npm è stato rinominato workbox-broadcast-update, seguendo la convenzione di denominazione utilizzata per altri moduli. Questo pacchetto è equivalente al precedente pacchetto workbox-broadcast-cache-update, che ora è deprecato.
Workbox Core
In Workbox v3, il livello di dettaglio dei livelli di log può essere controllato tramite il metodo workbox.core.setLogLevel(), che indicheresti uno dei valori nell'enumerazione workbox.core.LOG_LEVELS. Puoi anche leggere l'attuale livello di log tramite workbox.core.logLevel.
In Workbox v4, tutte queste funzionalità sono state rimosse perché tutti i moderni strumenti per sviluppatori ora dispongono di funzionalità avanzate di filtro dei log (vedi Filtro dell'output della console per Chrome Dev Tools).
Workbox-sw
Due metodi che in precedenza erano esposti direttamente nello spazio dei nomi workbox (che corrisponde al modulo workbox-sw) sono stati invece spostati in workbox.core. workbox.skipWaiting() è diventato workbox.core.skipWaiting() e, allo stesso modo, workbox.clientsClaim() è diventato workbox.core.clientsClaim().
Configurazione strumento di creazione
La denominazione di alcune opzioni che possono essere trasmesse all'interfaccia a riga di comando di workbox-cli, a workbox-build o a workbox-webpack-plugin è cambiata. Ogni volta che "URL" veniva utilizzato nel nome di un'opzione, verrà ritirato e sostituito con "URL". Ciò significa che sono preferibili i seguenti nomi di opzioni:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variante "URL" di questi nomi di opzioni funziona ancora nella versione 4, ma comporterà un messaggio di avviso. Invitiamo gli sviluppatori a eseguire la migrazione prima della release v5.
Nuova funzionalità
finestra-casella di lavoro
Il nuovo modulo workbox-window semplifica il processo di registrazione e di rilevamento degli aggiornamenti dei service worker e fornisce un mezzo di comunicazione standard tra il codice in esecuzione nel service worker e il codice in esecuzione nel contesto window della tua applicazione web.
L'utilizzo di workbox-window è facoltativo, ma ci auguriamo che gli sviluppatori lo trovino utile e valutano la possibilità di migrare parte della logica scritta a mano per utilizzarla quando opportuno. Per ulteriori informazioni sull'utilizzo di workbox-window, consulta la guida del modulo.
Migrazione di esempio
Un esempio di migrazione reale da Workbox v3 a v4 è disponibile in questa richiesta di pull.
Richiesta di aiuto
Prevediamo che la maggior parte delle migrazioni sia diretta. Se riscontri problemi non trattati in questa guida, comunicacelo aprendo un problema su GitHub.