Ten przewodnik zawiera informacje o zmianach wprowadzonych w Workbox w wersji 4 i zawiera przykłady zmian, które trzeba wprowadzić podczas przechodzenia z tej wersji.
Niezbędne zmiany
wstępne wczytywanie przez pole robocze
Zmieniono konwencję nazewnictwa wpisów wstępnie zapisanych w pamięci podręcznej. Teraz w przypadku wpisów, których adresy URL wymagają informacji o wersji (tj. wpisów zawierających pole revision
w pliku manifestu precache), te informacje o wersjach będą przechowywane jako część klucza pamięci podręcznej w specjalnym parametrze zapytania URL __WB_REVISION__
dołączonym do pierwotnego adresu URL. Wcześniej informacje te były przechowywane niezależnie od kluczy pamięci podręcznej przy użyciu 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 skryptu service worker. Po uaktualnieniu do wersji Workbox 4 zasoby z pamięci podręcznej użytkowników zostaną automatycznie przeniesione do nowego formatu klucza pamięci podręcznej i od tej pory zasoby w pamięci podręcznej będą wyświetlane w ten sam sposób co wcześniej.
Bezpośrednie korzystanie z kluczy pamięci podręcznej
Niektórzy deweloperzy muszą mieć bezpośredni dostęp do wpisów w pamięci podręcznej (poza kontekstem workbox.precaching.precacheAndRoute()
). Możesz na przykład zapisać w pamięci podręcznej obraz, który następnie wykorzystasz jako odpowiedź zastępczą, gdy nie można pobrać z sieci faktycznego obrazu.
Jeśli korzystasz w ten sposób z zasobów wstępnie zapisanych w pamięci podręcznej, począwszy od Workbox w wersji 4, musisz wykonać dodatkowy krok, aby przetłumaczyć oryginalny adres URL na odpowiedni klucz pamięci podręcznej, który może służyć do odczytywania wpisu zapisanego w pamięci podręcznej. Aby to zrobić, zadzwoń pod numer workbox.precaching.getCacheKeyForURL(originURL)
.
Jeśli na przykład wiesz, że plik 'fallback.png'
jest 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 w pamięci podręcznej
Zmiany wprowadzone w pamięci podręcznej w Workbox w wersji 4 oznaczają, że starsze pamięci podręczne utworzone przez poprzednie wersje tej aplikacji nie są zgodne. Domyślnie pozostają one bez zmian, a jeśli przejdziesz z Workbox v3 na Workbox v4, otrzymasz 2 kopie wszystkich wstępnie zapisanych zasobów w pamięci podręcznej.
Aby tego uniknąć, możesz bezpośrednio dodać wywołanie do workbox.precaching.cleanupOutdatedCaches()
do skryptów service worker lub ustawić nową opcję cleanupOutdatedCaches: true
, jeśli korzystasz z narzędzia do kompilacji w trybie GenerateSW
. Ponieważ mechanizm czyszczenia pamięci podręcznej działa na podstawie konwencji nazewnictwa pamięci podręcznej w celu znajdowania starszych pamięci wstępnych, a deweloperzy mają możliwość zastąpienia tych konwencji, popełniliśmy błąd ze względów bezpieczeństwa i nie włączyliśmy go domyślnie.
Zachęcamy deweloperów, którzy napotkają jakiekolwiek problemy związane z korzystaniem z tej funkcji – np. fałszywie pozytywne przypuszczenia do usuwania treści – aby ją poinformowali.
Wielkość liter w parametrach
Zmieniliśmy nazwę dwóch opcjonalnych parametrów, które można przekazywać do funkcji workbox.precaching.precacheAndRoute()
i workbox.precaching.addRoute()
, aby ujednolicić ogólną konwencję wielkich liter. ignoreUrlParametersMatching
to teraz ignoreURLParametersMatching
, a cleanUrls
to teraz cleanURLs
.
strategie skrzynki roboczej
Istnieją 2 przybliżone sposoby tworzenia instancji modułu obsługi w komponencie workbox-strategies
. Wycofujemy metodę fabryczną na rzecz wyraźnego wywoływania 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 wyświetlenie ostrzeżenia. Zachęcamy deweloperów do przeprowadzenia migracji przed wycofaniem obsługi w przyszłej wersji 5.
pole robocze-synchronizacja-w tle
Klasa workbox.backgroundSync.Queue
została napisana od nowa, aby zaoferować deweloperom większą elastyczność i kontrolę nad tym, jak żądania są dodawane do kolejki i odtwarzane.
W wersji 3 klasa Queue
miała jeden sposób dodawania żądań do kolejki (metoda addRequest()
), ale nie umożliwiała modyfikacji kolejki ani usuwania żądań.
W wersji 4 metoda addRequests()
została usunięta i dodano te metody tablicowe:
pushRequest()
popRequest()
shiftRequest()
unshiftRequest()
W wersji 3 klasa Queue
akceptowała też kilka wywołań zwrotnych, które pozwalały obserwować, kiedy żądania są odtwarzane (requestWillEnqueue
, requestWillReplay
, queueDidReplay
), ale większość deweloperów stwierdziła, że oprócz obserwacji potrzeba kontroli nad sposobem odtwarzania kolejki, w tym możliwości dynamicznego modyfikowania i zmieniania kolejności żądań, a 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 przy każdej próbie ponownego odtworzenia przez przeglądarkę. Domyślnie wywołanie zwrotne onSync
wywołuje metodę replayRequests()
, ale jeśli potrzebujesz większej kontroli nad procesem ponownego odtwarzania, możesz w dowolny sposób odtwarzać kolejkę, korzystając z wymienionych powyżej metod tablicowych.
Oto przykład niestandardowej logiki 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ż wewnętrznie tworzy instancję Queue
), więc zmieniła się w ten sam sposób.
ważność okna roboczego
Nazwa pakietu npm
została zmieniona na workbox-expiration
, zgodnie z konwencją nazewnictwa używaną w innych modułach. Ten pakiet jest funkcjonalnie odpowiednikiem starszego pakietu workbox-cache-expiration
, który został już wycofany.
aktualizacja-rozgłaszania-robota
Nazwa pakietu npm
została zmieniona na workbox-broadcast-update
, zgodnie z konwencją nazewnictwa używaną w innych modułach. Ten pakiet jest funkcjonalnie odpowiednikiem starszego pakietu workbox-broadcast-cache-update
, który został już wycofany.
rdzeń skrzynki roboczej
W Workbox w wersji 3 szczegółowość poziomów logu można kontrolować za pomocą metody workbox.core.setLogLevel()
, która przekazuje jedną z wartości w wyliczeniu workbox.core.LOG_LEVELS
. Bieżący poziom logowania możesz też odczytać na stronie 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 w przypadku Narzędzi deweloperskich w Chrome).
Workbox-sw
Dwie 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
. Organizacja workbox.skipWaiting()
zmieniła się w workbox.core.skipWaiting()
i podobnie zmieniła się w workbox.clientsClaim()
na workbox.core.clientsClaim()
.
Konfiguracja narzędzia do kompilacji
Zmieniły się nazewnictwo niektórych opcji, które można przekazywać do interfejsu workbox-cli, workbox-build lub workbox-webpack-plugin, Gdy w nazwie opcji użyto parametru „Url”, zastąpiliśmy go zamiast „URL”. Oznacza to, że preferowane są te nazwy opcji:
dontCacheBustURLsMatching
ignoreURLParametersMatching
modifyURLPrefix
templatedURLs
Odmiana „Url” tych nazw opcji nadal działa w wersji 4, ale powoduje wyświetlenie komunikatu ostrzegawczego. Zachęcamy deweloperów do przeprowadzenia migracji przed wprowadzeniem wersji 5.
Nowa funkcja
okno robocze
Nowy moduł workbox-window
upraszcza proces rejestracji skryptu service worker i wykrywania aktualizacji oraz zapewnia standardowy sposób komunikacji między kodem uruchomionym w skrypcie service worker a kodem działającym w kontekście window
aplikacji internetowej.
Chociaż korzystanie z metody workbox-window
jest opcjonalne, mamy nadzieję, że spodoba się ono deweloperom, dlatego w razie potrzeby warto przenieść do niego część logiki pisanej odręcznie. Więcej informacji o korzystaniu z workbox-window
znajdziesz w przewodniku po module.
Przykładowa migracja
Przykład rzeczywistej migracji z Workbox w wersji 3 do 4 znajdziesz w tym żądaniu pobierania.
Uzyskiwanie pomocy
Przewidujemy, że większość migracji będzie prosta. Jeśli napotkasz problemy, których nie ma w tym przewodniku, daj nam znać, otwierając je na GitHubie.