Ten przewodnik skupia się na zmianach wprowadzonych w wersji 6 Workboxa, a także zawiera przykłady zmian, które należy wprowadzić podczas aktualizacji z wersji 5 Workboxa.
Zmiany powodujące niezgodność
workbox-core
Metoda skipWaiting() w metodzie workbox-core nie będzie już dodawać modułu obsługi install i odpowiada wyłącznie wywołaniu self.skipWaiting().
Od teraz użyj self.skipWaiting(), ponieważ skipWaiting() zostanie prawdopodobnie usunięty z Workboxa w wersji 7.
workbox-precaching
- Dokumentów HTML z innych domen, które odpowiadają adresom URL przekierowania HTTP, nie można już używać w celu spełnienia żądania nawigacji za pomocą
workbox-precaching. Ten scenariusz jest zazwyczaj nietypowy. - Parametr zapytania w adresie URL
fbclidjest teraz ignorowany przezworkbox-precachingpodczas wyszukiwania odpowiedzi z poziomu pamięci podręcznej dla danego żądania. - Konstruktor
PrecacheControllerprzyjmuje teraz jako parametr obiekt z określonymi właściwościami zamiast ciągu znaków. Ten obiekt obsługuje te właściwości:cacheName(służący do tego samego celu co ciąg przekazany do konstruktora w wersji 5),plugins(zastępuje metodęaddPlugins()w wersji 5) ifallbackToNetwork(zastępuje podobną opcję przekazaną docreateHandler()i „createHandlerBoundToURL() w wersji 5). - Metody
install()iactivate()klasyPrecacheControllerprzyjmują teraz dokładnie 1 parametr, który powinien być ustawiony odpowiednio naInstallEventlubActivateEvent. - Metoda
addRoute()została usunięta z funkcjiPrecacheController. Zamiast tego możesz użyć nowej klasyPrecacheRoutedo utworzenia trasy, którą następnie możesz zarejestrować. - Metoda
precacheAndRoute()została usunięta z funkcjiPrecacheController. (nadal istnieje jako statyczna metoda pomocnicza wyeksportowana przez modułworkbox-precaching). Został on usunięty, ponieważ zamiast niego można użyć polaPrecacheRoute. - Metoda
createMatchCalback()została usunięta z funkcjiPrecacheController. Zamiast tego możesz użyć nowego atrybutuPrecacheRoute. - Metoda
createHandler()została usunięta z metodyPrecacheController. Zamiast tego do obsługi żądań można użyć właściwościstrategyobiektuPrecacheController. - Eksport statyczny
createHandler()został już usunięty z modułuworkbox-precaching. Zamiast tego deweloperzy powinni utworzyć instancjęPrecacheControlleri użyć właściwościstrategy. - Trasa zarejestrowana w
precacheAndRoute()jest teraz „prawdziwą” trasą, która korzysta z klasyRouterwworkbox-routing. Może to spowodować inny porządek oceny tras, jeśli przeplatasz wywołania do funkcjiregisterRoute()iprecacheAndRoute().
workbox-routing
Metoda setDefaultHandler() przyjmuje teraz opcjonalny drugi parametr odpowiadający metodzie HTTP, której dotyczy, domyślnie 'GET'.
- Jeśli używasz
setDefaultHandler()i wszystkie Twoje żądania mają wartośćGET, nie musisz wprowadzać żadnych zmian. - Jeśli masz prośby inne niż
GET(POST,PUTitp.),setDefaultHandler()nie będzie już powodować dopasowywania tych żądań.
Konfiguracja kompilacji
Opcja mode w trybach getManifest i injectManifest w wersjach workbox-build i workbox-cli nie była obsługiwana zgodnie z planem i została usunięta. Nie dotyczy to workbox-webpack-plugin, który obsługuje mode w ramach wtyczki InjectManifest.
Narzędzia do kompilowania wymagają Node.js w wersji 10 lub nowszej
Wersje Node.js starsze niż 10 nie są już obsługiwane w workbox-webpack-plugin, workbox-build ani workbox-cli. Jeśli używasz starszej wersji Node.js, zaktualizuj środowisko wykonawcze do obsługiwanej wersji.
Nowe ulepszenia
workbox-strategies
Wersja 6.0 Workbox wprowadza nowy sposób definiowania własnych strategii Workbox przez zewnętrznych deweloperów. Dzięki temu deweloperzy zewnętrzni mogą rozszerzać Workbox w sposób w pełni odpowiadający ich potrzebom.
Nowa klasa podstawowa strategii
W wersji 6 wszystkie klasy strategii Workbox muszą rozszerzać nową klasę podstawową Strategy. Wszystkie wbudowane strategie zostały przekształcone, aby je obsługiwać.
Klasa podstawowa Strategy odpowiada za 2 główne kwestie:
- wywoływanie funkcji zwrotnych cyklu życia wtyczki wspólnej dla wszystkich elementów obsługi strategii (np. podczas uruchamiania, odpowiadania i zatrzymywania).
- Tworzenie instancji „handlera”, która może zarządzać stanem każdej pojedynczej prośby obsługiwanej przez strategię.
Nowa klasa „handler”
Wcześniej mieliśmy moduły wewnętrzne o nazwach fetchWrapper i cacheWrapper, które (jak sama nazwa wskazuje) otaczają różne interfejsy API do pobierania i użytkowania pamięci podręcznej za pomocą haka w ich cyklu życia. Obecnie ten mechanizm umożliwia działanie wtyczek, ale deweloperzy nie mają do niego dostępu.
Nowa klasa obsługi (StrategyHandler) będzie udostępniać te metody, aby strategie niestandardowe mogły wywoływać fetch() lub cacheMatch() i mieć automatyczne wywoływanie wtyczek dodanych do instancji strategii.
Ta klasa umożliwiłaby też deweloperom dodawanie własnych niestandardowych wywołań zwrotnych cyklu życia, które mogłyby być specyficzne dla ich strategii i działałyby „bezproblemowo” z dotychczasowym interfejsem wtyczki.
Nowy stan cyklu życia wtyczki
W wersji 5 Workboxa wtyczki są stanowe. Oznacza to, że jeśli żądanie /index.html powoduje wywołanie funkcji zwrotnych requestWillFetch i cachedResponseWillBeUsed, te 2 funkcje nie mogą się ze sobą komunikować ani nawet wiedzieć, że zostały wywołane przez to samo żądanie.
W wersji 6 wszystkie wywołania zwrotne wtyczki również będą przekazywane nowy obiekt state. Ten obiekt stanu będzie unikalny dla tego konkretnego obiektu wtyczki i tej konkretnej wywołania strategii (czyli wywołania funkcji handle()). Umożliwia to deweloperom pisanie wtyczek, w których jedna funkcja zwracająca wywołanie może warunkowo wykonać jakąś czynność na podstawie tego, co zrobiła inna funkcja zwracająca wywołanie w tym samym pliku wtyczki (np. obliczyć różnicę czasową między wykonaniem funkcji requestWillFetch i fetchDidSucceed lub fetchDidFail).
Nowe wywołania zwrotne cyklu życia wtyczki
Dodano nowe wywołania zwrotne cyklu życia wtyczki, aby umożliwić deweloperom pełne wykorzystanie stanu cyklu życia wtyczki:
handlerWillStart: wywoływany przed rozpoczęciem działania logiki obsługi. To wywołanie zwrotne może służyć do ustawiania początkowego stanu modułu obsługi (np. zarejestrowania czasu rozpoczęcia).handlerWillRespond: wywoływana przed zwróceniem odpowiedzi przez metodę strategiihandle(). Ten wywołanie zwrotne może służyć do modyfikowania odpowiedzi przed jej przekazaniem do modułu obsługi trasy lub innej logiki niestandardowej.handlerDidRespond: jest wywoływany po zwróceniu odpowiedzi przez metodęhandle()strategii. To wywołanie zwrotne może służyć do rejestrowania szczegółów ostatecznej odpowiedzi, np. po zmianach wprowadzonych przez inne wtyczki.handlerDidComplete: wywoływana po ustaniu wszystkich przedłużonych obietnic dodanych do zdarzenia z wywołania tej strategii. Ta funkcja z powrotem może służyć do raportowania wszelkich danych, które wymagają oczekiwania na zakończenie działania obsługi, aby można było je obliczyć (np. stan trafienia do pamięci podręcznej, opóźnienie w pamięci podręcznej, opóźnienie w sieci).handlerDidError: wywoływany, gdy moduł obsługi nie może podać prawidłowej odpowiedzi z żadnego źródła. Ten wywołania zwrotnego można użyć do dostarczenia treści „zastępczych” jako alternatywy dla błędu sieci.
Programiści wdrażający własne strategie nie muszą się martwić o wywoływanie tych funkcji zwracania wartości, ponieważ robi to nowa klasa bazowa Strategy.
Dokładniejsze typy TypeScript dla obsługi
Znormalizowane zostały definicje TypeScript dla różnych metod wywołań zwrotnych. Powinna ona ułatwić pracę programistom, którzy używają TypeScript i pisują własny kod do implementacji lub wywoływania obsługi.
workbox-window
Nowa metoda messageSkipWaiting()
Aby uprościć proces aktywowania „oczekującego” pracownika usługi, do modułu workbox-window dodano nową metodę messageSkipWaiting(). Dzięki temu:
- Wywołuje ona
postMessage()z faktycznie standardowym tekstem wiadomości,{type: 'SKIP_WAITING'}, który sprawdza usługa robocza wygenerowana przez Workbox, aby wywołaćskipWaiting(). - Wybiera prawidłowy skrypt service worker, w którym ma zostać opublikowana ta wiadomość, nawet jeśli nie jest to ten sam skrypt service worker, u którego zarejestrowano
workbox-window.
Usunięcie zdarzeń „external” na rzecz właściwości isExternal
Wszystkie zdarzenia „zewnętrzne” w workbox-window zostały usunięte, a zamiast nich występują „normalne” zdarzenia z ustawionym atrybutem isExternal o wartości true. Dzięki temu deweloperzy, którym zależy na tej różnicy, mogą ją wykryć, a deweloperzy, którzy nie muszą jej znać, mogą zignorować tę właściwość.
Lepsza receptura „Oferuj użytkownikom odświeżanie strony”
Dzięki tym dwóm zmianom można uprościć regułę „Zaoferuj użytkownikom możliwość ponownego załadowania strony”:
MULTI_LINE_CODE_PLACEHOLDER_0
workbox-routing
Do funkcji matchCallback używanej w funkcji workbox-routing jest przekazywany nowy parametr logiczny sameOrigin. Ma wartość true, jeśli żądanie dotyczy adresu URL z tej samej domeny. W przeciwnym razie ma wartość false.
Upraszcza to niektóre popularne schematy:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions w workbox-expiration
Teraz możesz ustawić wartość matchOptions w funkcji workbox-expiration, która zostanie przekazana jako parametr CacheQueryOptions do wywołania funkcji cache.delete(). (większość deweloperów nie musi tego robić).
workbox-precaching
Używa strategii dotyczących workboxa.
Element workbox-precaching został przepisany, aby używać jako podstawy elementu workbox-strategies. Nie powinno to spowodować żadnych zmian powodujących niezgodność i powinno poprawić długoterminową spójność sposobu, w jaki oba moduły uzyskują dostęp do sieci i pamięci podręcznej.
Wstępne buforowanie przetwarza teraz wpisy pojedynczo, a nie zbiorczo
Pole workbox-precaching zostało zaktualizowane, dzięki czemu żąda i buforuje tylko 1 wpis w pliku manifestu precache, zamiast żądać wszystkich jednocześnie i buforować je w pamięci podręcznej (pozostawiając zapytanie w przeglądarce, aby dowiedzieć się, jak ograniczyć ruch).
To powinno zmniejszyć ryzyko net::ERR_INSUFFICIENT_RESOURCES błędów podczas wstępnego buforowania. Powinno to też zmniejszyć rywalizację o przepustowość między wczytywaniem w pamięci podręcznej a równoczesnymi żądaniami wysyłanymi przez aplikację internetową.
PrecacheFallbackPlugin umożliwia łatwiejszy tryb offline
workbox-precaching zawiera teraz metodę PrecacheFallbackPlugin, która implementuje nową metodę cyklu życia handlerDidError dodaną w wersji 6.
Dzięki temu możesz łatwo określić wstępnie z pamięci podręcznej adres URL jako „awaryjny” dla danej strategii, gdy odpowiedź nie jest dostępna. Wtyczka zajmie się prawidłowym skonstruowaniem klucza pamięci podręcznej dla wstępnie z pamięci podręcznej adresu URL, w tym dowolnego wymaganego parametru rewizji.
Oto przykład użycia tej funkcji do wyświetlenia w odpowiedzi z wykorzystaniem wcześniej wygenerowanego /offline.html, gdy strategia NetworkOnly nie może wygenerować odpowiedzi na żądanie nawigacyjne (czyli wyświetla niestandardową stronę HTML offline):
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback w pamięci podręcznej środowiska wykonawczego
Jeśli zamiast ręcznego pisania serwisowego workera używasz generateSW, aby utworzyć go dla siebie, możesz użyć nowej opcji konfiguracji precacheFallback w runtimeCaching, aby osiągnąć ten sam efekt:
{
// ... 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',
},
},
}],
}
Uzyskiwanie pomocy
Przewidujemy, że migracja w większości przypadków będzie prosta. Jeśli napotkasz problemy, których nie ma w tym przewodniku, otwórz zgłoszenie na GitHubie.