zone de travail-SW

Le module workbox-sw offre un moyen extrêmement facile d'utiliser les modules Workbox, simplifie le chargement de ces modules et propose des méthodes d'assistance simples.

Vous pouvez utiliser workbox-sw via notre CDN ou avec un ensemble de fichiers de boîte de travail sur votre propre serveur.

Utiliser le logiciel Workbox via CDN

Le moyen le plus simple de commencer à utiliser ce module est d'utiliser le CDN. Il vous suffit d'ajouter les éléments suivants à votre service worker:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

Votre service worker dispose alors de l'espace de noms workbox, qui donne accès à tous les modules Workbox.

workbox.precaching.*
workbox.routing.*
etc

Lorsque vous commencez à utiliser les modules supplémentaires, une certaine magie opère.

Lorsque vous référencez un module pour la première fois, workbox-sw le détecte et le charge avant de le rendre disponible. Vous pouvez le constater par vous-même dans l'onglet "Network" (Réseau) des outils de développement.

Chargement des bibliothèques Workbox dans les outils de développement

Ces fichiers seront mis en cache par votre navigateur, ce qui vous permettra de les utiliser hors connexion ultérieurement.

Utiliser des fichiers de boîte de travail locale au lieu du CDN

Si vous ne souhaitez pas utiliser le CDN, vous pouvez facilement passer à des fichiers Workbox hébergés sur votre propre domaine.

L'approche la plus simple consiste à obtenir les fichiers via la commande copyLibraries de workbox-cli, puis à indiquer à workbox-sw où trouver ces fichiers via l'option de configuration modulePathPrefix.

Si vous placez les fichiers sous /third_party/workbox-vX.Y.Z/, utilisez-les comme suit:

importScripts('/third_party/workbox-vX.Y.Z/workbox-sw.js');

workbox.setConfig({
  modulePathPrefix: '/third_party/workbox-vX.Y.Z/',
});

Éviter les importations asynchrones

En arrière-plan, le chargement de nouveaux modules pour la première fois implique d'appeler importScripts() avec le chemin d'accès au fichier JavaScript correspondant (hébergé sur le CDN ou via une URL locale). Dans les deux cas, une restriction importante s'applique: les appels implicites à importScripts() ne peuvent se produire que dans le gestionnaire install d'un service worker ou pendant l'exécution initiale synchrone du script du service worker.

Pour éviter d'enfreindre cette restriction, il est recommandé de référencer les différents espaces de noms workbox.* en dehors des gestionnaires d'événements ou des fonctions asynchrones.

Par exemple, le code de service worker de premier niveau suivant est acceptable:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will work!
workbox.routing.registerRoute(
  ({request}) => request.destination === 'image',
  new workbox.strategies.CacheFirst()
);

Toutefois, le code ci-dessous peut poser problème si vous n'avez pas référencé workbox.strategies ailleurs dans votre service worker:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Oops! This causes workbox-strategies.js to be imported inside a fetch handler,
    // outside of the initial, synchronous service worker execution.
    const cacheFirst = new workbox.strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

Si vous devez écrire du code qui aurait autrement été contraire à cette restriction, vous pouvez déclencher explicitement l'appel importScripts() en dehors du gestionnaire d'événements à l'aide de la méthode workbox.loadModule():

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will trigger the importScripts() for workbox.strategies and its dependencies:
workbox.loadModule('workbox-strategies');

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Referencing workbox.strategies will now work as expected.
    const cacheFirst = new workbox.strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

Vous pouvez également créer une référence aux espaces de noms pertinents en dehors de vos gestionnaires d'événements, puis l'utiliser ultérieurement:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will trigger the importScripts() for workbox.strategies and its dependencies:
const {strategies} = workbox;

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Using the previously-initialized strategies will work as expected.
    const cacheFirst = new strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

Forcer l'utilisation des builds de débogage ou de production

Tous les modules Workbox sont fournis avec deux versions : une version de débogage qui contient une journalisation et une vérification supplémentaire du type, et une version de production qui supprime la journalisation et la vérification du type.

Par défaut, workbox-sw utilise la version de débogage pour les sites sur localhost, mais pour toute autre origine, il utilise la version de production.

Si vous souhaitez forcer les builds de débogage ou de production, vous pouvez définir l'option de configuration debug:

workbox.setConfig({
  debug: true,
});

Convertir le code à l'aide d'instructions d'importation pour utiliser workbox-sw

Lorsque vous chargez Workbox à l'aide de workbox-sw, tous les packages Workbox sont accessibles via l'espace de noms global workbox.*.

Si vous disposez d'un exemple de code utilisant des instructions import que vous souhaitez convertir pour utiliser workbox-sw, il vous suffit de charger workbox-sw et de remplacer toutes les instructions import par des variables locales qui font référence à ces modules sur l'espace de noms global.

Cela fonctionne, car chaque package de service worker Workbox publié sur npm est également disponible dans l'espace de noms workbox global via une version camelCase du nom (par exemple, tous les modules exportés à partir du package npm workbox-precaching sont disponibles sur workbox.precaching.*. Tous les modules exportés à partir du package npm workbox-background-sync se trouvent sur workbox.backgroundSync.*).

À titre d'exemple, voici du code qui utilise des instructions import faisant référence aux modules de la boîte de travail:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponse} from 'workbox-cacheable-response';

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    plugins: [new CacheableResponsePlugin({statuses: [0, 200]})],
  })
);

Voici le même code réécrit pour utiliser workbox-sw (notez que seules les instructions d'importation ont changé, la logique n'a pas été modifiée):

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

const {registerRoute} = workbox.routing;
const {CacheFirst} = workbox.strategies;
const {CacheableResponse} = workbox.cacheableResponse;

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    plugins: [new CacheableResponsePlugin({statuses: [0, 200]})],
  })
);