工作框策略

首次引入 Service Worker 时，出现了一组常见的缓存策略。缓存策略是一种模式，用于确定服务工件在收到提取事件后如何生成响应。

workbox-strategies 提供了最常见的缓存策略，因此您可以轻松在 Service Worker 中应用这些策略。

除了 Workbox 支持的策略之外，我们不会详细介绍其他策略，但您可以参阅离线食谱了解详情。

使用策略

在以下示例中，我们将展示如何将 Workbox 缓存策略与 workbox-routing 搭配使用。您可以为每种策略定义一些选项，这些选项在本文档的“配置策略”部分中有所介绍。

在“高级使用”部分中，我们将介绍如何在不使用 workbox-routing 的情况下直接使用缓存策略。

Stale-While-Revalidate

借助“stale-while-revalidate”模式，您可以使用缓存的响应（如果有）尽快响应请求，如果没有缓存的响应，则回退到网络请求。然后，系统会使用网络请求更新缓存。与“在重新验证时使用过时数据”的某些实现不同，此策略始终会发出重新验证请求，无论缓存响应的年龄如何。

这是一种相当常见的策略，对于应用而言，拥有最新的资源并不是至关重要的。

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

registerRoute(
  ({url}) => url.pathname.startsWith('/images/avatars/'),
  new StaleWhileRevalidate()
);

缓存优先（缓存回退到网络）

离线 Web 应用将严重依赖于缓存，但对于非关键且可以逐步缓存的资源，先缓存是最佳选项。

如果缓存中存在响应，系统将使用缓存的响应来执行请求，而不会使用网络。如果没有缓存的响应，系统会通过网络请求来执行请求，并将响应缓存起来，以便直接从缓存中提供下一个请求。

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

registerRoute(({request}) => request.destination === 'style', new CacheFirst());

优先使用网络（网络回退到缓存）

对于频繁更新的请求，网络优先策略是理想的解决方案。默认情况下，它会尝试从网络提取最新的响应。如果请求成功，系统会将响应放入缓存中。如果网络未能返回响应，系统将使用缓存的响应。

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

registerRoute(
  ({url}) => url.pathname.startsWith('/social-timeline/'),
  new NetworkFirst()
);

仅限影音平台

如果您需要从广告联盟中执行特定请求，则应采用仅限广告联盟策略。

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

registerRoute(({url}) => url.pathname.startsWith('/admin/'), new NetworkOnly());

仅缓存

仅缓存策略可确保从缓存中获取响应。在 Workbox 中，这种情况不太常见，但如果您有自己的预缓存步骤，则可能很有用。

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

registerRoute(({url}) => url.pathname.startsWith('/app/v2/'), new CacheOnly());

配置策略

您可以通过以下所有策略进行配置：

• 要用于策略的缓存的名称。
• 要在策略中使用的缓存过期限制。
• 一个插件数组，系统会在提取和缓存请求时调用其生命周期方法。

更改策略使用的缓存

您可以通过提供缓存名称来更改使用的缓存策略。如果您想将资源分离以便调试，这会很有用。

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

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
  })
);

使用插件

Workbox 附带一组可与这些策略搭配使用的插件。

• workbox-background-sync
• workbox-broadcast-update
• workbox-cacheable-response
• workbox-expiration
• workbox-range-requests

如需使用这些插件（或自定义插件）中的任何一个，您只需将实例传入 plugins 选项即可。

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

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new ExpirationPlugin({
        // Only cache requests for a week
        maxAgeSeconds: 7 * 24 * 60 * 60,
        // Only cache 10 requests.
        maxEntries: 10,
      }),
    ],
  })
);

自定义策略

除了配置策略之外，Workbox 还允许您创建自己的自定义策略。为此，您可以从 workbox-strategies 导入并扩展 Strategy 基类：

import {Strategy} from 'workbox-strategies';

class NewStrategy extends Strategy {
  _handle(request, handler) {
    // Define handling logic here
  }
}

在此示例中，handle() 用作请求策略来定义特定的处理逻辑。您可以使用以下两种请求策略：

