tworzenie buforowania w polu roboczym

Jedną z funkcji skryptów service worker jest zapisywanie zbioru plików w pamięci podręcznej podczas instalacji. Jest to często określane jako „wstępowanie”, ponieważ buforujesz treść przed użyciem skryptu service worker.

Głównym powodem jest to, że deweloperzy mają kontrolę nad pamięcią podręczną, co oznacza, że mogą określić, kiedy i jak długo plik jest przechowywany w pamięci podręcznej, a także wyświetlać go w przeglądarce bez połączenia z siecią, co pozwala tworzyć aplikacje internetowe działające w trybie offline.

Workbox upraszcza zapisywanie w pamięci podręcznej, ponieważ upraszcza interfejs API i dba o wydajne pobieranie zasobów.

Jak działa wywoływanie pól roboczych

Przy pierwszym wczytywaniu aplikacji internetowej workbox-precaching sprawdza wszystkie zasoby, które chcesz pobrać, usuwa duplikaty i podłącza odpowiednie zdarzenia skryptu service worker, by pobrać i przechowywać zasoby. Adresy URL, które już zawierają informacje o wersjach (np. hasz treści), są używane jako klucze pamięci podręcznej bez wprowadzania żadnych dalszych modyfikacji. W przypadku adresów URL, które nie zawierają informacji o obsłudze wersji, do klucza pamięci podręcznej dołączany jest dodatkowy parametr zapytania URL, który reprezentuje hasz treści generowany przez Workbox podczas kompilacji.

Wszystko to robi workbox-precaching podczas zdarzenia install skryptu service worker.

Gdy użytkownik ponownie odwiedza Twoją aplikację internetową i pojawia się nowy skrypt service worker z innymi zasobami wstępnie zapisywanymi w pamięci podręcznej, workbox-precaching przyjrzy się nowej liście i w zależności od ich weryfikacji określi, które zasoby są całkowicie nowe, a które wymagają aktualizacji. Wszystkie nowe zasoby lub aktualizacje wersji zostaną dodane do pamięci podręcznej podczas zdarzenia install nowego skryptu service worker.

Ten nowy skrypt service worker nie będzie używany do odpowiadania na żądania, dopóki nie zostanie wywołane jego zdarzenie activate. To w ramach zdarzenia activate workbox-precaching sprawdzi, czy w pamięci podręcznej nie ma zasobów, których nie ma już na liście bieżących adresów URL, i usunie je z pamięci podręcznej.

workbox-precaching wykona te czynności za każdym razem, gdy mechanizm Service Worker zostanie zainstalowany i aktywowany, upewniając się, że użytkownik ma najnowsze zasoby i pobiera tylko zmienione pliki.

Wyświetlanie odpowiedzi w pamięci podręcznej

Wywołanie precacheAndRoute() lub addRoute() spowoduje utworzenie trasy, która będzie odpowiadać żądaniam adresów URL wstępnie zapisanych w pamięci podręcznej.

Strategia odpowiedzi stosowana na tej trasie jest priorytetowa w pamięci podręcznej: odpowiedź z pamięci podręcznej zostanie użyta, chyba że odpowiedź z pamięci podręcznej nie istnieje (z powodu nieoczekiwanego błędu). W takim przypadku zamiast tego zostanie użyta odpowiedź sieci.

Kolejność wywołań funkcji precacheAndRoute() lub addRoute() jest ważna. Zwykle warto wywołać ją odpowiednio wcześnie w pliku skryptu service worker, zanim zarejestrujesz dodatkowe trasy w registerRoute(). Jeśli najpierw wywołano funkcję registerRoute(), a trasa pasuje do żądania przychodzącego, odpowiedź będzie stosowana niezależnie od strategii zdefiniowanej w tej dodatkowej trasie, a nie w przypadku strategii opartej na pamięci podręcznej używanej przez workbox-precaching.

Objaśnienie listy pamięci podręcznej

