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)