routing-casella di lavoro

Un service worker può intercettare le richieste di rete per una pagina. Potrebbe rispondere a il browser con contenuti memorizzati nella cache, contenuti della rete o contenuti generati nel Service worker.

workbox-routing è un modulo che semplifica l'indirizzamento queste richieste diverse funzioni che forniscono risposte.

Come viene eseguito il routing

Quando una richiesta di rete causa un evento di recupero dei service worker, workbox-routing tenterà di rispondere alla richiesta utilizzando le route e i gestori forniti.

Diagramma di routing della casella di lavoro

Gli aspetti principali da tenere in considerazione rispetto a quanto riportato sopra sono:

  • Il metodo di una richiesta è importante. Per impostazione predefinita, le route sono registrate GET richieste. Se vuoi intercettare altri tipi di richieste, dovrai avere per specificare il metodo.

  • L'ordine della registrazione della route è importante. Se più route vengono registrato in grado di gestire una richiesta, la route registrata per prima verranno utilizzati per rispondere alla richiesta.

Esistono diversi modi per registrare un percorso: puoi utilizzare i callback, le o istanze di route.

Corrispondenza e gestione nelle route

Un "percorso" in una casella di lavoro non serve più di due funzioni: una "corrispondenza" funzione per determinare se la route deve corrispondere a una richiesta e a una "gestione" nella funzione di chiamata, che dovrebbe gestire la richiesta e rispondere con una risposta.

Workbox include alcuni helper che eseguiranno la corrispondenza e la gestione ma se dovessi avere bisogno di un comportamento diverso, scrivi un la funzione di corrispondenza e gestore personalizzata è l'opzione migliore.

R funzione di callback di corrispondenza viene passato un ExtendableEvent, Request e un URL oggetto che puoi restituendo un valore veritiero. Come semplice esempio, puoi trovare una corrispondenza un URL specifico come questo:

const matchCb = ({url, request, event}) => {
  return url.pathname === '/special/url';
};

La maggior parte dei casi d'uso può essere trattata esaminando / testando url o request.

R funzione di callback del gestore riceverà lo stesso ExtendableEvent, Request e URL oggetto e un valore params, ovvero il valore restituito da "match" personalizzata.

const handlerCb = async ({url, request, event, params}) => {
  const response = await fetch(request);
  const responseBody = await response.text();
  return new Response(`${responseBody} <!-- Look Ma. Added Content. -->`, {
    headers: response.headers,
  });
};

Il tuo gestore deve restituire una promessa che si risolve in un Response. In questo esempio, stiamo usando async e await. Il valore Response restituito verrà aggregato in una promessa.

Puoi registrare questi callback in questo modo:

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb);

L'unico limite è che la "corrispondenza" il callback deve essere sincrono non puoi eseguire alcuna operazione asincrona. Il motivo è che Router deve rispondere in modo sincrono all'evento di recupero o consentire la riduzione ad altri eventi di recupero.

Di solito il "gestore" del callback userebbe una delle strategie fornite dalle strategie di lavoro come segue:

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

registerRoute(matchCb, new StaleWhileRevalidate());

In questa pagina ci concentreremo su workbox-routing, ma puoi scopri di più su queste strategie nelle strategie workbox.

Come registrare una route di espressione regolare

È prassi comune utilizzare un'espressione regolare anziché una "corrispondenza" di Google. Workbox semplifica l'implementazione, ad esempio:

import {registerRoute} from 'workbox-routing';

registerRoute(new RegExp('/styles/.*\\.css'), handlerCb);

Per le richieste da parte di stessa origine, questa espressione regolare avrà una corrispondenza finché l'URL della richiesta corrisponde un'espressione regolare.

  • https://example.com/styles/main.css
  • https://example.com/styles/nested/file.css
  • https://example.com/nested/styles/directory.css

Tuttavia, per le richieste multiorigine, le espressioni regolari deve corrispondere all'inizio dell'URL. Il motivo è che improbabile che con un'espressione regolare new RegExp('/styles/.*\\.css') volevi trovare una corrispondenza con i file CSS di terze parti.

  • https://cdn.third-party-site.com/styles/main.css
  • https://cdn.third-party-site.com/styles/nested/file.css
  • https://cdn.third-party-site.com/nested/styles/directory.css

Se volevi seguire questo comportamento, devi solo assicurarti che vengano applicate le normali corrisponde all'inizio dell'URL. Se volessimo abbinare richieste di https://cdn.third-party-site.com potremmo utilizzare dell'espressione new RegExp('https://cdn\\.third-party-site\\.com.*/styles/.*\\.css').

  • https://cdn.third-party-site.com/styles/main.css
  • https://cdn.third-party-site.com/styles/nested/file.css
  • https://cdn.third-party-site.com/nested/styles/directory.css

