Migracja z Workbox 3 do 4

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.