InstallEvent: addRoutes() 方法

語法

addRoutes(routerRules)

引數

routerRules

一個單獨的物件，或一個或多個物件的陣列，代表瞭如何獲取某些資源的規則。每個 routerRules 物件包含以下屬性：

條件

一個定義了一個或多個條件的 **condition** 物件，用於指定哪些資源應該匹配此規則。可以包含以下屬性；如果使用了多個屬性，則資源必須滿足所有指定的條件才能匹配規則。

not 可選

一個 **condition** 物件，定義了必須顯式 **不** 滿足的條件才能匹配規則。在 not 條件內部定義的條件與其他條件是互斥的。

or 可選

一個 **condition** 物件的陣列。必須滿足這些定義的條件之一才能匹配規則。在 or 條件內部定義的條件與其他條件是互斥的。

requestMethod 可選

一個字串，表示請求應使用的 HTTP 方法，以便匹配規則，例如 "get"、"put" 或 "head"。

requestMode 可選

一個字串，表示請求應具有的 模式，以便匹配規則，例如 "same-origin"、"no-cors" 或 "cors"。

requestDestination 可選

一個字串，表示請求的 目標，即應該請求的內容型別，以便匹配規則。例如包括 "audio"、"document"、"script" 和 "worker"。

runningStatus 可選

一個列舉值，表示 Service Worker 的必需執行狀態，以便請求匹配規則。可能的值為 "running" 或 "not-running"。

urlPattern 可選

一個 URLPattern 例項，或一個 URLPattern() 建構函式的 input 模式，表示與規則匹配的 URL。不允許使用正則表示式捕獲組，因此 URLPattern.hasRegExpGroups 必須為 false。

source

一個列舉值或一個物件，用於指定將從哪個源載入匹配的資源。可能的列舉值是：

"cache"

資源將從瀏覽器 Cache 載入。

"fetch-event"

資源將透過 Service Worker 的 fetch 事件處理程式載入。這可以與 "runningStatus" 條件結合使用，以便在 Service Worker 執行時從其載入資源，並在其未執行時回退到網路上的靜態路由。

"network"

資源將從網路載入。

"race-network-and-fetch-handler"

同時嘗試從網路和 Service Worker 的 fetch 事件處理程式載入資源。哪個先完成就使用哪個。

source 值也可以設定為一個物件，其中包含一個名為 cacheName 的屬性，其值為一個字串，表示瀏覽器 Cache 的名稱。如果存在，匹配的資源將從這個特定的命名快取載入。

返回值

一個 Promise，它將以 undefined 解析。

異常

TypeError DOMException

當 routerRules 中的一個或多個規則物件無效，或者其 source 值為 "fetch-event" 但關聯的 Service Worker 沒有 fetch 事件處理程式時，會丟擲此錯誤。如果您嘗試將 or 與其他條件型別結合使用，也會丟擲此錯誤。

示例

當 Service Worker 未執行時，將特定請求路由到網路

在以下示例中，以 /articles 開頭的 URL 將在 Service Worker 當前未執行時路由到網路。

addEventListener("install", (event) => {
  event.addRoutes({
    condition: {
      urlPattern: "/articles/*",
      runningStatus: "not-running",
    },
    source: "network",
  });
});

將表單 POST 請求路由到網路

在以下示例中，傳送到表單的 POST 請求將直接傳送到網路，並繞過 Service Worker。

addEventListener("install", (event) => {
  event.addRoutes({
    condition: {
      urlPattern: "/form/*",
      requestMethod: "post",
    },
    source: "network",
  });
});

將某些圖片型別請求路由到命名快取

在以下示例中，瀏覽器 Cache 名為 "pictures" 的快取用於獲取副檔名為 .png 或 .jpg 的檔案。

addEventListener("install", (event) => {
  event.addRoutes({
    condition: {
      or: [{ urlPattern: "*.png" }, { urlPattern: "*.jpg" }],
    },
    source: {
      cacheName: "pictures",
    },
  });
});

您不能將 or 與其他條件結合使用，這會導致 TypeError。例如，如果您想匹配副檔名為 .png 或 .jpg 的檔案，但僅當 requestMethod 是 get 時，您需要指定兩個單獨的條件。

addEventListener("install", (event) => {
  event.addRoutes(
    {
      condition: {
        urlPattern: "*.png",
        requestMethod: "get",
      },
      source: {
        cacheName: "pictures",
      },
    },
    {
      condition: {
        urlPattern: "*.jpg",
        requestMethod: "get",
      },
      source: {
        cacheName: "pictures",
      },
    },
  );
});

規範

瀏覽器相容性

另見

• InstallEvent
• install 事件
• Service Worker API
• 使用 Service Worker 靜態路由 API 為特定路徑繞過 Service Worker，來自 developer.chrome.com (2024)