Se desideri trovare corrispondenze sia di parti locali che di terze parti, puoi utilizzare un carattere jolly all'inizio dell'espressione regolare, ma questa operazione deve essere eseguita con cautela per assicurarti che non causi comportamenti imprevisti nella tua app web.

Come registrare un percorso di navigazione

Se il tuo sito è un'app a pagina singola, puoi utilizzare una Da NavigationRoute a restituiscono una risposta specifica per tutti richieste di navigazione.

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler);
registerRoute(navigationRoute);

Ogni volta che un utente visita il tuo sito nel browser, la richiesta della pagina viene sarà una richiesta di navigazione e verrà pubblicata la pagina /app-shell.html memorizzata nella cache. Nota. Dovresti fare in modo che la pagina venga memorizzata nella cache tramite workbox-precaching o tramite il tuo passaggio di installazione personalizzato.

Per impostazione predefinita, risponderà a tutte le richieste di navigazione. Se vuoi limitalo per rispondere a un sottoinsieme di URL, puoi usare l'allowlist e denylist per limitare le pagine corrispondenti a questo percorso.

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [new RegExp('/blog/')],
  denylist: [new RegExp('/blog/restricted/')],
});
registerRoute(navigationRoute);

L'unica cosa da notare è che il denylist vince se un URL è in entrambi allowlist e denylist.

Imposta un gestore predefinito

Se vuoi fornire un "gestore" per le richieste che non corrispondono a una route, può impostare un gestore predefinito.

import {setDefaultHandler} from 'workbox-routing';

setDefaultHandler(({url, event, params}) => {
  // ...
});

Imposta un gestore cattura

Se una qualsiasi delle tue route genera un errore, puoi acquisire e la riduzione controllata impostando un gestore cattura.

import {setCatchHandler} from 'workbox-routing';

setCatchHandler(({url, event, params}) => {
  ...
});

Definizione di una route per richieste non GET

Per impostazione predefinita, si presume che tutte le route riguardino le richieste GET.

Se vuoi indirizzare altre richieste, ad esempio una richiesta POST, devi per definire il metodo durante la registrazione della route, in questo modo:

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb, 'POST');
registerRoute(new RegExp('/api/.*\\.json'), handlerCb, 'POST');

Logging router

Dovresti essere in grado di determinare il flusso di una richiesta utilizzando i log workbox-routing, che evidenzierà gli URL in fase di elaborazione tramite Workbox.

Log di routing

Se hai bisogno di informazioni più dettagliate, puoi impostare il livello di log su debug in Visualizzare i log delle richieste non gestite dal router. Consulta le nostre guida al debug per ulteriori informazioni su impostare il livello di log.

Debug e log dei messaggi di routing

Utilizzo avanzato

Se vuoi avere un maggiore controllo su quando assegnare il router Workbox richieste, puoi creare le tue Istanza e chiamata di Router è handleRequest() ogni volta che vuoi utilizzare il router per rispondere a una richiesta.

import {Router} from 'workbox-routing';

const router = new Router();

self.addEventListener('fetch', event => {
  const {request} = event;
  const responsePromise = router.handleRequest({
    event,
    request,
  });
  if (responsePromise) {
    // Router found a route to handle the request.
    event.respondWith(responsePromise);
  } else {
    // No route was found to handle the request.
  }
});

Quando usi direttamente Router, dovrai usare anche il corso Route, o una qualsiasi delle classi ampliate per registrare le route.

import {Route, RegExpRoute, NavigationRoute, Router} from 'workbox-routing';

const router = new Router();
router.registerRoute(new Route(matchCb, handlerCb));
router.registerRoute(new RegExpRoute(new RegExp(...), handlerCb));
router.registerRoute(new NavigationRoute(handlerCb));

Tipi

NavigationRoute

NavigationRoute semplifica la creazione di un workbox-routing.Route corrispondente per il browser [richieste di navigazione]https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests.

Corrisponde solo alle richieste in arrivo la cui https://fetch.spec.whatwg.org/#concept-request-mode|mode è impostato su navigate.

Facoltativamente, puoi applicare questa route solo a un sottoinsieme di richieste di navigazione utilizzando uno o entrambi i parametri denylist e allowlist.

