Dieser Leitfaden konzentriert sich auf funktionsgefährdende Änderungen in Workbox v6 und enthält Beispiele dafür, welche Änderungen Sie bei einem Upgrade von Workbox v5 vornehmen müssen.
Nicht abwärtskompatible Änderungen
Workbox Core
Die Methode skipWaiting() in workbox-core fügt keinen install-Handler mehr hinzu und entspricht dem Aufrufen von self.skipWaiting().
Verwende ab jetzt stattdessen self.skipWaiting(), da skipWaiting() wahrscheinlich in Workbox v7 entfernt wird.
Workbox-Precaching
- Ursprungsübergreifende HTML-Dokumente für URLs, die einer HTTP-Weiterleitung entsprechen, können nicht mehr verwendet werden, um eine Navigationsanfrage mit
workbox-precachingzu erfüllen. Dieses Szenario ist in der Regel ungewöhnlich. - Der URL-Suchparameter
fbclidwird jetzt vonworkbox-precachingignoriert, wenn eine vorab im Cache gespeicherte Antwort für eine bestimmte Anfrage gesucht wird. - Der Konstruktor
PrecacheControllerakzeptiert jetzt anstelle eines Strings ein Objekt mit bestimmten Attributen als Parameter. Dieses Objekt unterstützt die folgenden Attribute:cacheName(für denselben Zweck wie der String, der in Version 5 an den Konstruktor übergeben wurde),plugins(ersetzt die MethodeaddPlugins()von Version 5) undfallbackToNetwork(ersetzt die ähnliche Option, die ancreateHandler()und `createHandlerBoundToURL() in Version 5 übergeben wurde). - Die Methoden
install()undactivate()vonPrecacheControllerverwenden jetzt genau einen Parameter, der auf einen entsprechendenInstallEventbzw.ActivateEventfestgelegt werden sollte. - Die Methode
addRoute()wurde ausPrecacheControllerentfernt. Stattdessen kann die neuePrecacheRoute-Klasse verwendet werden, um eine Route zu erstellen, die Sie dann registrieren können. - Die Methode
precacheAndRoute()wurde ausPrecacheControllerentfernt. Es existiert weiterhin als statische Hilfsmethode, die vom Modulworkbox-precachingexportiert wurde. Sie wurde entfernt, weil stattdessenPrecacheRouteverwendet werden kann. - Die Methode
createMatchCalback()wurde ausPrecacheControllerentfernt. Stattdessen kann die neuePrecacheRouteverwendet werden. - Die Methode
createHandler()wurde ausPrecacheControllerentfernt. Das AttributstrategydesPrecacheController-Objekts kann stattdessen zur Verarbeitung von Anfragen verwendet werden. - Der statische Export
createHandler()wurde bereits aus dem Modulworkbox-precachingentfernt. Entwickler sollten stattdessen einePrecacheController-Instanz erstellen und ihrstrategy-Attribut verwenden. - Die bei
precacheAndRoute()registrierte Route ist jetzt eine „reale“ Route, die im Hintergrund dieRouter-Klasse vonworkbox-routingverwendet. Dies kann zu einer anderen Auswertungsreihenfolge Ihrer Routen führen, wenn Sie Aufrufe vonregisterRoute()undprecacheAndRoute()verschachteln.
Workbox-Routing
Für die Methode setDefaultHandler() wird jetzt ein optionaler zweiter Parameter verwendet, der der HTTP-Methode entspricht, auf die sie angewendet wird. Der Standardwert ist 'GET'.
- Wenn Sie
setDefaultHandler()verwenden und alle Ihre AnfragenGETsind, müssen keine Änderungen vorgenommen werden. - Wenn Sie Anfragen haben, die nicht
GETsind (POST,PUTusw.), DurchsetDefaultHandler()stimmen diese Anfragen dann nicht mehr überein.
Build-Konfiguration
Die Option mode für die Modi getManifest und injectManifest in workbox-build und workbox-cli sollte nicht unterstützt werden und wurde entfernt. Dies gilt nicht für workbox-webpack-plugin, das mode im zugehörigen InjectManifest-Plug-in unterstützt.
Build-Tools erfordern Node.js v10 oder höher
Node.js-Versionen vor V10 werden für workbox-webpack-plugin, workbox-build oder workbox-cli nicht mehr unterstützt. Wenn Sie eine ältere Node.js-Version als V8 verwenden, aktualisieren Sie die Laufzeit auf eine unterstützte Version.
Neue Verbesserungen
Workbox-Strategien
Workbox v6 bietet Drittentwicklern eine neue Möglichkeit, ihre eigenen Workbox-Strategien zu definieren. Dadurch wird sichergestellt, dass Entwickler von Drittanbietern Workbox so erweitern können, dass sie ihren Anforderungen vollständig gerecht werden.
Neue Strategie-Basisklasse
In v6 müssen alle Workbox-Strategieklassen die neue Strategy-Basisklasse erweitern. Alle integrierten Strategien wurden umformuliert, um dies zu unterstützen.
Die Strategy-Basisklasse hat zwei Hauptaufgaben:
- Für alle Strategie-Handler gemeinsame Callbacks für den Plug-in-Lebenszyklus aufrufen (z. B. Start, Antwort und Ende)
- Erstellen einer „Handler“-Instanz, die den Status für jede einzelne Anfrage verwalten kann, die von einer Strategie verarbeitet wird.
Neue "handler"-Klasse
Zuvor hatten wir interne Module mit den Namen fetchWrapper und cacheWrapper, die (wie der Name schon sagt) die verschiedenen Abruf- und Cache-APIs mit Hooks in ihren Lebenszyklus einbinden. Dieser Mechanismus ermöglicht derzeit Plug-ins, steht Entwicklern jedoch nicht zur Verfügung.
Die neue Handler-Klasse StrategyHandler stellt diese Methoden bereit, sodass benutzerdefinierte Strategien fetch() oder cacheMatch() aufrufen können und alle Plug-ins enthalten, die automatisch zur Strategieinstanz hinzugefügt wurden.
Diese Klasse würde es Entwicklern außerdem ermöglichen, ihre eigenen benutzerdefinierten Lebenszyklus-Callbacks hinzuzufügen, die für ihre Strategien spezifisch sind, und sie würden mit der vorhandenen Plug-in-Schnittstelle „funktionieren“.
Neuer Plug-in-Lebenszyklusstatus
In Workbox v5 sind Plug-ins zustandslos. Wenn also eine Anfrage für /index.html sowohl den requestWillFetch- als auch den cachedResponseWillBeUsed-Callback auslöst, können diese beiden Callbacks nicht miteinander kommunizieren und wissen auch nicht, dass sie von derselben Anfrage ausgelöst wurden.
In Version 6 wird außerdem an alle Plug-in-Callbacks ein neues state-Objekt übergeben. Dieses Statusobjekt ist für dieses bestimmte Plug-in-Objekt und diesen speziellen Strategieaufruf (d.h. den Aufruf von handle()) eindeutig. So können Entwickler Plug-ins schreiben, bei denen ein Callback bedingt bestimmte Aktionen ausführen kann, je nachdem, was ein anderer Callback im selben Plug-in getan hat (z.B. die Zeitdifferenz zwischen requestWillFetch und fetchDidSucceed oder fetchDidFail berechnen).
Neue Plug-in-Lebenszyklus-Callbacks
Es wurden neue Callbacks für den Plug-in-Lebenszyklus hinzugefügt, damit Entwickler den Plug-in-Lebenszyklus vollständig nutzen können:
handlerWillStart: Wird aufgerufen, bevor eine Handler-Logik ausgeführt wird. Dieser Callback kann verwendet werden, um den anfänglichen Handler-Status festzulegen (z.B. zum Aufzeichnen der Startzeit).handlerWillRespond: Wird aufgerufen, bevor die Methodehandle()der Strategie eine Antwort zurückgibt. Mit diesem Callback kann diese Antwort geändert werden, bevor sie an einen Routen-Handler oder eine andere benutzerdefinierte Logik zurückgegeben wird.handlerDidRespond: Wird aufgerufen, nachdem die Methodehandle()der Strategie eine Antwort zurückgegeben hat. Dieser Callback kann verwendet werden, um endgültige Antwortdetails zu erfassen, z.B. nach Änderungen, die von anderen Plug-ins vorgenommen wurden.handlerDidComplete: Wird aufgerufen, nachdem alle verlängerten Lebensdauer-Versprechen, die dem Ereignis durch den Aufruf dieser Strategie hinzugefügt wurden, abgewickelt wurden. Dieser Callback kann für Berichte zu Daten verwendet werden, die warten müssen, bis der Handler zur Berechnung fertig ist (z.B. Cache-Trefferstatus, Cache-Latenz, Netzwerklatenz).handlerDidError: Wird aufgerufen, wenn der Handler keine gültige Antwort aus einer beliebigen Quelle bereitstellen konnte. Dieser Callback kann verwendet werden, um „Fallback“-Inhalte als Alternative zu einem Netzwerkfehler bereitzustellen.
Entwickler, die ihre eigenen benutzerdefinierten Strategien implementieren, müssen sich nicht um das Aufrufen dieser Callbacks kümmern. All dies wird von der neuen Strategy-Basisklasse verarbeitet.
Genauere TypeScript-Typen für Handler
Die TypeScript-Definitionen für verschiedene Callback-Methoden wurden normalisiert. Dies sollte für Entwickler, die TypeScript verwenden und ihren eigenen Code zum Implementieren oder Aufrufen von Handlern schreiben, eine bessere Erfahrung bieten.
Arbeitsbereich-Fenster
Neue messageÜberspringenWarteing()-Methode
Dem Modul workbox-window wurde die neue Methode messageSkipWaiting() hinzugefügt, um die Aktivierung des Service Workers (Warten) zu vereinfachen. Dies bietet einige Verbesserungen:
- Sie ruft
postMessage()mit dem Standard-Nachrichtentext{type: 'SKIP_WAITING'}auf, den ein von Workbox generierter Service Worker prüft, umskipWaiting()auszulösen. - Es wird der richtige Service Worker mit dem Status „Warten“ ausgewählt, an den die Nachricht gesendet werden soll, auch wenn es sich nicht um denselben Service Worker handelt, mit dem
workbox-windowregistriert wurde.
„Externe“ Ereignisse werden zugunsten einer isExternal-Property entfernt
Alle Ereignisse vom Typ "external" in workbox-window wurden anstelle von "normalen" Ereignissen entfernt, bei denen die Property isExternal auf true festgelegt ist. So können Entwickler, denen die Unterscheidung wichtig ist, sie trotzdem erkennen. Entwickler, die dies nicht wissen müssen, können die Eigenschaft ignorieren.
Übersichtliches Rezept „Nutzern eine Seite neu laden“
Dank der beiden oben genannten Änderungen lässt sich das Rezept Nutzern eine Aktualisierung der Seite anbieten vereinfachen:
MULTI_LINE_CODE_PLACEHOLDER_0
Workbox-Routing
Der neue boolesche Parameter sameOrigin wird an die in workbox-routing verwendete matchCallback-Funktion übergeben. Der Wert wird auf true gesetzt, wenn sich die Anfrage auf eine URL desselben Ursprungs bezieht, andernfalls wird er auf „false“ gesetzt.
Dies vereinfacht einige gängige Textbausteine:
MULTI_LINE_CODE_PLACEHOLDER_1
MatchOptions in workbox-expiration
Sie können jetzt matchOptions in workbox-expiration festlegen, das dann als CacheQueryOptions an den zugrunde liegenden cache.delete()-Aufruf übergeben wird. Für die meisten Entwickler ist dies nicht erforderlich.
Workbox-Precaching
Nutzt Workbox-Strategien
workbox-precaching wurde umgeschrieben, sodass workbox-strategies als Basis verwendet wird. Dies sollte keine funktionsgefährdenden Änderungen zur Folge haben und zu einer besseren langfristigen Konsistenz beim Zugriff der beiden Module auf das Netzwerk und den Cache führen.
Beim Precaching werden Einträge jetzt einzeln und nicht als Bulk-Verarbeitung verarbeitet
workbox-precaching wurde aktualisiert, sodass nur ein Eintrag im Precache-Manifest gleichzeitig angefordert und im Cache gespeichert wird. Es wird nicht mehr versucht, alle gleichzeitig anzufordern und im Cache zu speichern. Der Browser muss also den Browser verlassen, um herauszufinden, wie er gedrosselt werden kann.
Dies sollte die Wahrscheinlichkeit von net::ERR_INSUFFICIENT_RESOURCES-Fehlern beim Precaching verringern und außerdem den Bandbreitenkonflikt zwischen dem Precaching und gleichzeitigen Anfragen der Webanwendung verringern.
Ein PrecacheFallbackPlugin ermöglicht ein einfacheres Offline-Fallback
workbox-precaching enthält jetzt eine PrecacheFallbackPlugin, mit der die neue Lebenszyklusmethode handlerDidError implementiert wird, die in Version 6 hinzugefügt wurde.
Dadurch ist es einfach, eine vorab im Cache gespeicherte URL als „Fallback“ für eine bestimmte Strategie anzugeben, wenn keine Antwort verfügbar wäre. Das Plug-in erstellt den korrekten Cache-Schlüssel für die vorab im Cache gespeicherte URL, einschließlich aller erforderlichen Überarbeitungsparameter.
Im Folgenden sehen Sie ein Beispiel für eine Antwort mit einem vorab im Cache gespeicherten /offline.html, wenn die Strategie NetworkOnly keine Antwort auf eine Navigationsanfrage generieren kann, d. h., eine benutzerdefinierte Offline-HTML-Seite anzuzeigen:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback beim Laufzeit-Caching
Wenn Sie generateSW verwenden, um einen Service Worker für Sie zu erstellen, anstatt den Service Worker manuell zu schreiben, können Sie die neue precacheFallback-Konfigurationsoption in runtimeCaching verwenden, um dasselbe Ergebnis zu erzielen:
{
// ... 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',
},
},
}],
}
Hilfe erhalten
Wir gehen davon aus, dass die meisten Migrationen unkompliziert verlaufen. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, informieren Sie uns bitte, indem Sie ein Problem auf GitHub erstellen.