Ce guide se concentre sur les modifications destructives introduites dans Workbox v4 et fournit des exemples de modifications à apporter à la mise à niveau depuis Workbox v3.
Modifications majeures
boîte de travail-précaching
La convention d'attribution de noms pour les entrées en pré-cache a été mise à jour. Désormais, pour les entrées dont les URL nécessitent des informations de révision (c'est-à-dire les entrées qui contiennent un champ revision dans le fichier manifeste de pré-cache), ces informations de gestion des versions seront stockées dans la clé de cache, dans un paramètre de requête d'URL __WB_REVISION__ spécial, ajouté à l'URL d'origine. (Auparavant, ces informations étaient stockées séparément des clés de cache, à l'aide de IndexedDB.)
Les développeurs qui tirent parti de la mise en cache préalable via workbox.precaching.precacheAndRoute() (le cas d'utilisation le plus courant) n'ont pas besoin de modifier la configuration de leur service worker. Lors de la mise à niveau vers Workbox v4, les éléments mis en cache de vos utilisateurs sont automatiquement migrés vers le nouveau format de clé de cache. À l'avenir, les ressources en pré-cache continueront d'être diffusées de la même manière qu'auparavant.
Utiliser directement les clés de cache
Certains développeurs peuvent avoir besoin d'accéder directement aux entrées de mise en cache préalable, en dehors du contexte de workbox.precaching.precacheAndRoute(). Par exemple, vous pouvez mettre en cache une image que vous finissez par utiliser en tant que réponse de remplacement lorsqu'une image ne peut pas être extraite du réseau.
Si vous utilisez les éléments en pré-cache de cette façon, à partir de Workbox v4, vous devrez effectuer une étape supplémentaire afin de convertir l'URL d'origine en clé de cache correspondante qui pourra être utilisée pour lire l'entrée mise en cache. Pour ce faire, appelez workbox.precaching.getCacheKeyForURL(originURL).
Par exemple, si vous savez que 'fallback.png' est en pré-cache:
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...
}
});
Nettoyer les anciennes données en pré-cache
Les modifications apportées à la mise en cache préalable dans Workbox v4 signifient que les anciens précaches, créés par les versions précédentes de Workbox, ne sont pas compatibles. Par défaut, elles sont laissées telles quelles. Si vous passez de Workbox v3 à Workbox v4, vous obtenez deux copies de toutes vos ressources en pré-cache.
Pour éviter cela, vous pouvez ajouter un appel à workbox.precaching.cleanupOutdatedCaches() directement à un service workers ou définir la nouvelle option cleanupOutdatedCaches: true si vous utilisez un outil de compilation en mode GenerateSW. Étant donné que la logique de nettoyage du cache s'appuie sur les conventions de dénomination des caches pour rechercher les précaches plus anciens et que les développeurs ont la possibilité de remplacer ces conventions, nous avons commis des erreurs de sécurité et n'avons pas activé cette fonctionnalité par défaut.
Nous encourageons les développeurs qui rencontrent des problèmes lors de l'utilisation de cette fonctionnalité à nous le signaler, par exemple en générant des faux positifs lors d'une suppression.
Utilisation de minuscules/majuscules dans les paramètres
Deux paramètres facultatifs pouvant être transmis à workbox.precaching.precacheAndRoute() et workbox.precaching.addRoute() ont été renommés afin de standardiser notre convention d'utilisation des majuscules de manière générale. ignoreUrlParametersMatching est maintenant ignoreURLParametersMatching, et cleanUrls est maintenant cleanURLs.
Stratégies de boîte de travail
Il existe deux méthodes à peu près équivalentes pour créer une instance de gestionnaire dans workbox-strategies. Nous abandonnons la méthode fabrique au lieu d'appeler explicitement le constructeur de la stratégie.
// 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({...});
Même si la syntaxe de la méthode de fabrique continuera de fonctionner dans la version 4, son utilisation générera un avertissement. Nous encourageons les développeurs à effectuer la migration avant la suppression de la prise en charge dans la prochaine version 5.
synchronisation en arrière-plan de la boîte de travail
La classe workbox.backgroundSync.Queue a été réécrite pour offrir aux développeurs plus de flexibilité et de contrôle sur la façon dont les requêtes sont ajoutées à la file d'attente et relues.
Dans la version 3, la classe Queue avait un seul moyen d'ajouter des requêtes à la file d'attente (méthode addRequest()), mais elle n'avait aucun moyen de modifier la file d'attente ni de supprimer des requêtes.
Dans la version 4, la méthode addRequests() a été supprimée et les méthodes suivantes semblables à des tableaux ont été ajoutées:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Dans la version 3, la classe Queue a également accepté plusieurs rappels qui vous permettaient d'observer à quel moment les requêtes étaient relues (requestWillEnqueue, requestWillReplay, queueDidReplay). Toutefois, la plupart des développeurs ont constaté qu'en plus de l'observation, ils souhaitaient contrôler la façon dont la file d'attente était relue, y compris la possibilité de modifier, de réorganiser ou même d'annuler des requêtes individuelles de manière dynamique.
Dans la version 4, ces rappels ont été supprimés au profit d'un seul rappel onSync, qui est invoqué chaque fois qu'une tentative de relecture est effectuée par le navigateur. Par défaut, le rappel onSync appelle replayRequests(), mais si vous avez besoin de mieux contrôler le processus de relecture, vous pouvez utiliser les méthodes de type tableau listées ci-dessus pour relancer la file d'attente comme vous le souhaitez.
Voici un exemple de logique de relecture personnalisée:
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!');
},
});
De même, la classe workbox.backgroundSync.Plugin accepte les mêmes arguments que la classe Queue (puisqu'elle crée une instance Queue en interne). Elle a donc été modifiée de la même manière.
délai d'expiration de la zone de travail
Le package npm a été renommé workbox-expiration, conformément à la convention d'attribution de noms utilisée pour les autres modules. D'un point de vue fonctionnel, ce package est l'équivalent de l'ancien package workbox-cache-expiration, désormais obsolète.
mise à jour-diffusion-boîte-de-travail
Le package npm a été renommé workbox-broadcast-update, conformément à la convention d'attribution de noms utilisée pour les autres modules. D'un point de vue fonctionnel, ce package est l'équivalent de l'ancien package workbox-broadcast-cache-update, désormais obsolète.
Workbox-core
Dans Workbox v3, la verbosité des niveaux de journalisation peut être contrôlée via la méthode workbox.core.setLogLevel(), à laquelle vous transmettez l'une des valeurs de l'énumération workbox.core.LOG_LEVELS. Vous pouvez également lire le niveau de journalisation actuel via workbox.core.logLevel.
Dans Workbox v4, tous ces éléments ont été supprimés, car tous les outils pour les développeurs modernes sont désormais dotés de fonctionnalités avancées de filtrage des journaux (consultez Filtrer le résultat de la console pour les outils pour les développeurs Chrome).
boîte de travail-sw
Deux méthodes précédemment exposées directement sur l'espace de noms workbox (qui correspond au module workbox-sw) ont été déplacées vers workbox.core. workbox.skipWaiting() est devenu workbox.core.skipWaiting(), et workbox.clientsClaim() est devenu workbox.core.clientsClaim().
Configuration de l'outil de compilation
La dénomination de certaines options pouvant être transmises à workbox-cli, workbox-build ou workbox-webpack-plugin a changé. Chaque fois que "Url" était utilisé dans un nom d'option, il a été remplacé par "URL". Par conséquent, nous vous recommandons d'utiliser les noms d'options suivants:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variante "URL" de ces noms d'option fonctionne toujours dans la version 4, mais elle entraînera l'affichage d'un message d'avertissement. Nous encourageons les développeurs à effectuer la migration avant la sortie de la v5.
Nouvelles fonctionnalités
fenêtre de la boîte de travail
Le nouveau module workbox-window simplifie le processus d'enregistrement d'un service worker et la détection des mises à jour. Il fournit un moyen de communication standard entre le code exécuté dans le service worker et le code exécuté dans le contexte window de votre application Web.
Bien que l'utilisation de workbox-window soit facultative, nous espérons que les développeurs le trouveront utile et envisagerons de migrer une partie de leur logique manuscrite afin de l'utiliser le cas échéant. Pour en savoir plus sur l'utilisation de workbox-window, consultez le guide du module.
Exemple de migration
Vous trouverez un exemple de migration concrète de Workbox v3 vers v4 dans cette demande d'extraction.
Obtenir de l'aide
Nous estimons que la plupart des migrations seront simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, veuillez nous signaler un problème sur GitHub.