Ce guide se concentre sur les modifications destructives introduites dans Workbox v6. Il fournit des exemples de modifications à apporter lors de la mise à niveau depuis la version 5.
Modifications majeures
coeur de la boîte de travail
La méthode skipWaiting() dans workbox-core n'ajoute plus de gestionnaire install et équivaut à simplement appeler self.skipWaiting().
Utilisez désormais self.skipWaiting() à la place, car skipWaiting() sera probablement supprimé dans Workbox v7.
zone de travail-prémise en cache
- Les documents HTML multi-origines pour les URL correspondant à une redirection HTTP ne peuvent plus être utilisés pour répondre à une requête de navigation avec
workbox-precaching. Ce scénario est généralement rare. workbox-precachingignore désormais le paramètre de requête d'URLfbclidlors de la recherche d'une réponse mise en pré-cache pour une requête donnée.- Le constructeur
PrecacheControllerutilise désormais un objet avec des propriétés spécifiques comme paramètre au lieu d'une chaîne. Cet objet accepte les propriétés suivantes:cacheName(ayant le même rôle que la chaîne transmise au constructeur dans la version 5),plugins(remplace la méthodeaddPlugins()de la version 5) etfallbackToNetwork(remplace l'option similaire transmise àcreateHandler()et `createHandlerBoundToURL() dans la version 5). - Les méthodes
install()etactivate()dePrecacheControlleracceptent désormais exactement un seul paramètre, qui doit être défini respectivement sur les valeursInstallEventouActivateEventcorrespondantes. - La méthode
addRoute()a été supprimée dePrecacheController. À la place, la nouvelle classePrecacheRoutepeut être utilisée pour créer une route que vous pouvez ensuite enregistrer. - La méthode
precacheAndRoute()a été supprimée dePrecacheController. (Il existe toujours en tant que méthode d'assistance statique exportée par le moduleworkbox-precaching.) Elle a été supprimée, carPrecacheRoutepeut être utilisé à la place. - La méthode
createMatchCalback()a été supprimée dePrecacheController. Vous pouvez utiliser le nouveauPrecacheRouteà la place. - La méthode
createHandler()a été supprimée dePrecacheController. La propriétéstrategyde l'objetPrecacheControllerpeut être utilisée pour gérer les requêtes à la place. - L'exportation statique
createHandler()a déjà été supprimée du moduleworkbox-precaching. À la place, les développeurs doivent construire une instancePrecacheControlleret utiliser sa propriétéstrategy. - La route enregistrée auprès de
precacheAndRoute()est désormais une "vraie" route qui utilise en arrière-plan la classeRouterdeworkbox-routing. Cela peut entraîner un ordre d'évaluation différent de vos routes si vous entrelacez les appels àregisterRoute()etprecacheAndRoute().
routage de la boîte de travail
La méthode setDefaultHandler() utilise désormais un deuxième paramètre facultatif correspondant à la méthode HTTP à laquelle il s'applique, par défaut 'GET'.
- Si vous utilisez
setDefaultHandler()et que toutes vos requêtes sontGET, aucune modification n'est nécessaire. - Si vous avez des requêtes qui ne sont pas
GET(POST,PUT, etc.),setDefaultHandler()n'entraînera plus la mise en correspondance de ces requêtes.
Build Configuration (Configuration de compilation)
L'option mode pour les modes getManifest et injectManifest dans workbox-build et workbox-cli n'était pas destinée à être prise en charge et a été supprimée. Cela ne s'applique pas à workbox-webpack-plugin, qui est compatible avec mode dans son plug-in InjectManifest.
Les outils de compilation nécessitent Node.js v10 ou version ultérieure
Les versions Node.js antérieures à la v10 ne sont plus compatibles avec workbox-webpack-plugin, workbox-build et workbox-cli. Si vous exécutez une version de Node.js antérieure à la version 8, mettez à jour votre environnement d'exécution vers une version compatible.
Nouvelles améliorations
Stratégies de boîte de travail
Workbox v6 offre aux développeurs tiers un nouveau moyen de définir leurs propres stratégies. Ainsi, les développeurs tiers ont la possibilité d'étendre Workbox de manière à répondre pleinement à leurs besoins.
Nouvelle classe de base "Stratégie"
Dans la version 6, toutes les classes de stratégie Workbox doivent étendre la nouvelle classe de base Strategy. Toutes les stratégies intégrées ont été réécrites pour y répondre.
La classe de base Strategy est responsable de deux éléments principaux:
- Invoquer des rappels de cycle de vie du plug-in communs à tous les gestionnaires de stratégie (par exemple, lorsqu'ils démarrent, répondent et se terminent)
- Créer une instance "gestionnaire" pouvant gérer l'état de chaque requête traitée par une stratégie
Nouvelle classe "handler"
Nous disposions auparavant de modules internes appelés fetchWrapper et cacheWrapper, qui encapsulent, comme leur nom l'indique, les différentes API de récupération et de mise en cache avec des hooks dans leur cycle de vie. C'est le mécanisme qui permet actuellement aux plug-ins de fonctionner, mais qui n'est pas exposé aux développeurs.
La nouvelle classe "handler", StrategyHandler, expose ces méthodes afin que les stratégies personnalisées puissent appeler fetch() ou cacheMatch(), et que tous les plug-ins ajoutés à l'instance de stratégie soient automatiquement appelés.
Cette classe permet également aux développeurs d'ajouter leurs propres rappels de cycle de vie personnalisés, susceptibles d'être spécifiques à leurs stratégies, et qui "fonctionneraient" avec l'interface de plug-in existante.
Nouvel état du cycle de vie du plug-in
Dans la version 5 de Workbox, les plug-ins sont sans état. Cela signifie que si une requête destinée à /index.html déclenche à la fois les rappels requestWillFetch et cachedResponseWillBeUsed, ces deux rappels n'auront aucun moyen de communiquer entre eux ni même de savoir qu'ils ont été déclenchés par la même requête.
Dans la version 6, tous les rappels de plug-in recevront également un nouvel objet state. Cet objet d'état sera propre à cet objet de plug-in particulier et à cet appel de stratégie particulier (appel de handle()). Cela permet aux développeurs d'écrire des plug-ins dans lesquels un rappel peut effectuer une action conditionnelle en fonction de l'action d'un autre rappel du même plug-in (par exemple, calculer le delta de temps entre l'exécution de requestWillFetch et fetchDidSucceed ou fetchDidFail).
Nouveaux rappels de cycle de vie du plug-in
De nouveaux rappels de cycle de vie du plug-in ont été ajoutés pour permettre aux développeurs de profiter pleinement de l'état du cycle de vie du plug-in:
handlerWillStart: appelé avant l'exécution de toute logique de gestionnaire. Ce rappel peut être utilisé pour définir l'état initial du gestionnaire (par exemple, pour enregistrer l'heure de début).handlerWillRespond: appelé avant que la méthodehandle()des stratégies ne renvoie une réponse. Ce rappel peut être utilisé pour modifier cette réponse avant de la renvoyer à un gestionnaire de routes ou à une autre logique personnalisée.handlerDidRespond: appelé lorsque la méthodehandle()de la stratégie a renvoyé une réponse. Ce rappel peut être utilisé pour enregistrer tous les détails de la réponse finale, par exemple après des modifications apportées par d'autres plug-ins.handlerDidComplete: appelé une fois que toutes les promesses de durée de vie étendues ajoutées à l'événement à partir de l'appel de cette stratégie ont été résolues. Ce rappel peut être utilisé pour générer des rapports sur toutes les données qui doivent attendre la fin du calcul par le gestionnaire (par exemple, l'état du succès de cache (hit), la latence du cache, la latence du réseau).handlerDidError: appelé si le gestionnaire n'a pas pu fournir de réponse valide à partir d'une source. Ce rappel peut être utilisé pour fournir un contenu de remplacement à la place d'une erreur réseau.
Les développeurs qui implémentent leurs propres stratégies personnalisées n'ont pas à se soucier d'appeler eux-mêmes ces rappels. Tout est géré par une nouvelle classe de base Strategy.
Types TypeScript plus précis pour les gestionnaires
Les définitions TypeScript pour différentes méthodes de rappel ont été normalisées. Cela devrait offrir une meilleure expérience aux développeurs qui utilisent TypeScript et écrivent leur propre code pour implémenter ou appeler des gestionnaires.
fenêtre de la boîte de travail
Nouvelle méthode messageSkipWaiting()
Une nouvelle méthode, messageSkipWaiting(), a été ajoutée au module workbox-window pour simplifier le processus d'activation du service worker en attente. Cela offre quelques améliorations:
- Elle appelle
postMessage()avec le corps du message standard de facto,{type: 'SKIP_WAITING'}, qu'un service worker généré par Workbox recherche pour déclencherskipWaiting(). - Il sélectionne le service worker "en attente" auquel publier ce message, même s'il ne s'agit pas du service worker auprès duquel
workbox-windowa été enregistré.
Suppression des événements "externes" au profit d'une propriété isExternal
Tous les événements "external" dans workbox-window ont été supprimés à la place des événements "normal" avec une propriété isExternal définie sur true. Ainsi, les développeurs qui se soucient de cette distinction peuvent la détecter, tandis que les développeurs qui n'ont pas besoin de la connaître peuvent ignorer la propriété.
Méthode de nettoyage "Proposer une actualisation de la page aux utilisateurs"
Grâce aux deux modifications ci-dessus, la recette Proposer une actualisation de la page aux utilisateurs peut être simplifiée:
MULTI_LINE_CODE_PLACEHOLDER_0
routage de la boîte de travail
Un nouveau paramètre booléen, sameOrigin, est transmis à la fonction matchCallback utilisée dans workbox-routing. Il est défini sur true si la requête concerne une URL de même origine, et sur "false" dans le cas contraire.
Cela simplifie certains code récurrents courants:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions dans workbox-expiration
Vous pouvez maintenant définir matchOptions dans workbox-expiration, qui sera ensuite transmis en tant que CacheQueryOptions à l'appel cache.delete() sous-jacent. (La plupart des développeurs n'ont pas besoin de le faire.)
zone de travail-prémise en cache
Utilise des stratégies d'emplacement de travail
workbox-precaching a été réécrit pour utiliser workbox-strategies comme base. Cela ne devrait pas entraîner de modifications importantes, et devrait conduire à une meilleure cohérence à long terme dans la façon dont les deux modules accèdent au réseau et au cache.
La mise en cache préliminaire traite désormais les entrées une par une, et non de façon groupée.
workbox-precaching a été mis à jour de sorte qu'une seule entrée dans le fichier manifeste de mise en cache préalable soit demandée et mise en cache à la fois, au lieu d'essayer de les demander et de les mettre en cache toutes en même temps (laissant cette entrée au navigateur déterminer comment la limiter).
Cela devrait réduire le risque d'erreurs net::ERR_INSUFFICIENT_RESOURCES lors de la mise en cache préalable, mais également réduire les conflits de bande passante entre la mise en cache précoce et les requêtes simultanées effectuées par l'application Web.
PrecacheFallbackPlugin facilite l'action de remplacement hors connexion.
workbox-precaching inclut désormais un PrecacheFallbackPlugin, qui implémente la nouvelle méthode de cycle de vie handlerDidError ajoutée dans la version 6.
Il est ainsi facile de spécifier une URL en pré-cache en tant qu'URL de remplacement pour une stratégie donnée lorsqu'une réponse ne serait pas disponible autrement. Le plug-in crée correctement la clé de cache correcte pour l'URL en pré-mise en cache, y compris les paramètres de révision nécessaires.
Voici un exemple d'utilisation qui permet de répondre avec un /offline.html en pré-cache lorsque la stratégie NetworkOnly ne peut pas générer de réponse à une requête de navigation (en d'autres termes, afficher une page HTML hors connexion personnalisée) :
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback dans la mise en cache de l'environnement d'exécution
Si vous utilisez generateSW pour créer un service worker à votre place au lieu de l'écrire manuellement, vous pouvez utiliser la nouvelle option de configuration precacheFallback dans runtimeCaching pour obtenir le même résultat:
{
// ... 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',
},
},
}],
}
Obtenir de l'aide
Nous pensons que la plupart des migrations seront simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, veuillez ouvrir une page de problème sur GitHub pour nous en informer.