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.
Nicht abwärtskompatible Änderungen
Workbox-Core
Mit der Methode skipWaiting() in workbox-core wird kein install-Handler mehr hinzugefügt. Sie entspricht dem Aufrufen von self.skipWaiting().
Verwenden Sie ab sofort 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 für Navigationsanfragen mit
workbox-precachingverwendet werden. 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
PrecacheController-Konstruktor übernimmt jetzt ein Objekt mit bestimmten Eigenschaften als Parameter anstelle eines Strings. Dieses Objekt unterstützt die folgenden Eigenschaften:cacheName(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 ancreateHandler()und `createHandlerBoundToURL() in Version 5 übergeben wurde). - Die Methoden
install()undactivate()vonPrecacheControllerverwenden jetzt genau einen Parameter, der auf eine entsprechendeInstallEventbzw. eine entsprechendeActivateEventfestgelegt werden muss. - Die Methode
addRoute()wurde ausPrecacheControllerentfernt. An ihrer Stelle kann die neue KlassePrecacheRouteverwendet werden, um eine Route zu erstellen, die Sie dann registrieren können. - Die Methode
precacheAndRoute()wurde ausPrecacheControllerentfernt. (Sie ist weiterhin als statische Hilfsmethode vorhanden, 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. Stattdessen kann die Eigenschaftstrategydes ObjektsPrecacheControllerzur Verarbeitung von Anfragen verwendet werden. - Der statische Export
createHandler()wurde bereits aus dem Modulworkbox-precachingentfernt. An ihrer Stelle sollten Entwickler einePrecacheController-Instanz erstellen und deren Attributstrategyverwenden. - Die bei
precacheAndRoute()registrierte Route ist jetzt eine „echte“ Route, die im Hintergrund dieRouter-Klasse vonworkbox-routingnutzt. Dies kann zu einer anderen Auswertungsreihenfolge der Routen führen, wenn Sie Aufrufe anregisterRoute()undprecacheAndRoute()verschachteln.
Workbox-Routing
Die Methode setDefaultHandler() verwendet jetzt einen optionalen zweiten Parameter, der der HTTP-Methode entspricht, für die sie gilt. Der Standardwert ist 'GET'.
- Wenn Sie
setDefaultHandler()verwenden und alle Ihre AnfragenGETsind, müssen keine Änderungen vorgenommen werden. - Wenn Sie Anfragen haben, die nicht
GET(POST,PUTusw.) sind,setDefaultHandler()führt dazu, dass diese Anfragen nicht mehr ü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-Strategien
Workbox v6 bietet externen Entwicklern eine neue Möglichkeit, ihre eigenen Workbox-Strategien zu definieren. Dadurch wird sichergestellt, dass externe Entwickler die Möglichkeit haben, Workbox auf eine Weise zu erweitern, die ihren Anforderungen voll entspricht.
Neue Basisklasse für Strategie
In Version 6 muss die neue Strategy-Basisklasse für alle Workbox-Strategieklassen erweitert werden. Alle integrierten Strategien wurden neu geschrieben, um dies zu unterstützen.
Die Strategy-Basisklasse ist für zwei Hauptaufgaben verantwortlich:
- Aufruf von Plug-in-Lebenszyklus-Callbacks, die für alle Strategie-Handler üblich sind (z.B. wann sie starten, antworten und enden).
- Eine "Handler"-Instanz erstellen, die den Status für jede einzelne Anfrage verwalten kann, die eine Strategie verarbeitet.
Neue „handler“-Klasse
Früher hatten interne Module die Aufrufe 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, ist jedoch nicht für Entwickler sichtbar.
Die neue Handler-Klasse StrategyHandler macht diese Methoden verfügbar, sodass benutzerdefinierte Strategien fetch() oder cacheMatch() aufrufen können und alle Plug-ins, die der Strategieinstanz hinzugefügt wurden, automatisch aufgerufen werden.
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 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 oder wissen, dass sie von derselben Anfrage ausgelöst wurden.
In Version 6 wird an alle Plug-in-Callbacks außerdem 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 ausführen kann, die auf einem anderen Callback im selben Plug-in basiert (z.B. das Zeitdelta zwischen requestWillFetch und fetchDidSucceed oder fetchDidFail berechnen).
Neue Callbacks für den Plug-in-Lebenszyklus
Es wurden neue Callbacks für den Plug-in-Lebenszyklus 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 Callback kann der anfängliche Handler-Status festgelegt werden (z.B. die Startzeit aufzeichnen).handlerWillRespond: wird aufgerufen, bevor diehandle()-Methode der Strategien eine Antwort zurückgibt. Mit diesem Callback kann die Antwort geändert werden, bevor sie an einen Routing-Handler oder eine andere benutzerdefinierte Logik zurückgegeben wird.handlerDidRespond: wird aufgerufen, nachdem die Methodehandle()der Strategie eine Antwort zurückgibt. Mit diesem Callback können alle endgültigen Antwortdetails 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 Callback können alle Daten gemeldet werden, die warten müssen, bis der Handler für die Berechnung abgeschlossen ist (z.B. Cache-Trefferstatus, Cache-Latenz, Netzwerklatenz).handlerDidError: wird aufgerufen, wenn der Handler keine gültige Antwort aus einer Quelle bereitstellen konnte. Mit diesem Callback kann Fallback-Inhalte als Alternative zu einem Netzwerkfehler bereitgestellt werden.
Entwickler, die ihre eigenen benutzerdefinierten Strategien implementieren, müssen sich nicht selbst darum kümmern, diese Callbacks aufzurufen. All das wird von einer neuen Strategy-Basisklasse abgewickelt.
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.
Arbeitsbereich-Fenster
Neue Methode „messageSkipwaiting()“
Die neue Methode messageSkipWaiting() wurde dem Modul workbox-window hinzugefügt, um die Aktivierung des Service Workers „Warten“ 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 wird, auch wenn es sich nicht um denselben Service Worker handelt, bei dem
workbox-windowregistriert wurde.
Entfernung von „external“-Ereignissen zugunsten einer isExternal-Eigenschaft
Alle "external"-Ereignisse in workbox-window wurden anstelle von "normalen" Ereignissen entfernt, bei denen die Eigenschaft isExternal auf true festgelegt war. So können Entwickler, denen die Unterscheidung wichtig ist, sie trotzdem erkennen, während Entwickler, die dies nicht wissen müssen, die Eigenschaft ignorieren können.
Übersichtliches Schema „Nutzern eine Aktualisierung der Seite anbieten“
Dank der beiden obigen Änderungen kann das Rezept Nutzern eine Aktualisierung der Seite anbieten vereinfacht werden:
MULTI_LINE_CODE_PLACEHOLDER_0
Workbox-Routing
Der neue boolesche Parameter sameOrigin wird an die Funktion matchCallback übergeben, die in workbox-routing verwendet wird. Er ist auf true gesetzt, wenn die Anfrage für eine URL desselben Ursprungs ist, andernfalls auf „false“.
Dies vereinfacht einige gängige Standardformulierungen:
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, um workbox-strategies als Basis zu verwenden. 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 Precache-Manifest angefordert und im Cache gespeichert wird, anstatt zu versuchen, alle auf einmal anzufordern und im Cache zu speichern. Der Browser kann dann herausfinden, wie die Drosselung funktioniert.
Dadurch sollte die Wahrscheinlichkeit von net::ERR_INSUFFICIENT_RESOURCES-Fehlern beim Precaching verringert und gleichzeitig der Bandbreitenkonflikt zwischen dem Precaching und gleichzeitigen Anfragen der Webanwendung verringert werden.
PrecacheFallbackPlugin vereinfacht Offline-Fallbacks.
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 erstellt den richtigen Cache-Schlüssel für die vorab im Cache gespeicherte URL, einschließlich aller erforderlichen Überarbeitungsparameter.
Hier ist ein Beispiel, wie es mit einem vorab im Cache gespeicherten /offline.html antwortet, wenn mit der NetworkOnly-Strategie keine Antwort auf eine Navigationsanfrage generiert werden kann – mit anderen Worten, es wird eine benutzerdefinierte Offline-HTML-Seite angezeigt:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback beim 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 sein werden. Wenn Probleme auftreten, die in dieser Anleitung nicht behandelt werden, eröffnen Sie ein Problem auf GitHub.