Plug-ins gebruiken

Wanneer u Workbox gebruikt, wilt u mogelijk een verzoek en een antwoord manipuleren terwijl het wordt opgehaald of in de cache wordt opgeslagen. Met Workbox-plug-ins kunt u extra gedrag aan uw servicemedewerker toevoegen met minimale extra standaardwerk. Ze kunnen worden verpakt en hergebruikt in uw eigen projecten, of openbaar worden gemaakt zodat anderen ze ook kunnen gebruiken.

Workbox biedt een aantal kant-en-klare plug-ins die voor ons beschikbaar zijn, en als u een handig type bent, kunt u aangepaste plug-ins schrijven die zijn afgestemd op de vereisten van uw toepassing.

Beschikbare Workbox-plug-ins

Workbox biedt de volgende officiële plug-ins voor gebruik in uw servicemedewerker:

Workbox-plug-ins (of ze nu een van de hierboven genoemde plug-ins zijn, of een aangepaste plug-in) worden gebruikt met een Workbox-strategie door een exemplaar van de plug-in toe te voegen aan de plugins -eigenschap van de strategie:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {ExpirationPlugin} from 'workbox-expiration';

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'images',
    plugins: [
      new ExpirationPlugin({
        maxEntries: 60,
        maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
      }),
    ],
  })
);

Methoden voor aangepaste plug-ins

Een Workbox-plug-in moet een of meer callback-functies implementeren. Wanneer u een plug-in aan een strategie toevoegt, worden de callback-functies automatisch op het juiste moment uitgevoerd. De Strategie geeft uw callback-functie relevante informatie door over het huidige verzoek en/of antwoord, waardoor uw plug-in de context krijgt die deze nodig heeft om actie te ondernemen. De volgende callback-functies worden ondersteund:

  • cacheWillUpdate : aangeroepen voordat een Response wordt gebruikt om een ​​cache bij te werken. Bij deze methode kan het antwoord worden gewijzigd voordat het aan de cache wordt toegevoegd, of u kunt null retourneren om te voorkomen dat de cache volledig wordt bijgewerkt.
  • cacheDidUpdate : wordt aangeroepen wanneer een nieuw item aan een cache wordt toegevoegd of als een bestaand item wordt bijgewerkt. Plug-ins die deze methode gebruiken, kunnen handig zijn als u een actie wilt uitvoeren na een cache-update.
  • cacheKeyWillBeUsed : aangeroepen voordat een aanvraag wordt gebruikt als cachesleutel. Dit gebeurt voor zowel cache-lookups (wanneer mode 'read' is) als cache-schrijfbewerkingen (wanneer mode 'write' is). Deze callback is handig als u URL's moet overschrijven of normaliseren voordat u ze gebruikt om toegang te krijgen tot caches.
  • cachedResponseWillBeUsed : Dit wordt aangeroepen net voordat een antwoord uit een cache wordt gebruikt, waardoor u dat antwoord kunt onderzoeken. Op dit moment kunt u een ander antwoord retourneren, of null retourneren.
  • requestWillFetch : Wordt gebeld wanneer een verzoek op het punt staat naar het netwerk te gaan. Handig als u het Request moet wijzigen vlak voordat het naar het netwerk gaat.
  • fetchDidFail : Wordt aangeroepen wanneer een netwerkverzoek mislukt, hoogstwaarschijnlijk vanwege een afwezigheid van netwerkconnectiviteit, en wordt niet geactiveerd wanneer de browser een netwerkverbinding heeft, maar een foutmelding ontvangt (bijvoorbeeld 404 Not Found ).
  • fetchDidSucceed : wordt aangeroepen wanneer een netwerkverzoek slaagt, ongeacht de HTTP-antwoordcode.
  • handlerWillStart : wordt aangeroepen voordat er handlerlogica wordt gestart, wat handig is als u de initiële handlerstatus moet instellen. Als u bijvoorbeeld wilt weten hoe lang het duurt voordat de handler een antwoord genereert, kunt u de starttijd noteren in deze callback.
  • handlerWillRespond : Wordt aangeroepen voordat de methode handle() van de strategie een antwoord retourneert, wat handig is als u een antwoord moet wijzigen voordat u het terugstuurt naar een RouteHandler of andere aangepaste logica.
  • handlerDidRespond : Aangeroepen nadat de handle() -methode van de strategie een antwoord retourneert. Dit is wanneer het nuttig kan zijn om eventuele details van de definitieve reactie vast te leggen (bijvoorbeeld na wijzigingen die door andere plug-ins zijn aangebracht).
  • handlerDidComplete : Wordt aangeroepen nadat alle beloften voor het verlengen van de levensduur die aan de gebeurtenis zijn toegevoegd vanaf het aanroepen van de strategie, zijn afgehandeld. Dit is handig als u gegevens moet rapporteren die moeten wachten totdat de handler klaar is om zaken als cachehitstatus, cachelatentie, netwerklatentie en andere nuttige informatie te berekenen.
  • handlerDidError : Wordt aangeroepen als de handler vanuit geen enkele bron een geldig antwoord kan geven, wat het optimale moment is om een ​​soort terugvalreactie te geven als alternatief voor een regelrechte mislukking.

