Questa guida si concentra sulle modifiche che provocano errori introdotte in Workbox v6, con esempi delle modifiche necessarie per eseguire l'upgrade da Workbox v5.
Modifiche che provocano un errore
core box di lavoro
Il metodo skipWaiting()
in workbox-core
non aggiungerà più un gestore install
ed equivale alla semplice chiamata di self.skipWaiting()
.
D'ora in poi, usa invece self.skipWaiting()
perché è probabile che skipWaiting()
venga rimosso in Workbox v7.
pre-memorizzazione nella cache della casella di lavoro
- Non è più possibile utilizzare i documenti HTML multiorigine per gli URL che corrispondono a un reindirizzamento HTTP per soddisfare una richiesta di navigazione con
workbox-precaching
. Questo scenario è generalmente raro. - Il parametro di query dell'URL
fbclid
ora viene ignorato daworkbox-precaching
quando si cerca una risposta pre-memorizzata nella cache per una determinata richiesta. - Il costruttore
PrecacheController
ora accetta un oggetto con proprietà specifiche come parametro, anziché una stringa. Questo oggetto supporta le seguenti proprietà:cacheName
(che serve lo stesso scopo della stringa passata al costruttore nella v5),plugins
(sostituisce il metodoaddPlugins()
dalla v5) efallbackToNetwork
(che sostituisce l'opzione simile passata acreateHandler()
e "createHandlerBoundToURL() nella v5). - I metodi
install()
eactivate()
diPrecacheController
ora utilizzano esattamente un parametro, che deve essere impostato rispettivamente su unInstallEvent
oActivateEvent
corrispondente. - Il metodo
addRoute()
è stato rimosso daPrecacheController
. Al suo posto, la nuova classePrecacheRoute
può essere utilizzata per creare un percorso che puoi quindi registrare. - Il metodo
precacheAndRoute()
è stato rimosso daPrecacheController
. Esiste ancora come metodo helper statico esportato dal moduloworkbox-precaching
. È stato rimosso perché è possibile utilizzarePrecacheRoute
. - Il metodo
createMatchCalback()
è stato rimosso daPrecacheController
. Puoi usare il nuovoPrecacheRoute
. - Il metodo
createHandler()
è stato rimosso daPrecacheController
. La proprietàstrategy
dell'oggettoPrecacheController
può essere utilizzata per gestire le richieste. - L'esportazione statica
createHandler()
è già stata rimossa dal moduloworkbox-precaching
. Al suo posto, gli sviluppatori dovrebbero creare un'istanzaPrecacheController
e utilizzare la relativa proprietàstrategy
. - Il percorso registrato con
precacheAndRoute()
ora è un percorso "reale" che utilizza la classeRouter
diworkbox-routing
. Se interfoli le chiamate aregisterRoute()
eprecacheAndRoute()
, questo potrebbe comportare un ordine di valutazione diverso dei tuoi percorsi.
routing-casella di lavoro
Il metodo setDefaultHandler()
ora richiede un secondo parametro facoltativo corrispondente al metodo HTTP a cui si applica, il cui valore predefinito è 'GET'
.
- Se utilizzi
setDefaultHandler()
e tutte le tue richieste sonoGET
, non devi apportare modifiche. - Se hai richieste diverse da
GET
(POST
,PUT
e così via),setDefaultHandler()
non farà più corrispondere queste richieste.
Configurazione build
L'opzione mode
per le modalità getManifest
e injectManifest
in workbox-build
e workbox-cli
non era destinata a essere supportata ed è stata rimossa. Non si applica a workbox-webpack-plugin
, che supporta mode
nel suo plug-in InjectManifest
.
Gli strumenti di creazione richiedono Node.js v10 o versioni successive
Le versioni di Node.js precedenti alla v10 non sono più supportate per workbox-webpack-plugin
, workbox-build
o workbox-cli
. Se esegui una versione di Node.js precedente alla v8, aggiorna il runtime a una versione supportata.
Nuovi miglioramenti
strategie-workbox
Workbox v6 introduce un nuovo modo per gli sviluppatori di terze parti per definire le proprie strategie Workbox. Questo assicura che gli sviluppatori di terze parti abbiano la possibilità di estendere Workbox in modi che soddisfano pienamente le loro esigenze.
Classe di base Nuova strategia
Nella versione 6, tutte le classi di strategia Workbox devono estendere la nuova classe base Strategy
. A questo scopo, sono state riscritte tutte le strategie integrate.
La classe base Strategy
è responsabile di due aspetti principali:
- Richiamo di callback del ciclo di vita dei plug-in comuni a tutti i gestori di strategie (ad es. quando iniziano, rispondono e terminano).
- Creazione di un'istanza "handler", in grado di gestire lo stato di ogni singola richiesta gestita da una strategia.
Nuova classe "handler"
In precedenza avevamo moduli interni chiamati fetchWrapper
e cacheWrapper
che (come suggerisce il nome) aggregano le varie API di recupero e cache con hook nel loro ciclo di vita. Si tratta del meccanismo che attualmente consente il funzionamento dei plug-in, ma non è esposto agli sviluppatori.
La nuova classe "handler", StrategyHandler
, mostrerà questi metodi in modo che le strategie personalizzate possano chiamare fetch()
o cacheMatch()
e avere tutti i plug-in aggiunti all'istanza della strategia che vengono richiamati automaticamente.
Questa classe consentirebbe inoltre agli sviluppatori di aggiungere callback personalizzati del ciclo di vita, che potrebbero essere specifici per le loro strategie, e "funzionano" semplicemente con l'interfaccia dei plug-in esistente.
Nuovo stato del ciclo di vita dei plug-in
In Workbox v5, i plug-in sono stateless. Ciò significa che se una richiesta per /index.html
attiva entrambi i callback requestWillFetch
e cachedResponseWillBeUsed
, questi due callback non possono comunicare tra loro né sapere che sono stati attivati dalla stessa richiesta.
Nella versione 6, a tutti i callback dei plug-in viene passato anche un nuovo oggetto state
. Questo oggetto di stato sarà univoco per questo oggetto plug-in specifico e per questa chiamata di strategia specifica (ovvero la chiamata a handle()
). Ciò consente agli sviluppatori di scrivere plug-in in cui un callback può eseguire un'azione in base alle azioni eseguite da un altro callback nello stesso plug-in (ad esempio calcolando il delta temporale tra l'esecuzione di requestWillFetch
e fetchDidSucceed
o fetchDidFail
).
Nuovi callback del ciclo di vita dei plug-in
Sono stati aggiunti nuovi callback del ciclo di vita dei plug-in per consentire agli sviluppatori di sfruttare appieno lo stato del ciclo di vita dei plug-in:
handlerWillStart
: richiamato prima dell'esecuzione di qualsiasi logica di gestore. Questo callback può essere utilizzato per impostare lo stato iniziale di gestore (ad es. registrare l'ora di inizio).handlerWillRespond
: chiamato prima che il metodohandle()
delle strategie restituisca una risposta. Questo callback può essere utilizzato per modificare la risposta prima di restituirla a un gestore di route o a un'altra logica personalizzata.handlerDidRespond
: richiamato dopo che il metodohandle()
della strategia restituisce una risposta. Questo callback può essere utilizzato per registrare i dettagli finali della risposta, ad esempio dopo le modifiche apportate da altri plug-in.handlerDidComplete
: richiamato dopo che tutte le promesse di durata estesa aggiunte all'evento dal richiamo di questa strategia sono state risolte. Questo callback può essere utilizzato per generare report sui dati che devono attendere il completamento del gestore per poterli calcolare (ad esempio, stato di successo della cache, latenza della cache, latenza di rete).handlerDidError
: chiamato se il gestore non è stato in grado di fornire una risposta valida da qualsiasi origine. Questo callback può essere utilizzato per fornire contenuti "di riserva" in alternativa a un errore di rete.
Gli sviluppatori che implementano le proprie strategie personalizzate non devono preoccuparsi di richiamare autonomamente questi callback, il tutto gestito da una nuova classe base Strategy
.
Tipi TypeScript più precisi per i gestori
Le definizioni TypeScript per i vari metodi di callback sono state normalizzate. Questo dovrebbe portare a un'esperienza migliore per gli sviluppatori che usano TypeScript e scrivono il proprio codice per implementare o chiamare i gestori.
finestra-casella di lavoro
Nuovo metodo messageSkipPending()
È stato aggiunto un nuovo metodo, messageSkipWaiting()
, al modulo workbox-window
per semplificare il processo di attivazione del service worker"in attesa". Questa opzione offre alcuni miglioramenti:
- Chiama
postMessage()
con il corpo del messaggio standard de facto,{type: 'SKIP_WAITING'}
, che un service worker generato da Workbox controlla per attivareskipWaiting()
. - Sceglie il service worker "in attesa" corretto su cui pubblicare questo messaggio, anche se non si tratta dello stesso service worker con cui è stato registrato
workbox-window
.
Rimozione di eventi "esterni" a favore di una proprietà isExternal
Tutti gli eventi "external" in workbox-window
sono stati rimossi al posto degli eventi "normali" con una proprietà isExternal
impostata su true
. In questo modo, gli sviluppatori che tengono alla distinzione possono comunque rilevarla, mentre quelli che non hanno bisogno di saperli possono ignorare la proprietà.
Ricetta più pulita "Offri il ricaricamento di una pagina agli utenti"
Grazie a entrambe le modifiche riportate sopra, la formula "Offri il ricaricamento di una pagina agli utenti" può essere semplificata:
MULTI_LINE_CODE_PLACEHOLDER_0
routing-casella di lavoro
Un nuovo parametro booleano, sameOrigin
, viene trasmesso alla funzione matchCallback
utilizzata in workbox-routing
. È impostato su true
se la richiesta riguarda un URL della stessa origine e su false negli altri casi.
Questo semplifica alcuni boilerplate comuni:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions in workbox-expiration
Ora puoi impostare matchOptions
in workbox-expiration
, che verrà poi trasmesso come CacheQueryOptions
alla chiamata cache.delete()
sottostante. La maggior parte degli sviluppatori non dovrà farlo.
pre-memorizzazione nella cache della casella di lavoro
Utilizza strategie-workbox
workbox-precaching
è stato riscritto in modo da utilizzare workbox-strategies
come base. Questo non dovrebbe comportare modifiche che provocano errori e dovrebbe portare a una migliore coerenza a lungo termine nel modo in cui i due moduli accedono alla rete e alla cache.
La pre-memorizzazione nella cache ora elabora le voci una alla volta, non in blocco
workbox-precaching
è stato aggiornato in modo che venga richiesta e memorizzata nella cache una sola voce alla volta nel file manifest di pre-cache, invece di cercare di richiederle e memorizzarle tutte nella cache contemporaneamente (lasciando il file al browser per capire come limitarle).
Ciò dovrebbe ridurre la probabilità che si verifichino errori di net::ERR_INSUFFICIENT_RESOURCES
durante la pre-memorizzazione e dovrebbe anche ridurre la contesa della larghezza di banda tra la pre-memoria e le richieste simultanee effettuate dall'app web.
PrecacheFallbackPlugin consente un fallback offline più semplice
workbox-precaching
ora include un PrecacheFallbackPlugin
, che implementa il nuovo metodo del ciclo di vita handlerDidError
aggiunto nella v6.
In questo modo è più semplice specificare un URL prememorizzato nella cache come "riserva" per una determinata strategia quando una risposta non sarebbe disponibile in altro modo. Il plug-in si occuperà di creare correttamente la chiave cache corretta per l'URL prememorizzato nella cache, incluso qualsiasi parametro di revisione necessario.
Di seguito è riportato un esempio di utilizzo per rispondere con un /offline.html
prememorizzato nella cache quando la strategia NetworkOnly
non è in grado di generare una risposta per una richiesta di navigazione. In altre parole, viene visualizzata una pagina HTML offline personalizzata:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback
nella memorizzazione nella cache di runtime
Se utilizzi generateSW
per creare un service worker per te invece di scriverlo manualmente, puoi utilizzare la nuova opzione di configurazione precacheFallback
in runtimeCaching
per eseguire la stessa operazione:
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
Richiedere assistenza
Prevediamo che la maggior parte delle migrazioni sarà semplice. Se riscontri problemi non trattati in questa guida, comunicacelo aprendo un problema su GitHub.