Dieses Handbuch konzentriert sich auf funktionsgefährdende Änderungen, die in Workbox v6 eingeführt wurden, und enthält Beispiele dafür, welche Änderungen Sie vornehmen müssen, wenn Sie ein Upgrade von Workbox v5 durchführen.
Wichtige Änderungen
workbox-core
Die Methode skipWaiting() in workbox-core fügt keinen install-Handler mehr hinzu und entspricht dem Aufruf von self.skipWaiting().
Verwenden Sie ab sofort stattdessen self.skipWaiting(), da skipWaiting() wahrscheinlich in Workbox v7 entfernt wird.
workbox-precaching
- Mehrfach-Quell-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 nicht üblich. - Der URL-Suchparameter
fbclidwird jetzt vonworkbox-precachingignoriert, wenn eine vorab im Cache gespeicherte Antwort für eine bestimmte Anfrage gesucht wird. - Der
PrecacheController-Konstruktor nimmt jetzt ein Objekt mit bestimmten Eigenschaften als Parameter anstelle eines Strings an. Dieses Objekt unterstützt die folgenden Eigenschaften:cacheName(dient demselben Zweck wie der String, der in Version 5 an den Konstruktor übergeben wurde),plugins(ersetzt dieaddPlugins()-Methode aus Version 5) undfallbackToNetwork(ersetzt die ähnliche Option, die in Version 5 ancreateHandler()und „createHandlerBoundToURL()“ übergeben wurde). - Die Methoden
install()undactivate()vonPrecacheControllernehmen jetzt genau einen Parameter an, der auf einen entsprechendenInstallEventoderActivateEventgesetzt werden sollte. - Die Methode
addRoute()wurde ausPrecacheControllerentfernt. Stattdessen kann die neue KlassePrecacheRouteverwendet werden, um eine Route zu erstellen, die Sie dann registrieren können. - Die Methode
precacheAndRoute()wurde ausPrecacheControllerentfernt. Sie existiert weiterhin als statische Hilfsmethode, die vomworkbox-precaching-Modul exportiert wird. Er wurde entfernt, da stattdessenPrecacheRouteverwendet werden kann. - Die Methode
createMatchCalback()wurde ausPrecacheControllerentfernt. Stattdessen kann das neuePrecacheRouteverwendet werden. - Die Methode
createHandler()wurde ausPrecacheControllerentfernt. Stattdessen kann die PropertystrategydesPrecacheController-Objekts verwendet werden, um Anfragen zu verarbeiten. - Der statische
createHandler()-Export wurde bereits aus demworkbox-precaching-Modul entfernt. Stattdessen sollten Entwickler einePrecacheController-Instanz erstellen und dasstrategy-Attribut verwenden. - Die bei
precacheAndRoute()registrierte Route ist jetzt eine „echte“ Route, die dieRouter-Klasse vonworkbox-routingverwendet. Dies kann zu einer anderen Auswertungsreihenfolge der Routen führen, wenn Sie Aufrufe anregisterRoute()undprecacheAndRoute()verschachteln.
workbox-routing
Die setDefaultHandler()-Methode nimmt jetzt einen optionalen zweiten Parameter entgegen, der der HTTP-Methode entspricht, auf die sie angewendet wird. Standardmäßig ist das 'GET'.
- Wenn Sie
setDefaultHandler()verwenden und alle Ihre AnfragenGETsind, müssen Sie nichts ändern. - Wenn Sie Anfragen haben, die nicht
GET(POST,PUTusw.) sind,setDefaultHandler()führt nicht mehr dazu, dass diese Anfragen übereinstimmen.
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 in seinem InjectManifest-Plug-in unterstützt.
Build-Tools erfordern Node.js v10 oder höher
Node.js-Versionen vor Version 10 werden für workbox-webpack-plugin, workbox-build und workbox-cli nicht mehr unterstützt. Wenn Sie eine ältere Node.js-Version als Version 8 verwenden, aktualisieren Sie Ihre Laufzeit auf eine unterstützte Version.
Neue Verbesserungen
workbox-strategies
Workbox v6 bietet externen Entwicklern eine neue Möglichkeit, ihre eigenen Workbox-Strategien zu definieren. So können Drittanbieter Workbox so erweitern, dass sie ihren Anforderungen voll und ganz entspricht.
Neue Basisklasse für Strategie
In Version 6 muss die neue Strategy-Basisklasse für alle Workbox-Strategieklassen erweitert werden. Alle vordefinierten Strategien wurden entsprechend überarbeitet.
Die Basisklasse Strategy ist für zwei Hauptaufgaben verantwortlich:
- Aufruf von Callbacks für den Lebenszyklus von Plug-ins, die für alle Strategie-Handler gemeinsam sind (z.B. beim Starten, Antworten und Beenden).
- Erstellen einer „Handler“-Instanz, die den Status für jede einzelne Anfrage verwalten kann, die von einer Strategie verarbeitet wird.
Neue „handler“-Klasse
Bisher gab es interne Module namens fetchWrapper und cacheWrapper, die (wie der Name schon sagt) die verschiedenen Abruf- und Cache-APIs mit Hooks in ihren Lebenszyklus einbetten. Dieser Mechanismus ermöglicht derzeit die Funktion von Plug-ins, ist aber für Entwickler nicht sichtbar.
Die neue „handler“-Klasse StrategyHandler stellt diese Methoden zur Verfügung, damit benutzerdefinierte Strategien fetch() oder cacheMatch() aufrufen und alle Plugins, die der Strategieinstanz hinzugefügt wurden, automatisch aufgerufen werden können.
Diese Klasse würde es Entwicklern auch ermöglichen, ihre eigenen benutzerdefinierten Lebenszyklus-Callbacks hinzuzufügen, die sich speziell auf ihre Strategien beziehen und mit der vorhandenen Plug-in-Oberfläche funktionieren würden.
Neuer Lebenszyklusstatus des Plug-ins
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 weder miteinander kommunizieren noch wissen, dass sie von derselben Anfrage ausgelöst wurden.
In Version 6 wird allen Plug-in-Callbacks auch ein neues state-Objekt übergeben. Dieses Statusobjekt ist eindeutig 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 eine bedingte Aktion basierend auf dem Verhalten eines anderen Callbacks im selben Plug-in ausführen kann, z.B. das Zeitdelta zwischen der Ausführung von requestWillFetch und fetchDidSucceed oder fetchDidFail.
Neue Callbacks für den Plug-in-Lebenszyklus
Es wurden neue Lebenszyklus-Callbacks für Plug-ins hinzugefügt, damit Entwickler den Lebenszyklusstatus des Plug-ins optimal nutzen können:
handlerWillStart: wird aufgerufen, bevor eine Handler-Logik ausgeführt wird. Mit diesem Rückruf kann der anfängliche Handlerstatus festgelegt werden (z.B. die Startzeit aufzeichnen).handlerWillRespond: Wird aufgerufen, bevor die Strategiemethodehandle()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 diehandle()-Methode der Strategie eine Antwort zurückgegeben hat. Mit diesem Rückruf können alle Details der endgültigen Antwort aufgezeichnet werden, z.B. nach Änderungen, die von anderen Plug-ins vorgenommen wurden.handlerDidComplete: wird aufgerufen, nachdem alle Versprechen zur Verlängerung der Lebensdauer, die dem Ereignis durch den Aufruf dieser Strategie hinzugefügt wurden, geklärt wurden. Mit diesem Rückruf können Daten erfasst werden, die erst berechnet werden können, wenn der Handler fertig ist (z.B. Cache-Trefferstatus, Cache-Latenz, Netzwerklatenz).handlerDidError: Wird aufgerufen, wenn der Handler keine gültige Antwort von einer Quelle liefern konnte. Mit diesem Rückruf können Sie als Alternative zu einem Netzwerkfehler „Fallback“-Inhalte bereitstellen.
Entwickler, die ihre eigenen benutzerdefinierten Strategien implementieren, müssen sich nicht darum kümmern, diese Callbacks selbst aufzurufen. Das wird alles von einer neuen Strategy-Basisklasse erledigt.
Genauere TypeScript-Typen für Handler
TypeScript-Definitionen für verschiedene Callback-Methoden wurden normalisiert. Dies sollte Entwicklern, die TypeScript verwenden und eigenen Code zum Implementieren oder Aufrufen von Handlern schreiben, zu einer besseren Erfahrung führen.
workbox-window
Neue Methode messageSkipwaiting()
Dem workbox-window-Modul wurde die neue Methode messageSkipWaiting() hinzugefügt, um die Aktivierung des wartenden Dienst-Workers zu vereinfachen. Dies bietet einige Verbesserungen:
- Sie ruft
postMessage()mit dem De-facto-Standardnachrichtentext{type: 'SKIP_WAITING'}auf, den ein von Workbox generierter Service Worker prüft, umskipWaiting()auszulösen. - Es wird der richtige „wartende“ Service Worker ausgewählt, an den diese Nachricht gesendet werden soll, auch wenn es sich nicht um denselben Service Worker handelt, bei dem
workbox-windowregistriert wurde.
Entfernung von „externen“ Ereignissen zugunsten einer externen Property
Alle externen Ereignisse in workbox-window wurden entfernt und durch „normale“ Ereignisse ersetzt, für die die isExternal-Eigenschaft auf true festgelegt ist. So können Entwickler, die die Unterscheidung benötigen, sie weiterhin erkennen. Entwickler, die sie nicht benötigen, können die Property ignorieren.
Optimiertes Rezept „Nutzer eine Seite neu laden lassen“
Dank der beiden oben genannten Änderungen kann das Rezept Nutzer eine Seitenaktualisierung anbieten vereinfacht werden:
MULTI_LINE_CODE_PLACEHOLDER_0
workbox-routing
Der neuen Funktion matchCallback, die in workbox-routing verwendet wird, wird der boolesche Parameter sameOrigin übergeben. Er ist auf true gesetzt, wenn die Anfrage für eine URL desselben Ursprungs ist, andernfalls auf „false“.
Dadurch wird einige gängige Boilerplate-Codefragmente vereinfacht:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions in workbox-expiration
Sie können jetzt matchOptions in workbox-expiration festlegen, was dann als CacheQueryOptions an den zugrunde liegenden cache.delete()-Aufruf übergeben wird. (Die meisten Entwickler müssen das nicht tun.)
Workbox-Precaching
Verwendet Workbox-Strategien
workbox-precaching wurde so umgeschrieben, dass workbox-strategies als Basis verwendet wird. Dies sollte zu keinen funktionsgefährdenden Änderungen führen und zu einer besseren langfristigen Konsistenz beim Zugriff der beiden Module auf das Netzwerk und den Cache führen.
Beim Precach werden Einträge jetzt einzeln, nicht im Bulk-Verfahren verarbeitet
workbox-precaching wurde aktualisiert, sodass jeweils nur ein Eintrag im Pre-Cache-Manifest angefordert und im Cache gespeichert wird, anstatt alle gleichzeitig anzufordern und im Cache zu speichern. Die Drosselung wird dem Browser überlassen.
Dadurch sollte die Wahrscheinlichkeit von net::ERR_INSUFFICIENT_RESOURCES-Fehlern beim Precaching verringert und die Bandbreitenauslastung zwischen Precaching und gleichzeitigen Anfragen der Webanwendung reduziert werden.
PrecacheFallbackPlugin ermöglicht einfacheren Offline-Fallback
workbox-precaching enthält jetzt eine PrecacheFallbackPlugin, die die neue Lebenszyklusmethode handlerDidError implementiert, die in Version 6 hinzugefügt wurde.
Dadurch wird es einfach, eine vorab im Cache gespeicherte URL als „Fallback“ für eine bestimmte Strategie anzugeben, wenn andernfalls keine Antwort verfügbar wäre. Das Plug-in sorgt dafür, dass der richtige Cache-Schlüssel für die vorab im Cache gespeicherte URL erstellt wird, einschließlich aller erforderlichen Revisionen.
Hier ist ein Beispiel, wie es mit einem vorab im Cache gespeicherten /offline.html antwortet, wenn mit der NetworkOnly-Strategie keine Antwort für eine Navigationsanfrage generiert werden kann – mit anderen Worten, es wird eine benutzerdefinierte Offline-HTML-Seite angezeigt:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback im Laufzeit-Caching
Wenn Sie generateSW verwenden, um einen Service Worker für Sie zu erstellen, anstatt ihn manuell zu schreiben, können Sie die neue precacheFallback-Konfigurationsoption in runtimeCaching verwenden, um dasselbe zu erreichen:
{
// ... 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 ablaufen. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, erstelle bitte einen Issue auf GitHub.