workbox-precaching wymaga tablicy obiektów z właściwością url i revision. Ta tablica jest czasami nazywana plikiem manifestu precache:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Ta lista odwołuje się do zestawu adresów URL, z których każdy ma własną informację o „zmianach”.

W przypadku drugiego i trzeciego obiektu w przykładzie powyżej właściwość revision jest ustawiona na null. Dzieje się tak, ponieważ informacje o poprawianiu znajdziesz w adresie URL, co jest zwykle sprawdzoną metodą w przypadku zasobów statycznych.

Pierwszy obiekt (/index.html) bezpośrednio ustawia właściwość wersji, czyli automatycznie wygenerowany skrót zawartości pliku. W przeciwieństwie do zasobów JavaScript i CSS pliki HTML zasadniczo nie mogą zawierać informacji o wersji w adresach URL. W przeciwnym razie linki do tych plików w internecie nie będą działać po każdej zmianie treści strony.

Dzięki przekazaniu właściwości wersji do precacheAndRoute() Workbox będzie wiedzieć, że plik się zmienił, i odpowiednio go zaktualizuje.

Workbox zawiera narzędzia ułatwiające generowanie tej listy:

• workbox-build: to pakiet węzłów, którego można używać w zadaniu gulp lub jako skryptu uruchamiania npm.
• workbox-webpack-plugin: użytkownicy pakietu internetowego mogą używać tej wtyczki.
• workbox-cli: nasz interfejs wiersza poleceń może też posłużyć do wygenerowania listy zasobów i dodania ich do skryptu service worker.

Żądania przychodzące dotyczące plików w pamięci podręcznej

Jedną z rzeczy, które workbox-precaching robi od razu, jest manipulowanie przychodzącymi żądaniami sieciowymi w celu dopasowania plików w pamięci podręcznej. Znajdziesz w nim typowe praktyki stosowane w internecie.

Na przykład żądanie / może zwykle zostać spełnione przez plik pod adresem /index.html.

Poniżej znajdziesz listę manipulacji, które workbox-precaching wykonuje domyślnie, wraz z informacjami, jak możesz te manipulacje zmienić.

Ignoruj parametry adresu URL

Żądania z parametrami wyszukiwania można modyfikować, aby usunąć określone wartości lub wszystkie.

Domyślnie parametry wyszukiwania zaczynające się od utm_ lub ściśle dopasowane do fbclid są usuwane. Oznacza to, że żądanie /about.html?utm_campaign=abcd zostanie wypełnione wartością /about.html w pamięci podręcznej.

Za pomocą funkcji ignoreURLParametersMatching możesz zignorować inny zestaw parametrów wyszukiwania:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Indeks katalogu

Żądania, których nazwa kończy się cyframi /, są domyślnie porównywane z wpisami z końcówką index.html. Oznacza to, że przychodzące żądanie / może być automatycznie obsługiwane za pomocą zapisanego w pamięci podręcznej wpisu /index.html.

Możesz ją zmienić lub całkowicie wyłączyć, ustawiając directoryIndex:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

Wyczyść adresy URL

Jeśli żądanie nie pasuje do pamięci podręcznej, na końcu dodajemy .html, aby umożliwić obsługę „czystych” adresów URL (czyli „ładnych” adresów). Oznacza to, że żądanie takie jak /about będzie obsługiwane przez wpis dla /about.html w pamięci podręcznej.

Możesz wyłączyć tę funkcję, ustawiając cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Niestandardowe manipulacje

Jeśli chcesz zdefiniować niestandardowe dopasowania w przypadku żądań przychodzących do zasobów wstępnie zapisanych w pamięci podręcznej, możesz to zrobić za pomocą opcji urlManipulation. Powinno to być wywołanie zwrotne, które zwraca tablicę możliwych dopasowań.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Zaawansowane użycie

Bezpośrednie korzystanie z PrecacheController