Proprietà

  • costruttore

    null

    Se vengono forniti sia denylist sia allowlist, denylist hanno la precedenza e la richiesta non corrisponderà a questa route.

    Le espressioni regolari in allowlist e denylist vengono confrontate con [pathname]https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname e [search]https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/search parti dell'URL richiesto.

    Nota: queste regex possono essere valutate rispetto a ogni URL di destinazione durante una navigazione. Evita di utilizzare RepExp complesse, altrimenti gli utenti potrebbero riscontrare ritardi durante la navigazione sul tuo sito.

    La funzione constructor ha questo aspetto: 

    (handler: RouteHandler, options?: NavigationRouteMatchOptions) => {...}

  • catchHandler

    RouteHandlerObject facoltativo

  • corrispondenza

    RouteMatchCallback

  • method

    HTTPMethod

  • setCatchHandler

    null

    La funzione setCatchHandler ha questo aspetto: 

    (handler: RouteHandler) => {...}

    • handler

      RouteHandler

      Una richiamata funzione che restituisce una promessa che si risolve in una Risposta

NavigationRouteMatchOptions

Proprietà

  • lista consentita

    Espressione regolare[] facoltativa

  • lista non consentita

    Espressione regolare[] facoltativa

RegExpRoute

RegExpRoute semplifica la creazione di espressioni regolari basate workbox-routing.Route

Per le richieste della stessa origine, l'espressione regolare deve corrispondere solo a parte dell'URL. Per richieste contro server di terze parti, devi definire un'espressione regolare che corrisponda all'inizio dell'URL.

Proprietà

  • costruttore

    null

    Se l'espressione regolare contiene [gruppi di acquisizione]https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#grouping-back-references, i valori acquisiti verranno passati params workbox-routing~handlerCallback .

    La funzione constructor ha questo aspetto: 

    (regExp: RegExp, handler: RouteHandler, method?: HTTPMethod) => {...}

    • regExp

      RegExp

      L'espressione regolare per trovare una corrispondenza con gli URL.

    • handler

      RouteHandler

      Una richiamata che restituisce una promessa risultante in una Risposta.

    • method

      HTTPMethod facoltativo

  • catchHandler

    RouteHandlerObject facoltativo

  • corrispondenza

    RouteMatchCallback

  • method

    HTTPMethod

  • setCatchHandler

    null

    La funzione setCatchHandler ha questo aspetto: 

    (handler: RouteHandler) => {...}

    • handler

      RouteHandler

      Una richiamata funzione che restituisce una promessa che si risolve in una Risposta

Route

Un Route è costituito da una coppia di funzioni di callback, "match" e "handler". La "corrispondenza" callback determinano se una route deve essere utilizzata per "gestire" un restituendo un valore non fittizio, se possibile. Il "gestore" callback viene chiamato in caso di corrispondenza e dovrebbe restituire una promessa che si risolve a un Response.

Proprietà

  • costruttore

    null

    Costruttore per la classe Route.

    La funzione constructor ha questo aspetto: 

    (match: RouteMatchCallback, handler: RouteHandler, method?: HTTPMethod) => {...}

    • corrispondenza

      RouteMatchCallback

      Una funzione di callback che determina se la route corrisponde a un determinato fetch evento restituendo un valore non falso.

    • handler

      RouteHandler

      Una richiamata che restituisce una risoluzione Promessa in una Risposta.

    • method

      HTTPMethod facoltativo

  • catchHandler

    RouteHandlerObject facoltativo

  • corrispondenza

    RouteMatchCallback

  • method

    HTTPMethod

  • setCatchHandler

    null

    La funzione setCatchHandler ha questo aspetto: 

    (handler: RouteHandler) => {...}

    • handler

      RouteHandler

      Una richiamata funzione che restituisce una promessa che si risolve in una Risposta

Router

Il router può essere utilizzato per elaborare un FetchEvent usando uno o più workbox-routing.Route, risponde con un Response se esiste una route corrispondente.

Se nessuna route corrisponde a una determinata richiesta, il router utilizzerà un valore "predefinito" , se presente.

Se la route corrispondente genera un errore, il router utilizzerà un comando "catch" di gestione se uno è definito per affrontare i problemi e rispondere con Richiedi.

Se una richiesta corrisponde a più route, verrà visualizzata la route registrata prima. da utilizzare per rispondere alla richiesta.

