Ten przewodnik skupia się na zmianach powodujących niezgodność wprowadzonych w Workbox v4. Zawiera też przykłady zmian, które należy wprowadzić przy przejściu z Workbox v3.
Zmiany powodujące niezgodność
workbox-precaching
Konwencja nazewnictwa wpisów w pamięci podręcznej została zaktualizowana. Teraz w przypadku wpisów, których adresy URL wymagają informacji o wersji (tzn. takich, które zawierają pole revision w pliku manifestu precache), informacje o wersji będą przechowywane jako część klucza pamięci podręcznej w specjalnym parametrze zapytania __WB_REVISION__ URL dołączonym do pierwotnego adresu URL. (wcześniej te informacje były przechowywane oddzielnie od kluczy pamięci podręcznej za pomocą IndexedDB).
Deweloperzy, którzy korzystają z wstępnego buforowania za pomocą workbox.precaching.precacheAndRoute() (co jest najczęstszym przypadkiem użycia), nie muszą wprowadzać żadnych zmian w konfiguracji service workera. Po przejściu na Workboxa 4 zapisane w pamięci podręcznej zasoby użytkowników zostaną automatycznie przeniesione do nowego formatu klucza pamięci podręcznej. W przyszłości zapisane wstępnie zasoby będą nadal wyświetlane w taki sam sposób jak wcześniej.
Bezpośrednie używanie kluczy pamięci podręcznej
Niektórzy deweloperzy mogą potrzebować dostępu do wpisów w precache bezpośrednio, poza kontekstem workbox.precaching.precacheAndRoute(). Możesz na przykład wstępnie ustawić obraz w pamięci podręcznej, który zostanie użyty jako odpowiedź „zastępcza”, gdy rzeczywistego obrazu nie będzie można pobrać z sieci.
Jeśli w ten sposób korzystasz z zasobów z zapamiętanym wcześniej buforem, od wersji Workbox 4 musisz wykonać dodatkowy krok, aby przekształcić oryginalny adres URL w odpowiednią wartość klucza pamięci podręcznej, która może służyć do odczytu zapisanego w pamięci podręcznej wpisu. W tym celu zadzwoń pod numer workbox.precaching.getCacheKeyForURL(originURL).
Jeśli na przykład wiesz, że 'fallback.png' jest przechowywane w pamięci podręcznej:
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...
}
});
Czyszczenie starych danych z pamięci podręcznej
Zmiany wprowadzone w precachingu w Workbox w wersji 4 oznaczają, że starsze dane wstępne utworzone przez poprzednie wersje Workbox są niezgodne. Domyślnie pozostają one w tym samym stanie. Jeśli zaktualizujesz Workboxa z wersji 3 na wersję 4, będziesz mieć 2 kopie wszystkich zasobów z zapamiętanej podręcznej pamięci.
Aby tego uniknąć, możesz dodać wywołanie workbox.precaching.cleanupOutdatedCaches() bezpośrednio do instancji Service Worker lub ustawić nową opcję cleanupOutdatedCaches: true, jeśli używasz narzędzia do kompilacji w trybie GenerateSW. Logika czyszczenia pamięci podręcznej działa na podstawie konwencji nazewnictwa pamięci podręcznej, aby znaleźć starsze pamięci podręczne. Ponieważ deweloperzy mają możliwość zastąpienia tych konwencji, postanowiliśmy zachować ostrożność i nie włączyliśmy tej funkcji domyślnie.
Zachęcamy deweloperów, którzy napotkają jakiekolwiek problemy podczas korzystania z tej funkcji, np. fałszywie pozytywne wyniki w przypadku usuwania, do poinformowania nas o tym.
Wielkość liter w parametrach
Zmieniliśmy nazwy dwóch opcjonalnych parametrów, które można przekazywać do parametrów workbox.precaching.precacheAndRoute() i workbox.precaching.addRoute(), aby ujednolicić ogólną konwencję wielkich liter. ignoreUrlParametersMatching to teraz ignoreURLParametersMatching, a cleanUrls to teraz cleanURLs.
workbox-strategies
Istnieją 2 prawie równoważne sposoby tworzenia instancji modułu obsługi w workbox-strategies. Wycofaliśmy metodę fabryczną na rzecz jawnego wywołania konstruktora strategii.
// 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({...});
Chociaż składnia metody fabrycznej będzie nadal działać w wersji 4, jej użycie spowoduje wygenerowanie ostrzeżenia. Zachęcamy deweloperów do wcześniejszego przeprowadzenia migracji, zanim w przyszłej wersji 5 zostanie wycofane wsparcie dla tej metody.
workbox-background-sync
Klasa workbox.backgroundSync.Queue została zmieniona, aby zapewnić deweloperom większą elastyczność i kontrolę nad sposobem dodawania żądań do kolejki i ponownego odtwarzania.
W wersji 3 klasa Queue miała tylko jeden sposób dodawania żądań do kolejki (metoda addRequest()), ale nie miała możliwości modyfikowania kolejki ani usuwania żądań.
W wersji 4 metoda addRequests() została usunięta, a dodaliśmy następujące metody przypominające tablicowe:
pushRequest()popRequest()shiftRequest()unshiftRequest()
W wersji 3 klasa Queue obsługiwała też kilka wywołań zwrotnych, które umożliwiały obserwowanie odtwarzania żądań (requestWillEnqueue, requestWillReplay, queueDidReplay), ale większość deweloperów uznała, że oprócz obserwacji chce mieć kontrolę nad tym, jak kolejka jest odtwarzana, w tym możliwość dynamicznego modyfikowania, zmieniania kolejności czy nawet anulowania poszczególnych żądań.
W wersji 4 te wywołania zwrotne zostały usunięte na rzecz pojedynczego wywołania zwrotnego onSync, które jest wywoływane za każdym razem, gdy przeglądarka próbuje odtworzyć film. Domyślnie wywołanie zwrotne onSync wywołuje replayRequests(), ale jeśli chcesz mieć większą kontrolę nad procesem odtwarzania, możesz użyć wymienionych powyżej metod podobnych do tablic, aby odtworzyć kolejkę w dowolny sposób.
Oto przykład logiki niestandardowego odtwarzania:
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!');
},
});
Podobnie klasa workbox.backgroundSync.Plugin akceptuje te same argumenty co klasa Queue (ponieważ tworzy wewnętrznie wystąpienie Queue), więc zmieniła się w ten sam sposób.
data ważności pola roboczego
Pakiet npm został przemianowany na workbox-expiration, aby był zgodny z konwencją nazewnictwa stosowaną w przypadku innych modułów. Pod względem działania ten pakiet jest odpowiednikiem starszego pakietu workbox-cache-expiration, który został wycofany.
workbox-broadcast-update
Pakiet npm został przemianowany na workbox-broadcast-update, aby był zgodny z konwencją nazewnictwa stosowaną w przypadku innych modułów. Ten pakiet ma takie same funkcje jak starszy pakiet workbox-broadcast-cache-update, który został wycofany.
workbox-core
W Workbox w wersji 3 szczegółowość poziomów logu można kontrolować za pomocą metody workbox.core.setLogLevel(), którą należy przekazać w wyliczeniem workbox.core.LOG_LEVELS. Bieżący poziom logowania możesz też odczytać za pomocą polecenia workbox.core.logLevel.
W Workbox w wersji 4 wszystkie te elementy zostały usunięte, ponieważ wszystkie nowoczesne narzędzia dla programistów są wyposażone w zaawansowane funkcje filtrowania dzienników (zobacz filtrowanie danych wyjściowych konsoli pod kątem Narzędzi deweloperskich w Chrome.
workbox-sw
2 metody, które były wcześniej dostępne bezpośrednio w przestrzeni nazw workbox (odpowiadającej modułowi workbox-sw), zostały przeniesione do workbox.core. workbox.skipWaiting() stało się workbox.core.skipWaiting(), a workbox.clientsClaim() – workbox.core.clientsClaim().
Konfiguracja narzędzia do kompilacji
Zmieniła się nazwa niektórych opcji, które można przekazywać do workbox-cli, workbox-build lub workbox-webpack-plugin. W przypadku nazw opcji zawierających „Url” zastosowano nową nazwę „URL”. Oznacza to, że preferowane są te nazwy opcji:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Wersja „Url” tych nazw opcji nadal działa w wersji 4, ale powoduje wyświetlenie komunikatu ostrzeżenia. Zachęcamy deweloperów do przeprowadzenia migracji przed wydaniem wersji 5.
Nowe funkcje
okno
Nowy moduł workbox-window upraszcza proces rejestracji i wykrywania aktualizacji usług działających w ramach service workera oraz zapewnia standardowy sposób komunikacji między kodem działającym w usłudze działającej w kontekście window aplikacji internetowej.
Korzystanie z funkcji workbox-window jest opcjonalne, ale mamy nadzieję, że deweloperzy uznają ją za przydatną i w odpowiednich przypadkach rozważą przeniesienie części swojej logiki napisane ręcznie. Więcej informacji o korzystaniu z narzędzia workbox-window znajdziesz w przewodniku modułu.
Przykład migracji
Przykład migracji z Workboxa w wersji 3 do wersji 4 znajdziesz w tym Pull Request.
Uzyskiwanie pomocy
Przewidujemy, że migracja w większości przypadków będzie prosta. Jeśli napotkasz problemy, których nie omówiliśmy w tym przewodniku, daj nam znać, otwierając zgłoszenie na GitHubie.