工作箱路由

Service Worker 可攔截網頁的網路要求。它可能會以快取內容、網路內容或服務工作站產生的內容對瀏覽器做出回應。

workbox-routing 模組可讓您輕鬆將這些要求「轉送」至提供回應的不同函式。

轉送執行方式

當網路要求造成 Service Worker 擷取事件時，workbox-routing 會嘗試使用提供的路徑和處理常式回應要求。

上文需要注意的是：

• 要求的方法相當重要。根據預設，路徑會註冊用於 GET 要求。如要攔截其他類型的要求，您需要指定方法。

• 路線登錄順序相當重要。如果註冊了多個路徑可以處理要求，則優先登錄的路徑會用來回應要求。

註冊路徑的幾種方式如下：您可以使用回呼、規則運算式或路徑執行個體。

在路徑中比對及處理

工作箱中的「route」是指兩個函式，兩者都是「matching」函式，用於判斷路徑是否應符合要求，而「處理」函式則應處理要求並回應。

Workbox 提供了一些輔助程式，可為您執行比對和處理作業，但如果發現自己需要不同的行為，請撰寫自訂比對和處理常式函式。

比對回呼函式會傳遞 ExtendableEvent、Request 及可傳回傾斜值比對的 URL 物件。舉個簡單的例子，您可以比對特定網址，如下所示：

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

大部分用途都能透過檢查 / 測試 url 或 request 來涵蓋。

處理常式回呼函式會具有相同的 ExtendableEvent、Request 和 URL 物件與 params 值，也就是「match」函式傳回的值。

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,
  });
};

您的處理常式必須傳回會解析為 Response 的承諾。在此範例中，我們使用的是 async 和 await。實際上，回傳的 Response 值會納入承諾內容中。

您可以註冊這些回呼，如下所示：

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb);

唯一的限制是「比對」回呼「必須」同步傳回超值值，因此您無法執行任何非同步工作。這是因為 Router 必須同步回應擷取事件，或允許傳送至其他擷取事件。

在一般情況下，「handler」回呼會使用 workbox-Strategyies 提供的其中一項策略，如下所示：

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

registerRoute(matchCb, new StaleWhileRevalidate());

本頁面將著重於 workbox-routing，但您可以進一步瞭解這些與工作相關的策略。

如何註冊規則運算式路徑

常見的做法是使用規則運算式，而不是「match」回呼。Workbox 提供簡單的實作方式，如下所示：

import {registerRoute} from 'workbox-routing';

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

針對來自相同來源的要求，只要要求的網址與規則運算式相符，這個規則運算式就會進行比對。

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

不過，如果是跨來源要求，規則運算式必須與網址開頭相符。這是因為您可能使用規則運算式 new RegExp('/styles/.*\\.css') 來比對第三方 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

如果「did」想要這個行為，您只需確保規則運算式與網址開頭相符即可。如要比對 https://cdn.third-party-site.com 的要求，可以使用規則運算式 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

如果想同時比對本機和第三方，可以在規則運算式的開頭使用萬用字元，但請務必謹慎行事，確保您的網站不會導致網頁應用程式發生非預期行為。

如何註冊導覽路徑

如果您的網站是單一頁面應用程式，可以使用 NavigationRoute 傳回所有導覽要求的特定回應。

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);

每當使用者在瀏覽器中前往您的網站，頁面要求就會成為瀏覽要求，並傳送快取頁面 /app-shell.html。 (注意：您應該透過 workbox-precaching 或自己的安裝步驟要求快取網頁。)

根據預設，這個屬性會回應「所有」瀏覽要求。如要限制網址只能回應部分網址，可以使用 allowlist 和 denylist 選項來限制哪些網頁與這個路徑相符。

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);

請注意，如果網址同時位於 allowlist 和 denylist 中，denylist 將會勝出。

設定預設處理常式

如果您想為不符合路徑的要求提供「處理常式」，可以設定預設處理常式。

import {setDefaultHandler} from 'workbox-routing';

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

設定接收處理常式

萬一任何路徑擲回錯誤，您可以設定擷取處理常式，以便順利擷取並降級。

import {setCatchHandler} from 'workbox-routing';

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

定義非 GET 要求的路徑

根據預設，所有路徑都會假設為 GET 要求。

如要轉送其他要求 (例如 POST 要求)，您必須在註冊路線時定義方法，如下所示：

import {registerRoute} from 'workbox-routing';

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

路由器記錄

您可以使用 workbox-routing 的記錄判斷要求的流程，並醒目顯示要透過 Workbox 處理的網址。

如果您需要更詳細的資訊，可以將記錄層級設為 debug，以查看路由器未處理要求的相關記錄。如要進一步瞭解如何設定記錄層級，請參閱偵錯指南。

進階用法

如要進一步控管向 Workbox 路由器發出要求的時間，您可以建立自己的 Router 執行個體，並在每次使用路由器回應要求時呼叫 handleRequest() 方法。

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.
  }
});

直接使用 Router 時，也需要使用 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));

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

workbox-routing.setCatchHandler(
  handler: RouteHandler,
)

workbox-routing.setDefaultHandler(
  handler: RouteHandler,
)