• handle()：执行请求策略并返回一个将解析为 Response 的 Promise，从而调用所有相关的插件回调。
• handleAll()：类似于 handle()，但会返回两个 Promise 对象。第一个等效于 handle() 返回的内容，第二个将在策略中添加到 event.waitUntil() 的 promise 完成时解析。

这两种请求策略都使用以下两个参数进行调用：

• request：策略将针对哪个 Request 返回响应。
• handler：为当前策略自动创建的 StrategyHandler 实例。

制定新策略

以下是一个重新实现 NetworkOnly 行为的新策略示例：

class NewNetworkOnlyStrategy extends Strategy {
  _handle(request, handler) {
    return handler.fetch(request);
  }
}

请注意，系统会调用 handler.fetch()，而不是原生 fetch 方法。StrategyHandler 类提供了多项提取和缓存操作，可在使用 handle() 或 handleAll() 时使用：

• fetch：提取给定请求，并调用 requestWillFetch()、fetchDidSucceed() 和 fetchDidFail() 插件生命周期方法
• cacheMatch：匹配缓存中的请求，并调用 cacheKeyWillBeUsed() 和 cachedResponseWillBeUsed() 插件生命周期方法
• cachePut：将请求/响应对放入缓存，并调用 cacheKeyWillBeUsed()、cacheWillUpdate() 和 cacheDidUpdate() 插件生命周期方法
• fetchAndCachePut：调用 fetch()，并在后台针对 fetch() 生成的响应运行 cachePut()。
• hasCallback：将回调作为输入，如果策略至少包含一个具有给定回调的插件，则返回 true。
• runCallbacks：按顺序运行与给定名称匹配的所有插件回调，并将给定参数对象（与当前插件状态合并）作为唯一参数传递。
• iterateCallbacks：接受回调并返回包含匹配插件回调的可迭代对象，其中每个回调都封装在当前处理程序状态中（即，当您调用每个回调时，您传递给它的任何对象参数都将与插件的当前状态合并）。
• waitUntil：向与正在处理的请求关联的事件（通常为 FetchEvent）的生命周期延长 promise 中添加 promise。
• doneWaiting：返回一个 Promise，该 Promise 会在传递给 waitUntil() 的所有 Promise 都已解决后解析。
• destroy：停止运行策略，并立即解析所有待处理的 waitUntil() promise。

注意：请参阅 StrategyHandler 的源代码实现，查看每个操作接受的所有参数

自定义缓存网络争用策略

以下示例基于离线食谱中的 cache-network-race（Workbox 不提供），但更进一步，在网络请求成功后始终更新缓存。这是使用多个操作的更复杂策略示例。

import {Strategy} from 'workbox-strategies';

class CacheNetworkRace extends Strategy {
  _handle(request, handler) {
    const fetchAndCachePutDone = handler.fetchAndCachePut(request);
    const cacheMatchDone = handler.cacheMatch(request);

    return new Promise((resolve, reject) => {
      fetchAndCachePutDone.then(resolve);
      cacheMatchDone.then(response => response && resolve(response));

      // Reject if both network and cache error or find no response.
      Promise.allSettled([fetchAndCachePutDone, cacheMatchDone]).then(
        results => {
          const [fetchAndCachePutResult, cacheMatchResult] = results;
          if (
            fetchAndCachePutResult.status === 'rejected' &&
            !cacheMatchResult.value
          ) {
            reject(fetchAndCachePutResult.reason);
          }
        }
      );
    });
  }
}

高级用法

如果您想在自己的提取事件逻辑中使用这些策略，可以使用策略类通过特定策略运行请求。

例如，如需使用“在重新验证期间使用过时数据”策略，您可以执行以下操作：

self.addEventListener('fetch', event => {
  const {request} = event;
  const url = new URL(request.url);

  if (url.origin === location.origin && url.pathname === '/') {
    event.respondWith(new StaleWhileRevalidate().handle({event, request}));
  }
});

