Migracja z Workbox 5 do 6

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 klasie workbox-core nie będzie już dodawać elementu install i będzie równoważna wywołaniu metody 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 źródeł w przypadku adresów URL odpowiadających przekierowaniu HTTP nie można już używać do obsługi żądania nawigacji z użyciem workbox-precaching. Ten scenariusz jest zazwyczaj nietypowy.
• Parametr zapytania w adresie URL fbclid jest teraz ignorowany przez usługę workbox-precaching podczas wyszukiwania odpowiedzi z poziomu pamięci podręcznej dla danego żądania.
• Konstruktor PrecacheController przyjmuje teraz jako parametr obiekt z określonymi właściwościami zamiast ciągu znaków. Obiekt ten obsługuje te właściwości: cacheName (spełnia tę samą funkcję co ciąg znaków przekazany konstruktorowi w wersji 5), plugins (zastępuje metodę addPlugins() w wersji 5) i fallbackToNetwork (zastępuje podobną opcję przekazaną do funkcji createHandler() i createHandlerBoundToURL() w wersji 5).
• Metody install() i activate() klasy PrecacheController przyjmują teraz dokładnie 1 parametr, który powinien być ustawiony odpowiednio na InstallEvent lub ActivateEvent.
• Metoda addRoute() została usunięta z funkcji PrecacheController. Zamiast tego możesz użyć nowej klasy PrecacheRoute do utworzenia trasy, którą następnie możesz zarejestrować.
• Metoda precacheAndRoute() została usunięta z funkcji PrecacheController. (nadal istnieje jako statyczna metoda pomocnicza wyeksportowana przez moduł workbox-precaching). Został on usunięty, ponieważ zamiast niego można użyć pola PrecacheRoute.
• Metoda createMatchCalback() została usunięta z funkcji PrecacheController. Zamiast tego możesz użyć nowego atrybutu PrecacheRoute.
• Metoda createHandler() została usunięta z funkcji PrecacheController. Zamiast tego do obsługi żądań można użyć właściwości strategy obiektu PrecacheController.
• Eksport statyczny createHandler() został już usunięty z modułu workbox-precaching. Zamiast tego deweloperzy powinni utworzyć instancję PrecacheController i użyć właściwości strategy.
• Trasa zarejestrowana w precacheAndRoute() jest teraz „prawdziwą” trasą, która korzysta z klasy Router w workbox-routing. Może to spowodować zmianę kolejności oceny tras, jeśli przeplatasz wywołania do funkcji registerRoute() i precacheAndRoute().

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 jakieś prośby inne niż GET (POST, PUT itp.), setDefaultHandler() nie będzie już powodować dopasowywania tych żądań.

Konfiguracja kompilacji

Opcja mode w przypadku trybów 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 przypadku 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 zakończenia).
• 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. To mechanizm, który obecnie umożliwia działanie wtyczek, ale nie jest widoczny dla deweloperów.

Nowa klasa „handler” (StrategyHandler) udostępni te metody, dzięki czemu niestandardowe strategie mogą wywoływać metody fetch() lub cacheMatch(), a wszystkie wtyczki dodane do instancji strategii będą wywoływane automatycznie.

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 do wszystkich wywołań zwrotnych w pluginie będzie też przekazywany nowy obiekt state. Ten obiekt stanu będzie unikalny dla tego konkretnego obiektu wtyczki i tej konkretnej wywołanej strategii (czyli wywołania 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. Tej funkcji zwrotnej można użyć do ustawienia początkowego stanu modułu obsługi (np. do zapisania czasu rozpoczęcia).
• handlerWillRespond: wywoływana przed zwróceniem odpowiedzi przez metodę strategii handle(). 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. Ten wywołanie zwrotne może służyć do rejestrowania wszelkich szczegółów odpowiedzi końcowej, np. po zmianach wprowadzonych przez inne wtyczki.
• handlerDidComplete: wywoływana po zaakceptowaniu wszystkich zatrzymań dotyczących rozszerzenia okresu obowiązywania obietnic dodanych do zdarzenia po wywołaniu tej strategii. Ten wywołanie zwrotne 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. stanu trafienia do pamięci podręcznej, opóźnienia w pamięci podręcznej i opóźnienia w sieci).
• handlerDidError: wywoływany, gdy moduł obsługi nie może podać prawidłowej odpowiedzi z żadnego źródła. Ten wywołanie zwrotne może służyć do udostępniania treści „zastępczych” jako alternatywy dla błędu sieci.

Programiści implementują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

Definicje TypeScripta dla różnych metod wywołania zostały znormalizowane. 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 de facto standardowym tekstem wiadomości {type: 'SKIP_WAITING'}, który sprawdza usługa robocza wygenerowana przez Workbox, aby wywołać skipWaiting().
• Wybiera ona odpowiedni skrypt service worker w stanie „oczekujący”, do którego ma zostać wysłana wiadomość, nawet jeśli nie jest to ten sam skrypt, który zarejestrował 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”:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

workbox-routing

Do funkcji matchCallback używanej w funkcji workbox-routing jest przekazywany nowy parametr logiczny sameOrigin. Jest on ustawiany na true, jeśli żądanie dotyczy adresu URL tego samego pochodzenia, a w przeciwnym razie na fałsz.

Dzięki temu uprościsz niektóre typowe fragmenty:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

matchOptions w workbox-expiration

Teraz możesz ustawić parametr matchOptions w funkcji workbox-expiration, który zostanie przekazany jako parametr CacheQueryOptions do wywołania funkcji cache.delete(). (większość deweloperów nie będzie musiała 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 przerwy w działaniu usługi. Powinna też poprawić długoterminową spójność sposobu, w jaki te 2 moduły uzyskują dostęp do sieci i pamięci podręcznej.

Wstępne buforowanie przetwarza teraz wpisy pojedynczo, a nie zbiorczo

Funkcja workbox-precaching została zaktualizowana, aby za każdym razem wysyłać tylko 1 element z pliku manifestu do wcześniejszego buforowania zamiast próbować wysyłać i przechowywać w buforze wszystkie elementy naraz (pozostawiając przeglądarce decyzję o tym, jak ograniczyć przepustowość).

Powinno to zmniejszyć prawdopodobieństwo wystąpienia błędów net::ERR_INSUFFICIENT_RESOURCES podczas wstępnego buforowania, a także zmniejszyć współzawodnictwo o przepustowość między wstępnym buforowaniem a jednoczesnymi żądaniami wysyłanymi przez aplikację internetową.

PrecacheFallbackPlugin umożliwia łatwiejsze tworzenie wersji zapasowych offline

workbox-precaching zawiera teraz PrecacheFallbackPlugin, który wdraża 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 zaprecached URL, w tym dowolnego wymaganego parametru rewizji.

Oto przykład użycia tej funkcji w celu wyświetlenia w odpowiedzi z wykorzystaniem wcześniej wygenerowanego elementu /offline.html, gdy strategia NetworkOnly nie może wygenerować odpowiedzi na żądanie nawigacyjne (czyli wyświetla niestandardową stronę HTML offline):

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback w buforowaniu w czasie wykonywania

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 większość migracji będzie prosta. Jeśli napotkasz problemy, których nie ma w tym przewodniku, otwórz zgłoszenie na GitHubie.