Proprietà

  • costruttore

    null

    Inizializza un nuovo router.

    La funzione constructor ha questo aspetto: 

    () => {...}

  • route

    Map&lt;HTTPMethodRoute[]&gt;

  • addCacheListener

    null

    Aggiunge un listener di eventi di messaggi per gli URL da memorizzare nella cache dalla finestra. Ciò è utile per memorizzare nella cache le risorse caricate sulla pagina prima di quando il service worker ha iniziato a controllarlo.

    Il formato dei dati del messaggio inviati dalla finestra dovrebbe essere il seguente. In cui l'array urlsToCache può essere composto da stringhe URL o da un array di Stringa URL + oggetto requestInit (la stessa che passeresti a fetch()).

    {
  type: 'CACHE_URLS',
  payload: {
    urlsToCache: [
      './script1.js',
      './script2.js',
      ['./script3.js', {mode: 'no-cors'}],
    ],
  },
}

    La funzione addCacheListener ha questo aspetto: 

    () => {...}

  • addFetchListener

    null

    Aggiunge un listener di eventi di recupero per rispondere agli eventi in caso di corrispondenza di una route la richiesta dell'evento.

    La funzione addFetchListener ha questo aspetto: 

    () => {...}

  • findMatchingRoute

    null

    Confronta una richiesta e un URL (e, facoltativamente, un evento) a fronte dell'elenco di route registrate e, se c'è una corrispondenza, restituisce il insieme agli eventuali parametri generati dalla corrispondenza.

    La funzione findMatchingRoute ha questo aspetto: 

    (options: RouteMatchCallbackOptions) => {...}

    • returns

      oggetto

      Un oggetto con le proprietà route e params. Vengono compilate se è stata trovata una route corrispondente o undefined negli altri casi.

  • handleRequest

    null

    Applica le regole di routing a un oggetto FetchEvent per ottenere una risposta da un il gestore della route appropriato.

    La funzione handleRequest ha questo aspetto: 

    (options: object) => {...}

    • opzioni

      oggetto

      • evento

        ExtendableEvent

        L'evento che ha attivato richiesta.

      • richiesta

        Richiesta

        La richiesta da gestire.

    • returns

      Promise&lt;Response&gt;

      Viene restituita una promessa se una route registrata può gestire la richiesta. Se non vengono trovate corrispondenze route e non sono previsti defaultHandler, viene restituito undefined.

  • registerRoute

    null

    Registra un percorso con il router.

    La funzione registerRoute ha questo aspetto: 

    (route: Route) => {...}

    • percorso

      Route

      Il percorso da registrare.

  • setCatchHandler

    null

    Se una route genera un errore durante la gestione di una richiesta, handler verrà chiamato e avrà la possibilità di fornire una risposta.

    La funzione setCatchHandler ha questo aspetto: 

    (handler: RouteHandler) => {...}

    • handler

      RouteHandler

      Una richiamata che restituisce una promessa risultante in una Risposta.

  • setDefaultHandler

    null

    Definisci un handler predefinito che viene chiamato quando non esistono route esplicite corrispondono alla richiesta in arrivo.

    Ogni metodo HTTP ("GET", "POST" e così via) riceve il proprio gestore predefinito.

    Senza un gestore predefinito, le richieste senza corrispondenza andranno contro come se non fosse presente un service worker.

    La funzione setDefaultHandler ha questo aspetto: 

    (handler: RouteHandler, method?: HTTPMethod) => {...}

    • handler

      RouteHandler

      Una richiamata che restituisce una promessa risultante in una Risposta.

    • method

      HTTPMethod facoltativo

  • unregisterRoute

    null

    Consente di annullare la registrazione di una route con il router.

    La funzione unregisterRoute ha questo aspetto: 

    (route: Route) => {...}

    • percorso

      Route

      Il percorso per annullare la registrazione.

Metodi

registerRoute()

workbox-routing.registerRoute(
  capture: string | RegExp | RouteMatchCallback | Route,
  handler?: RouteHandler,
  method?: HTTPMethod,
)

Registra facilmente un'espressione regolare, una stringa o una funzione con una memorizzazione nella cache la tua strategia a un'istanza singleton Router.

Questo metodo genererà una route per te, se necessario. chiama workbox-routing.Router#registerRoute.

Parametri

  • registrare

    string | Espressione regolare | RouteMatchCallback | Itinerario

    Se il parametro di acquisizione è un Route, tutti gli altri argomenti verranno ignorati.

  • handler

    RouteHandler (facoltativo)

  • method

    HTTPMethod facoltativo

Resi

  • L'elemento Route generato.

setCatchHandler()

workbox-routing.setCatchHandler(
  handler: RouteHandler,
)

Se una route genera un errore durante la gestione di una richiesta, handler verrà chiamato e avrà la possibilità di fornire una risposta.

Parametri

  • handler

    RouteHandler

    Una richiamata che restituisce una promessa risultante in una Risposta.

setDefaultHandler()

workbox-routing.setDefaultHandler(
  handler: RouteHandler,
)

Definisci un handler predefinito che viene chiamato quando non esistono route esplicite corrispondono alla richiesta in entrata.

Senza un gestore predefinito, le richieste senza corrispondenza andranno contro come se non fosse presente un service worker.

Parametri

  • handler

    RouteHandler

    Una richiamata che restituisce una promessa risultante in una Risposta.