您可以在 workbox-strategies 参考文档中找到可用类的列表。

类型

CacheFirst

缓存优先请求策略的实现。

缓存优先策略对已修订的资源（例如 /styles/example.a8f5f1.css 等网址）非常有用，因为它们可以缓存很长时间。

如果网络请求失败且没有缓存匹配项，系统会抛出 WorkboxError 异常。

属性

• 构造函数

  void

  创建策略的新实例，并将所有记录的选项属性设置为公共实例属性。

  注意：如果自定义策略类扩展了基准 Strategy 类，并且不需要超出这些属性，则无需定义自己的构造函数。

  constructor 函数如下所示：

  (options?: StrategyOptions) => {...}

  • 选项

    StrategyOptions（可选）

  • 返回

    CacheFirst

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 两个 Promise 的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

CacheOnly

仅缓存请求策略的实现。

如果您想利用任何 Workbox 插件，此类会非常有用。

如果没有缓存匹配项，则会抛出 WorkboxError 异常。

属性

• 构造函数

  void

  创建策略的新实例，并将所有记录的选项属性设置为公共实例属性。

  注意：如果自定义策略类扩展了基准 Strategy 类，并且不需要超出这些属性，则无需定义自己的构造函数。

  constructor 函数如下所示：

  (options?: StrategyOptions) => {...}

  • 选项

    StrategyOptions（可选）

  • 返回

    CacheOnly

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 两个 Promise 的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

NetworkFirst

网络优先请求策略的实现。

默认情况下，此策略会缓存状态代码为 200 的响应以及不透明响应。不透明响应是指响应不支持 CORS 的跨源请求。

如果网络请求失败且没有缓存匹配项，系统会抛出 WorkboxError 异常。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (options?: NetworkFirstOptions) => {...}

  • 选项

    NetworkFirstOptions（可选）

  • 返回

    NetworkFirst

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 两个 Promise 的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

NetworkFirstOptions

属性

• cacheName

  字符串（选填）

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• networkTimeoutSeconds

  number 可选

• 插件

  WorkboxPlugin[] 可选

NetworkOnly

仅限网络请求策略的实现。

如果您想利用任何 Workbox 插件，此类会非常有用。

如果网络请求失败，这将引发 WorkboxError 异常。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (options?: NetworkOnlyOptions) => {...}

  • 选项

    NetworkOnlyOptions 可选

  • 返回

    NetworkOnly

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 两个 Promise 的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

NetworkOnlyOptions

属性

• fetchOptions

  RequestInit（可选）

• networkTimeoutSeconds

  number 可选

• 插件

  WorkboxPlugin[] 可选

StaleWhileRevalidate

“在重新验证期间过时”请求策略的实现。

系统会并行从缓存和网络请求资源。该策略将使用已缓存的版本做出响应（如果有），否则等待网络响应。每次成功请求时，缓存都会使用网络响应进行更新。

默认情况下，此策略会缓存状态代码为 200 的响应以及不透明响应。不透明响应是指响应不支持 CORS 的跨源请求。

如果网络请求失败且没有缓存匹配项，系统会抛出 WorkboxError 异常。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (options?: StrategyOptions) => {...}

  • 选项

    StrategyOptions（可选）

  • 返回

    StaleWhileRevalidate

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 两个 Promise 的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

Strategy

所有其他策略类都必须从中扩展的抽象基类：

属性

• 构造函数

  void

  创建策略的新实例，并将所有记录的选项属性设置为公共实例属性。

  注意：如果自定义策略类扩展了基准 Strategy 类，并且不需要超出这些属性，则无需定义自己的构造函数。

  constructor 函数如下所示：

  (options?: StrategyOptions) => {...}

  • 选项

    StrategyOptions（可选）

  • 返回

    策略

• cacheName

  字符串

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[]