Al deze callbacks zijn async en vereisen daarom await om te worden gebruikt wanneer een cache- of fetch-gebeurtenis het relevante punt voor de betreffende callback bereikt.

Als een plug-in alle bovenstaande callbacks zou gebruiken, zou dit de resulterende code zijn:

const myPlugin = {
  cacheWillUpdate: async ({request, response, event, state}) => {
    // Return `response`, a different `Response` object, or `null`.
    return response;
  },
  cacheDidUpdate: async ({
    cacheName,
    request,
    oldResponse,
    newResponse,
    event,
    state,
  }) => {
    // No return expected
    // Note: `newResponse.bodyUsed` is `true` when this is called,
    // meaning the body has already been read. If you need access to
    // the body of the fresh response, use a technique like:
    // const freshResponse = await caches.match(request, {cacheName});
  },
  cacheKeyWillBeUsed: async ({request, mode, params, event, state}) => {
    // `request` is the `Request` object that would otherwise be used as the cache key.
    // `mode` is either 'read' or 'write'.
    // Return either a string, or a `Request` whose `url` property will be used as the cache key.
    // Returning the original `request` will make this a no-op.
    return request;
  },
  cachedResponseWillBeUsed: async ({
    cacheName,
    request,
    matchOptions,
    cachedResponse,
    event,
    state,
  }) => {
    // Return `cachedResponse`, a different `Response` object, or null.
    return cachedResponse;
  },
  requestWillFetch: async ({request, event, state}) => {
    // Return `request` or a different `Request` object.
    return request;
  },
  fetchDidFail: async ({originalRequest, request, error, event, state}) => {
    // No return expected.
    // Note: `originalRequest` is the browser's request, `request` is the
    // request after being passed through plugins with
    // `requestWillFetch` callbacks, and `error` is the exception that caused
    // the underlying `fetch()` to fail.
  },
  fetchDidSucceed: async ({request, response, event, state}) => {
    // Return `response` to use the network response as-is,
    // or alternatively create and return a new `Response` object.
    return response;
  },
  handlerWillStart: async ({request, event, state}) => {
    // No return expected.
    // Can set initial handler state here.
  },
  handlerWillRespond: async ({request, response, event, state}) => {
    // Return `response` or a different `Response` object.
    return response;
  },
  handlerDidRespond: async ({request, response, event, state}) => {
    // No return expected.
    // Can record final response details here.
  },
  handlerDidComplete: async ({request, response, error, event, state}) => {
    // No return expected.
    // Can report any data here.
  },
  handlerDidError: async ({request, event, error, state}) => {
    // Return a `Response` to use as a fallback, or `null`.
    return fallbackResponse;
  },
};

Het event dat beschikbaar is in de hierboven genoemde callbacks is de oorspronkelijke gebeurtenis die de ophaal- of cacheactie heeft geactiveerd. Soms is er geen originele gebeurtenis, dus uw code moet controleren of deze bestaat voordat ernaar wordt verwezen.

Alle callbacks van plug-ins krijgen ook een state doorgegeven, dat uniek is voor een bepaalde plug-in en de strategie die deze aanroept. Dit betekent dat u plug-ins kunt schrijven waarbij één callback voorwaardelijk een taak kan uitvoeren op basis van wat een andere callback in dezelfde plug-in deed (bereken bijvoorbeeld het verschil tussen het uitvoeren requestWillFetch() en fetchDidSucceed() of fetchDidFail() ).

Plug-ins van derden

Als u een plug-in ontwikkelt en denkt dat deze buiten uw project kan worden gebruikt, raden we u aan deze als module te publiceren! Hieronder vindt u een korte lijst met door de community geleverde Workbox-plug-ins:

Mogelijk kunt u meer door de community geleverde Workbox-plug-ins vinden door te zoeken in de repository van npm.

Als u ten slotte een Workbox-plug-in heeft gebouwd die u wilt delen, voegt u het trefwoord workbox-plugin toe wanneer u deze publiceert. Als je dat doet, laat het ons dan weten op Twitter @WorkboxJS !