Domyślnie workbox-precaching skonfiguruje za Ciebie detektory install i activate. Dla programistów zaznajomionych z mechanizmami Service Worker może to nie być korzystne, jeśli potrzebujesz większej kontroli.

Zamiast korzystać z eksportu domyślnego, możesz użyć metody PrecacheController bezpośrednio, aby dodać elementy do pamięci podręcznej, określić, kiedy zasoby zostaną zainstalowane i kiedy należy je wyczyścić.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Bezpośrednie odczytywanie zasobów wstępnie zapisanych w pamięci podręcznej

Czasem może być konieczne bezpośrednie odczytanie zasobu zapisanego w pamięci podręcznej, poza kontekstem routingu, które workbox-precaching może wykonać automatycznie. Możesz na przykład zapisać w pamięci podręcznej częściowe szablony HTML, które następnie trzeba pobrać i wykorzystać przy tworzeniu pełnej odpowiedzi.

Ogólnie obiekty Response przechowywane w pamięci podręcznej można uzyskać za pomocą interfejsu Cache Storage API, ale jest jeden problem: klucz pamięci podręcznej adresu URL, którego należy użyć podczas wywoływania cache.match(), może zawierać parametr obsługi wersji, który workbox-precaching automatycznie tworzy i utrzymuje.

Aby uzyskać prawidłowy klucz pamięci podręcznej, możesz wywołać metodę getCacheKeyForURL(), przekazując pierwotny adres URL, a następnie użyć wyniku do wykonania w odpowiedniej pamięci podręcznej cache.match().

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Jeśli potrzebujesz tylko obiektu Response w pamięci podręcznej, możesz wywołać metodę matchPrecache(), która automatycznie użyje odpowiedniego klucza pamięci podręcznej i przeszuka odpowiednią pamięć:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Czyszczenie starych pamięci podręcznej

Większość wersji Workbox ma ten sam format do przechowywania wstępnie zapisanych danych, a pamięci podręcznej utworzone przez starsze wersje tej usługi mogą być normalnie używane w nowszych wersjach. Niekiedy zdarza się jednak, że zmiany w pamięci podręcznej wymagają od obecnych użytkowników ponownego pobrania wszystkiego, a dane wcześniej przechowywane w pamięci podręcznej stają się nieaktualne. (taka zmiana zaszła pomiędzy wersjami 3 i 4 Workspace).

Te nieaktualne dane nie powinny zakłócać normalnego działania, ale wpływają na ogólne wykorzystanie limitu miejsca na dane, a użytkownik może łatwiej je usunąć. Aby to zrobić, dodaj cleanupOutdatedCaches() do skryptu service worker lub ustaw cleanupOutdatedCaches: true, jeśli generujesz skrypt service worker za pomocą jednego z narzędzi do kompilacji dostępnych w Workbox.

Korzystanie z integralności zasobu podrzędnego

Niektórzy deweloperzy mogą chcieć dodać dodatkowe gwarancje oferowane przez mechanizm integralności zasobów podrzędnych podczas pobierania z sieci adresów URL z pamięci podręcznej.

Do każdego wpisu w pliku manifestu precache można dodać dodatkową, opcjonalną właściwość o nazwie integrity. Jeśli zostanie podana, zostanie użyta jako wartość integrity podczas tworzenia obiektu Request służącego do wypełniania pamięci podręcznej. W razie niezgodności proces wstępnego buforowania się nie uda.

Określanie, które wpisy w pliku manifestu wstępnego buforowania powinny mieć właściwości integrity, i ustalanie odpowiednich wartości do wykorzystania, nie należy do zakresu narzędzi do tworzenia w Workbox. Zamiast tego deweloperzy, którzy chcą włączyć tę funkcję, powinni zmodyfikować plik manifestu precached generowany przez Workbox, aby samodzielnie dodać odpowiednie informacje. Opcja manifestTransform w konfiguracji narzędzi do tworzenia w Workbox może pomóc w tych kwestiach:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)