• _awaitComplete

  void

  _awaitComplete 函数如下所示：

  (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • responseDone

    Promise<Response>

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<void>

• _getResponse

  void

  _getResponse 函数如下所示：

  (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

  • handler

    StrategyHandler

  • request

    请求

  • 事件

    ExtendableEvent

  • 返回

    Promise<Response>

• _handle

  void

  _handle 函数如下所示：

  (request: Request, handler: StrategyHandler) => {...}

  • request

    请求

  • handler

    StrategyHandler

  • 返回

    Promise<Response>

• 句柄

  void

  执行请求策略并返回一个 Promise，该 Promise 将解析为 Response，并调用所有相关的插件回调。

  将策略实例注册到 Workbox workbox-routing.Route 后，当路由匹配时，系统会自动调用此方法。

  或者，您也可以将此方法传递给 event.respondWith()，以便在独立的 FetchEvent 监听器中使用此方法。

  handle 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    Promise<Response>

• handleAll

  void

  与 workbox-strategies.Strategy~handle 类似，但它不会仅返回解析为 Response 的 Promise，而是会返回一个 [response, done] promise 元组，其中前者 (response) 等同于 handle() 返回的内容，而后者是一个 promise，在执行策略过程中添加到 event.waitUntil() 的所有 promise 完成后，它会解析。

  您可以等待 done promise，以确保策略执行的任何额外工作（通常是缓存响应）都成功完成。

  handleAll 函数如下所示：

  (options: FetchEvent | HandlerCallbackOptions) => {...}

  • 选项

    FetchEvent | HandlerCallbackOptions

    FetchEvent 或具有以下属性的对象。

  • 返回

    [Promise<Response>, Promise<void>]

    [response, done] 承诺的元组，可用于确定响应何时解析以及处理程序何时完成所有工作。

StrategyHandler

每次 Strategy 实例调用 workbox-strategies.Strategy~handle 或 workbox-strategies.Strategy~handleAll 时都会创建一个类，该类会将所有提取和缓存操作封装在插件回调中，并跟踪策略何时“完成”（即所有添加的 event.waitUntil() promise 均已解析）。

属性

• 构造函数

  void

  创建与传递的策略和正在处理请求的事件关联的新实例。

  该构造函数还会初始化将传递给处理此请求的每个插件的状态。

  constructor 函数如下所示：

  (strategy: Strategy, options: HandlerCallbackOptions) => {...}

  • 策略

    策略

  • 选项

    HandlerCallbackOptions

  • 返回

    StrategyHandler

• 事件

  ExtendableEvent

• params

  任意（可选）

• request

  请求

• 网址

  网址（可选）

• cacheMatch

  void

  使用策略对象上定义的 cacheName、matchOptions 和 plugins 从缓存中匹配请求（并调用所有适用的插件回调方法）。

  使用此方法时，系统会调用以下插件生命周期方法：

  • cacheKeyWillBeUsed()
  • cachedResponseWillBeUsed()

  cacheMatch 函数如下所示：

  (key: RequestInfo) => {...}

  • 键

    RequestInfo

    要用作缓存键的请求或网址。

  • 返回

    Promise<Response>

    匹配的回答（如果有）。

• cachePut

  void

  使用策略对象上定义的 cacheName 和 plugins 将请求/响应对放入缓存中（并调用所有适用的插件回调方法）。

  使用此方法时，系统会调用以下插件生命周期方法：

  • cacheKeyWillBeUsed()
  • cacheWillUpdate()
  • cacheDidUpdate()

  cachePut 函数如下所示：

  (key: RequestInfo, response: Response) => {...}

  • 键

    RequestInfo

    要用作缓存键的请求或网址。

  • Response

    响应

    要缓存的响应。

  • 返回

    Promise<boolean>

    如果 cacheWillUpdate 导致响应未缓存，则为 false；否则为 true。

• 销毁

  void

  停止运行策略，并立即解析所有待处理的 waitUntil() promise。

  destroy 函数如下所示：

  () => {...}

• doneWaiting

  void

  返回一个 promise，该 promise 会在传递给 workbox-strategies.StrategyHandler~waitUntil 的所有 promise 都已解决后解析。

  注意：在 doneWaiting() 稳定后执行的所有工作都应手动传递给事件的 waitUntil() 方法（而非此处理脚本的 waitUntil() 方法），否则服务工件线程可能会在工作完成之前被终止。

  doneWaiting 函数如下所示：

  () => {...}

  • 返回

    Promise<void>

• 提取

  void

  使用 Strategy 对象上定义的 fetchOptions（适用于非导航请求）和 plugins 提取给定请求（并调用所有适用的插件回调方法）。

  使用此方法时，系统会调用以下插件生命周期方法：

  • requestWillFetch()
  • fetchDidSucceed()
  • fetchDidFail()

  fetch 函数如下所示：

  (input: RequestInfo) => {...}

  • 输入

    RequestInfo

    要提取的网址或请求。

  • 返回

    Promise<Response>

• fetchAndCachePut

  void

  调用 this.fetch()，并在后台对 this.fetch() 生成的响应运行 this.cachePut()。

  对 this.cachePut() 的调用会自动调用 this.waitUntil()，因此您无需手动对事件调用 waitUntil()。

  fetchAndCachePut 函数如下所示：

  (input: RequestInfo) => {...}

  • 输入

    RequestInfo

    要提取和缓存的请求或网址。

  • 返回

    Promise<Response>

• getCacheKey

  void

  检查 cacheKeyWillBeUsed 回调的插件列表，并按顺序执行找到的任何回调。最后一个插件返回的最终 Request 对象会被视为缓存读取和/或写入的缓存键。如果未注册任何 cacheKeyWillBeUsed 插件回调，则系统会原封不动地返回传递的请求

  getCacheKey 函数如下所示：

  (request: Request, mode: "read" 
    | "write" 
   ) => {...}

  • request

    请求

  • 模式

    “read”
     | “write”
    

  • 返回

    Promise<Request>

• hasCallback

  void

  如果策略至少包含一个具有给定回调的插件，则返回 true。

  hasCallback 函数如下所示：

  (name: C) => {...}

  • name

    C

    要检查的回调的名称。

  • 返回

    布尔值

• iterateCallbacks

  void

  接受一个回调并返回一个包含匹配插件回调的可迭代对象，其中每个回调都封装在当前处理程序状态中（即，当您调用每个回调时，您传递给它的任何对象参数都将与插件的当前状态合并）。

  iterateCallbacks 函数如下所示：

  (name: C) => {...}

  • name

    C

    要运行的回调的名称

  • 返回

    Generator<NonNullable<indexedAccess>anyunknown>

• runCallbacks

  void

  按顺序运行与给定名称匹配的所有插件回调，并将给定参数对象（与当前插件状态合并）作为唯一参数传递。

  注意：由于此方法会运行所有插件，因此不适用于在调用下一个回调之前需要应用回调的返回值的情况。请参阅下文workbox-strategies.StrategyHandler#iterateCallbacks，了解如何处理此类情况。

  runCallbacks 函数如下所示：

  (name: C, param: Omit<indexedAccess"state" 
   >) => {...}

  • name

    C

    要在每个插件中运行的回调的名称。

  • param

    Omit<indexedAccess"state"
    >

    在执行每个回调时，要作为第一个（也是唯一一个）参数传递的对象。此对象将在执行回调之前与当前插件状态合并。

  • 返回

    Promise<void>

• waitUntil

  void

  将 promise 添加到与正在处理的请求关联的事件（通常为 FetchEvent）的 [extend lifetime promises]https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises。

  注意：您可以 await workbox-strategies.StrategyHandler~doneWaiting 来了解所有添加的 promise 何时都已解决。

  waitUntil 函数如下所示：

  (promise: Promise<T>) => {...}

  • promise

    Promise<T>

    要添加到触发请求的事件的延长生命周期 promise 中的 promise。

  • 返回

    Promise<T>

StrategyOptions

属性

• cacheName

  字符串（选填）

• fetchOptions

  RequestInit（可选）

• matchOptions

  CacheQueryOptions（可选）

• 插件

  WorkboxPlugin[] 可选