W tym przewodniku znajdziesz informacje o najważniejszych zmianach wprowadzonych w Workbox v6. Znajdziesz w nim przykłady zmian, które musisz wprowadzić podczas przechodzenia z tej wersji.
Istotne zmiany
Rdzeń skrzynki roboczej
Metoda skipWaiting() w workbox-core nie będzie już dodawana do modułu obsługi install i jest odpowiednikiem wywołania metody self.skipWaiting().
Od teraz używaj zasady self.skipWaiting(), ponieważ skipWaiting() zostanie prawdopodobnie usunięta z Workbox w wersji 7.
tworzenie buforowania w polu roboczym
- Dokumentów HTML z innych domen powiązanych z adresami URL, które odpowiadają przekierowaniam HTTP, nie można już używać w celu spełnienia żądania nawigacji z użyciem
workbox-precaching. Taki scenariusz jest zwykle rzadki. - Parametr zapytania URL
fbclidjest teraz ignorowany przezworkbox-precachingpodczas wyszukiwania odpowiedzi na dane żądanie w pamięci podręcznej. - Konstruktor
PrecacheControllerzamiast ciągu znaków przyjmuje teraz obiekt o określonych właściwościach. Ten obiekt obsługuje te właściwości:cacheName(służący do tego samego przeznaczenia co ciąg przekazany do konstruktora w wersji 5),plugins(zastępuje metodęaddPlugins()z wersji 5) orazfallbackToNetwork(zastępuje podobną opcję przekazaną docreateHandler()i `createHandlerBoundToURL()() w wersji 5). - Metody
install()iactivate()klasyPrecacheControllerprzyjmują teraz dokładnie 1 parametr, który należy ustawić odpowiednio naInstallEventlubActivateEvent. - Metoda
addRoute()została usunięta zPrecacheController. Możesz zamiast niej użyć nowej klasyPrecacheRoutedo utworzenia trasy, którą możesz potem zarejestrować. - Metoda
precacheAndRoute()została usunięta zPrecacheController. (Nadal będzie ona istnieć jako statyczna metoda pomocnicza wyeksportowana przez modułworkbox-precaching). Została usunięta, ponieważ zamiast niej można użyć:PrecacheRoute. - Metoda
createMatchCalback()została usunięta zPrecacheController. Zamiast niego możesz użyć nowej wersjiPrecacheRoute. - Metoda
createHandler()została usunięta zPrecacheController. Zamiast tego do obsługi żądań można używać właściwościstrategyobiektuPrecacheController. - Eksport statyczny
createHandler()został już usunięty z modułuworkbox-precaching. W jej miejsce deweloperzy powinni utworzyć instancjęPrecacheControlleri wykorzystać jej właściwośćstrategy. - Trasa zarejestrowana w
precacheAndRoute()jest teraz „prawdziwą” trasą korzystającą z klasyRoutersystemuworkbox-routing. Może to spowodować zmianę kolejności oceny tras, jeśli przeplatasz wywołania doregisterRoute()iprecacheAndRoute().
routing skrzynki roboczej
Metoda setDefaultHandler() przyjmuje teraz opcjonalny drugi parametr odpowiadający metodzie HTTP, do której ma zastosowanie. Domyślna wartość to 'GET'.
- Jeśli korzystasz z usługi
setDefaultHandler(), a wszystkie Twoje żądania mają wartośćGET, nie musisz wprowadzać żadnych zmian. - Jeśli masz jakieś żądania, które nie są związane z
GET(POST,PUTitp...),setDefaultHandler()nie będzie już wiązać ze sobą tych żądań.
Konfiguracja kompilacji
Opcja mode dla trybów getManifest i injectManifest w aplikacjach workbox-build i workbox-cli nie była obsługiwana i została usunięta. Nie dotyczy to domeny workbox-webpack-plugin, która obsługuje interfejs mode we wtyczce InjectManifest.
Narzędzia do kompilacji wymagają środowiska Node.js w wersji 10 lub nowszej
Wersje Node.js starsze niż 10 nie są już obsługiwane przez workbox-webpack-plugin, workbox-build ani workbox-cli. Jeśli używasz środowiska Node.js w wersji starszej niż 8, zaktualizuj środowisko wykonawcze do obsługiwanej wersji.
Nowe ulepszenia
strategie skrzynki roboczej
Workbox w wersji 6 wprowadza nowy sposób definiowania własnych strategii przez deweloperów zewnętrznych. Dzięki temu deweloperzy zewnętrzni mogą rozszerzać Workbox w sposób, który w pełni zaspokaja ich potrzeby.
Nowa klasa bazowa strategii
W wersji 6 wszystkie klasy strategii Workbox muszą stanowić rozszerzenie nowej klasy bazowej Strategy. Wszystkie wbudowane strategie zostały napisane na nowo, aby to ułatwić.
Klasa bazowa Strategy odpowiada za 2 główne funkcje:
- Wywoływanie wywołań zwrotnych cyklu życia wtyczki, które są wspólne dla wszystkich modułów obsługi strategii (np. w momencie uruchomienia, odpowiedzi i zakończenia).
- utworzenie instancji „modułu obsługi”, która może zarządzać stanem w przypadku każdego indywidualnego żądania obsługiwanego przez strategię;
Nowa klasa „handlowa”
Wcześniej moduły wewnętrzne wywołują fetchWrapper i cacheWrapper, które (jak sama nazwa wskazuje) zawierają haki do różnych interfejsów API pobierania i pamięci podręcznej. Obecnie umożliwiają one działanie wtyczek, ale nie są dostępne dla programistów.
Nowa klasa „obsługi” (StrategyHandler) będzie udostępniać te metody, dzięki czemu strategie niestandardowe mogą wywoływać metodę fetch() lub cacheMatch() i korzystać z wtyczek dodanych do instancji strategii automatycznie.
Umożliwia ona też programistom dodawanie własnych niestandardowych wywołań zwrotnych cyklu życia, które mogą być specyficzne dla ich strategii, i działają po prostu z obecnym interfejsem wtyczki.
Nowy stan cyklu życia wtyczki
W Workbox w wersji 5 wtyczki nie są stanowe. Oznacza to, że jeśli żądanie dotyczące /index.html wywoła zarówno wywołania zwrotne requestWillFetch, jak i cachedResponseWillBeUsed, te 2 wywołania zwrotne nie mogą się ze sobą komunikować ani nawet nie wiedzą, że zostały wywołane przez to samo żądanie.
W wersji 6 wszystkie wywołania zwrotne wtyczki będą też przekazywane nowy obiekt state. Obiekt stanu będzie unikalny dla tego konkretnego obiektu wtyczki i tego wywołania strategii (tj. wywołania handle()). Pozwala to programistom pisać wtyczki, w których jedno wywołanie zwrotne może warunkowo wykonać działanie na podstawie tego, co zrobiło inne wywołanie zwrotne w tej samej wtyczce (np. obliczenie różnicy czasu między uruchomieniami requestWillFetch a fetchDidSucceed lub fetchDidFail).
Wywołania zwrotne cyklu życia nowej wtyczki
Dodaliśmy nowe wywołania zwrotne cyklu życia wtyczki, aby umożliwić deweloperom pełne wykorzystanie stanu cyklu życia wtyczki:
handlerWillStart: wywoływana przed uruchomieniem jakichkolwiek działań logicznych modułu obsługi. Tego wywołania zwrotnego można użyć do ustawienia początkowego stanu modułu obsługi (np. aby zarejestrować czas rozpoczęcia).handlerWillRespond: wywoływana przed zwróceniem odpowiedzi metodyhandle()strategii. Tego wywołania zwrotnego można użyć do zmodyfikowania odpowiedzi przed jej zwróceniem do modułu obsługi trasy lub innej niestandardowej logice.handlerDidRespond: wywoływana po zwróceniu odpowiedzi ze strategiihandle(). Tego wywołania zwrotnego można użyć do rejestrowania szczegółów końcowej odpowiedzi, np. po zmianach wprowadzonych przez inne wtyczki.handlerDidComplete: wywołano po ugruntowaniu wszystkich obietnic życiowych dodanych do zdarzenia w wyniku wywołania tej strategii. Tego wywołania zwrotnego można użyć do raportowania danych, które muszą czekać na zakończenie działania modułu obsługi w celu obliczenia (np. stan trafienia w pamięci podręcznej, czas oczekiwania w pamięci podręcznej, opóźnienie sieci).handlerDidError: wywoływana, jeśli moduł obsługi nie mógł udzielić prawidłowej odpowiedzi z żadnego źródła. Tego wywołania zwrotnego można użyć, aby udostępnić treść zastępczą jako alternatywę dla błędu sieci.
Deweloperzy implementujący własne strategie niestandardowe nie muszą się martwić o samodzielne wywoływanie tych wywołań zwrotnych. Zajmuje się tym nowa klasa bazowa Strategy.
Dokładniejsze typy TypeScriptu na potrzeby modułów obsługi
Definicje TypeScript dla różnych metod wywołania zwrotnego zostały znormalizowane. Powinno to zapewnić większy komfort programistom, którzy używają TypeScriptu i piszą własny kod do implementacji lub wywoływania modułów obsługi.
okno-skrzynki roboczej
Nowa metoda messageSkipWaiting()
Do modułu workbox-window została dodana nowa metoda (messageSkipWaiting()), która upraszcza aktywowanie oczekującego” skryptu service worker. W ten sposób możesz:
- Wywołuje on
postMessage()ze standardową treścią wiadomości{type: 'SKIP_WAITING'}, pod kątem której skrypt service worker wygenerowany przez skrzynkę roboczą sprawdza, aby aktywowaćskipWaiting(). - Wybiera prawidłowy „oczekujący” skrypt service worker, w którym zostanie wysłana wiadomość, nawet jeśli nie jest to ten sam skrypt service worker, za pomocą którego zarejestrowano aplikację
workbox-window.
Usunięcie zdarzeń „zewnętrznych” na rzecz usługi isExternal
Wszystkie zdarzenia "external" w lokalizacji workbox-window zostały usunięte zamiast „normalnych” zdarzeń z właściwością isExternal ustawioną na true. Dzięki temu deweloperzy, którym zależy na różnicy, będą ją mogli wykryć, a deweloperzy, którzy nie potrzebują informacji, będą mogli ją zignorować.
Przepis na temat czyszczenia strony „Zaproponuj użytkownikom ponowne załadowanie strony”
Dzięki obu powyższych zmianom przepis „Zaproponuj użytkownikom ponowne załadowanie strony” można uprościć:
MULTI_LINE_CODE_PLACEHOLDER_0
routing skrzynki roboczej
Nowy parametr logiczny sameOrigin jest przekazywany do funkcji matchCallback używanej w obiekcie workbox-routing. Ma wartość true, jeśli żądanie dotyczy adresu URL z tej samej domeny. W przeciwnym razie ma wartość false (fałsz).
Upraszcza to niektóre popularne schematy:
MULTI_LINE_CODE_PLACEHOLDER_1
MatchOptions w oknie Workbox-expiration
Możesz teraz ustawić matchOptions w workbox-expiration, który będzie następnie przekazywany jako CacheQueryOptions do odpowiedniego wywołania cache.delete(). (Większość programistów nie musi tego robić).
tworzenie buforowania w polu roboczym
Korzysta ze strategii dotyczących pól roboczych
Tabela workbox-precaching została przepisana i używa workbox-strategies jako podstawy. Nie powinno to spowodować żadnych zmian powodujących błędy i powinno prowadzić do długotrwałej spójności sposobu, w jaki dwa moduły uzyskują dostęp do sieci i pamięci podręcznej.
Blokowanie obecnie przetwarza wpisy pojedynczo, a nie zbiorczo
Pakiet workbox-precaching został zaktualizowany, tak aby w pliku manifestu precache przechowywane były tylko 1 wpisy naraz, zamiast próbować wysyłać żądania i pamięć o nich w pamięci podręcznej jednocześnie (zachowywać przeglądarkę w celu określenia, jak ograniczyć działanie).
Powinno to zmniejszyć prawdopodobieństwo wystąpienia błędów net::ERR_INSUFFICIENT_RESOURCES podczas wstępnego buforowania, a także ograniczyć rywalizację o przepustowość między zapisywaniem w pamięci podręcznej a jednoczesnymi żądaniami wysyłanymi przez aplikację internetową.
PrecacheFallbackPlugin ułatwia tworzenie reklam zastępczych offline
Komponent workbox-precaching zawiera teraz element PrecacheFallbackPlugin, który implementuje nową metodę cyklu życia handlerDidError dodaną w wersji 6.
Ułatwia to określenie adresu URL zapisanego w pamięci podręcznej jako „zastępczej” dla danej strategii, gdy odpowiedź w innym przypadku nie byłaby dostępna. Wtyczka zadba o prawidłową skonstruowanie klucza pamięci podręcznej dla wstępnie zapisanego adresu URL z uwzględnieniem wszystkich potrzebnych parametrów wersji.
Oto przykład użycia obiektu /offline.html w pamięci podręcznej w sytuacji, gdy strategia NetworkOnly nie może wygenerować odpowiedzi na żądanie nawigacji – innymi słowy, wyświetla niestandardową stronę HTML offline:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback w pamięci podręcznej w czasie działania
Jeśli zamiast ręcznego pisania skryptu service worker tworzysz za pomocą generateSW, możesz użyć nowej opcji konfiguracji precacheFallback w runtimeCaching, aby osiągnąć to samo:
{
// ... 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',
},
},
}],
}
Jak uzyskać pomoc
Przewidujemy, że większość migracji będzie prosta. Jeśli napotkasz problemy, których nie obejmuje ten przewodnik, daj nam znać, otwierając problem na GitHubie.