Deze handleiding is gericht op het doorbreken van de wijzigingen die in Workbox v4 zijn geïntroduceerd, met voorbeelden van de wijzigingen die u moet aanbrengen bij het upgraden van Workbox v3.
Veranderingen doorbreken
precaching van werkvakken
De naamgevingsconventie voor vooraf in de cache opgeslagen vermeldingen is bijgewerkt. Voor items waarvan de URL's revisie-informatie nodig hebben (dwz de items die een revision in het precache-manifest bevatten), wordt die versie-informatie opgeslagen als onderdeel van de cachesleutel, in een speciale __WB_REVISION__ URL-queryparameter toegevoegd aan de originele URL. (Voorheen werd deze informatie afzonderlijk van de cachesleutels opgeslagen met behulp van IndexedDB .)
Ontwikkelaars die profiteren van precaching via workbox.precaching.precacheAndRoute() , wat het meest voorkomende gebruiksscenario is, hoeven geen wijzigingen aan te brengen in de configuratie van hun servicemedewerkers; bij het upgraden naar Workbox v4 zullen de in de cache opgeslagen middelen van uw gebruikers automatisch migreren naar het nieuwe cachesleutelformaat, en in de toekomst zullen de vooraf in de cache opgeslagen bronnen op dezelfde manier blijven werken als voorheen.
Cachesleutels rechtstreeks gebruiken
Sommige ontwikkelaars moeten mogelijk rechtstreeks toegang krijgen tot precache-items, buiten de context van workbox.precaching.precacheAndRoute() . U kunt bijvoorbeeld een afbeelding vooraf in de cache opslaan die u uiteindelijk gebruikt als 'fallback'-reactie wanneer een daadwerkelijke afbeelding niet van het netwerk kan worden opgehaald.
Als u op deze manier gebruik maakt van vooraf in de cache opgeslagen assets, moet u, beginnend in Workbox v4, een extra stap ondernemen om een originele URL te vertalen naar de overeenkomstige cachesleutel die kan worden gebruikt om het in de cache opgeslagen item te lezen. U doet dit door workbox.precaching.getCacheKeyForURL(originURL) aan te roepen.
Als u bijvoorbeeld weet dat 'fallback.png' vooraf in de cache is opgeslagen:
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...
}
});
Oude vooraf in de cache opgeslagen gegevens opruimen
De wijzigingen die zijn aangebracht in precaching in Workbox v4 betekenen dat oudere precaches, gemaakt door eerdere versies van Workbox, niet compatibel zijn. Standaard blijven ze zoals ze zijn, en als u een upgrade uitvoert van Workbox v3 naar Workbox v4, krijgt u twee exemplaren van al uw vooraf in de cache opgeslagen bronnen.
Om dit te voorkomen, kunt u de aanroep naar workbox.precaching.cleanupOutdatedCaches() rechtstreeks toevoegen aan serviceworkers, of de nieuwe optie cleanupOutdatedCaches: true instellen als u een buildtool in GenerateSW modus gebruikt. Omdat de logica voor het opschonen van de cache werkt op basis van cachenaamgevingsconventies om oudere precaches te vinden, en omdat ontwikkelaars de mogelijkheid hebben om deze conventies te omzeilen, hebben we een fout gemaakt aan de kant van de veiligheid en hebben we dit niet standaard ingeschakeld.
We moedigen ontwikkelaars die problemen ondervinden bij het gebruik hiervan aan (zoals valse positieven rond het verwijderen) om ons dit te laten weten .
Hoofdlettergebruik van parameters
Twee optionele parameters die kunnen worden doorgegeven aan workbox.precaching.precacheAndRoute() en workbox.precaching.addRoute() zijn hernoemd om onze algemene hoofdlettergebruikconventie te standaardiseren. ignoreUrlParametersMatching is nu ignoreURLParametersMatching en cleanUrls is nu cleanURLs .
workbox-strategieën
Er zijn twee, ongeveer gelijkwaardige manieren om een exemplaar van een handler te maken in workbox-strategies . We zijn de fabrieksmethode aan het afschaffen, ten gunste van het expliciet aanroepen van de constructor van de strategie.
// 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({...});
Hoewel de syntaxis van de fabrieksmethode in v4 blijft werken, zal het gebruik ervan een waarschuwing registreren, en we moedigen ontwikkelaars aan om te migreren voordat de ondersteuning in de toekomstige v5-release wordt verwijderd.
werkbox-achtergrondsynchronisatie
De klasse workbox.backgroundSync.Queue is herschreven om ontwikkelaars meer flexibiliteit en controle te bieden over hoe verzoeken aan de wachtrij worden toegevoegd en opnieuw worden afgespeeld.
In v3 had de klasse Queue één manier om verzoeken aan de wachtrij toe te voegen (de methode addRequest() ), maar er was geen enkele manier om de wachtrij te wijzigen of verzoeken te verwijderen.
In v4 is de methode addRequests() verwijderd en zijn de volgende array-achtige methoden toegevoegd:
-
pushRequest() -
popRequest() -
shiftRequest() -
unshiftRequest()
In v3 accepteerde de klasse Queue ook verschillende callbacks waarmee je kon observeren wanneer verzoeken opnieuw werden afgespeeld ( requestWillEnqueue , requestWillReplay , queueDidReplay ), maar de meeste ontwikkelaars ontdekten dat ze, naast observatie, ook controle wilden over hoe de wachtrij werd afgespeeld, inclusief de mogelijkheid om individuele verzoeken dynamisch te wijzigen, opnieuw te ordenen of zelfs te annuleren.
In v4 zijn deze callbacks verwijderd ten gunste van een enkele onSync callback , die wordt aangeroepen telkens wanneer de browser een herhalingspoging doet. Standaard zal de onSync callback replayRequests() aanroepen, maar als u meer controle over het herhalingsproces nodig heeft, kunt u de hierboven genoemde array-achtige methoden gebruiken om de wachtrij opnieuw af te spelen zoals u dat wilt.
Hier is een voorbeeld van aangepaste herhalingslogica:
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!');
},
});
Op dezelfde manier accepteert de klasse workbox.backgroundSync.Plugin dezelfde argumenten als de klasse Queue (aangezien deze intern een Queue instantie aanmaakt), dus deze is op dezelfde manier gewijzigd.
werkdoos-vervaldatum
Het npm pakket heeft de nieuwe naam workbox-expiration gekregen, passend bij de naamgevingsconventie die voor andere modules wordt gebruikt. Dit pakket is functioneel gelijkwaardig aan het oudere workbox-cache-expiration pakket , dat nu verouderd is.
workbox-broadcast-update
Het npm pakket is hernoemd naar workbox-broadcast-update , passend bij de naamgevingsconventie die voor andere modules wordt gebruikt. Dit pakket is functioneel gelijkwaardig aan het oudere workbox-broadcast-cache-update pakket , dat nu verouderd is.
werkdoos-kern
In Workbox v3 kon de breedsprakigheid van logniveaus worden beheerd via de workbox.core.setLogLevel() methode, waarbij u een van de waarden in de workbox.core.LOG_LEVELS opsomming zou doorgeven. U kunt ook het huidige logniveau lezen via workbox.core.logLevel .
In Workbox v4 zijn deze allemaal verwijderd omdat alle moderne ontwikkelaarstools nu worden geleverd met uitgebreide logboekfiltermogelijkheden (zie de console-uitvoer filteren voor Chrome Dev Tools).
werkkast-sw
Twee methoden die eerder rechtstreeks in de workbox naamruimte werden weergegeven (die overeenkomt met de workbox-sw -module) zijn in plaats daarvan verplaatst naar workbox.core . workbox.skipWaiting() is workbox.core.skipWaiting() geworden en op dezelfde manier is workbox.clientsClaim() workbox.core.clientsClaim() geworden.
Configuratie van hulpprogramma's
De naamgeving van sommige opties die kunnen worden doorgegeven aan workbox-cli, workbox-build of workbox-webpack-plugin is veranderd. Telkens wanneer 'Url' werd gebruikt in een optienaam, is deze verouderd ten gunste van 'URL'. Dit betekent dat de volgende optienamen de voorkeur hebben:
-
dontCacheBustURLsMatching -
ignoreURLParametersMatching -
modifyURLPrefix -
templatedURLs
De "Url"-variant van deze optienamen werkt nog steeds in v4, maar zal resulteren in een waarschuwingsbericht. We moedigen ontwikkelaars aan om vóór de v5-release te migreren.
Nieuwe functionaliteit
werkdoosvenster
De nieuwe workbox-window vereenvoudigt het proces van registratie van servicemedewerkers en het detecteren van updates, en biedt een standaardcommunicatiemiddel tussen code die wordt uitgevoerd in de servicemedewerker en code die wordt uitgevoerd in window van uw web-app.
Hoewel het gebruik van workbox-window optioneel is, hopen we dat ontwikkelaars het nuttig zullen vinden en overwegen om een deel van hun handgeschreven logica te migreren om het te gebruiken wanneer dat nodig is. U kunt meer leren over het gebruik van workbox-window in de handleiding van de module .
Voorbeeld migratie
Een voorbeeld van een real-world migratie van Workbox v3 naar v4 is te vinden in deze Pull Request .
Hulp krijgen
We verwachten dat de meeste migraties eenvoudig zullen zijn. Als u problemen tegenkomt die niet in deze handleiding worden behandeld, kunt u ons dit laten weten door een probleem op GitHub te openen .