工作框核心

Workbox 构建为模块化,允许开发者选择他们想要使用的内容,而无需强制他们将所有内容下载到单个文件中。

不过,模块之间存在重叠,例如,每个模块都需要与控制台交互、抛出有意义的错误以及使用网络或缓存。为避免每个模块实现相同的逻辑,workbox-core 包含每个模块所依赖的这些通用代码。

此模块确实为开发者提供了某些功能,但除了日志级别和缓存之外,workbox-core 还为每个模块(而不是最终开发者)提供内部逻辑。

查看和更改默认缓存名称

Workbox 通过 cacheNames 定义其缓存:

import {cacheNames} from 'workbox-core';

console.log(cacheNames.precache);
console.log(cacheNames.runtime);
console.log(cacheNames.googleAnalytics);

这些缓存名称采用前缀、名称和后缀格式构建,其中名称会根据缓存的使用情况而变化。

<prefix>-<cache-id>-<suffix>

您可以通过更改传递给 setCacheNameDetails() 的所有或部分值来更改这些默认名称。

import {cacheNames, setCacheNameDetails} from 'workbox-core';

setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'install-time',
  runtime: 'run-time',
  googleAnalytics: 'ga',
});

// Will print 'my-app-install-time-v1'
console.log(cacheNames.precache);

// Will print 'my-app-run-time-v1'
console.log(cacheNames.runtime);

// Will print 'my-app-ga-v1'
console.log(cacheNames.googleAnalytics);

前缀和后缀的主要用例是,如果您将 Workbox 用于多个项目,并为每个项目使用相同的 localhost 端口,请为每个模块设置自定义前缀,以防止缓存相互冲突。

客户索赔

一些开发者希望能够发布新的 Service Worker,并使其在激活后立即控制已经打开的网页,而这默认不会发生。

如果您希望这种行为,可以使用 workbox-core 提供的辅助方法:

import {clientsClaim} from 'workbox-core';

// This clientsClaim() should be at the top level
// of your service worker, not inside of, e.g.,
// an event handler.
clientsClaim();

workbox-core 中的 clientsClaim() 方法会自动向 Service Worker 添加 activate 事件监听器,并在其中调用 self.clients.claim()。在当前 Service Worker 激活之前调用 self.clients.claim() 将会导致运行时异常,而 workbox-core 的封装容器有助于确保您在正确的时间调用它。

废弃了 skipWaiting 封装容器

在 Workbox v6 之前,我们还建议开发者使用 workbox-core 中的 skipWaiting() 方法。不过,除了开发者显式调用 self.skipWaiting() 之外,此方法几乎没有什么价值。

由于旧版 workbox-core 封装容器还注册了 install 事件处理脚本,并在其中调用了 self.skipWaiting(),因此如果封装容器在安装完成后在另一个事件处理脚本(例如 message)内被调用,该封装容器将无法按预期运行。

出于这些原因,workbox-coreskipWaiting() 已废弃,开发者应改为直接调用 self.skipWaiting()。与 self.clients.claim() 不同,在“错误”时间调用 self.skipWaiting() 不会抛出异常,因此无需将其封装在事件处理脚本中。

类型

CacheDidUpdateCallback()

workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
)

返回

  • Promise<void>

CacheDidUpdateCallbackParam

属性

  • cacheName

    string

  • event

    ExtendableEvent

  • newResponse

    响应

  • oldResponse

    回复(可选)

  • request

    请求

  • state

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

返回

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

属性

  • cacheName

    string

  • cachedResponse

    回复(可选)

  • event

    ExtendableEvent

  • matchOptions

    CacheQueryOptions 可选

  • request

    请求

  • state

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

返回

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

属性

  • event

    ExtendableEvent

  • 模式

    string

  • params

    任意(可选)

  • request

    请求

  • state

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

返回

  • Promise<void | Response>

CacheWillUpdateCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • 条回复

    响应

  • state

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

返回

  • Promise<void>

FetchDidFailCallbackParam

属性

  • error

    错误

  • event

    ExtendableEvent

  • originalRequest

    请求

  • request

    请求

  • state

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

返回

  • Promise<Response>

FetchDidSucceedCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • 条回复

    响应

  • state

HandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

返回

  • Promise<void>

HandlerDidCompleteCallbackParam

属性

  • error

    错误(可选)

  • event

    ExtendableEvent

  • request

    请求

  • 条回复

    回复(可选)

  • state

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

返回

  • Promise<Response>

HandlerDidErrorCallbackParam

属性

  • error

    错误

  • event

    ExtendableEvent

  • request

    请求

  • state

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

返回

  • Promise<void>

HandlerDidRespondCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • 条回复

    回复(可选)

  • state

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

返回

  • Promise<Response>

HandlerWillRespondCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • 条回复

    响应

  • state

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

返回

  • Promise<void>

HandlerWillStartCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • state

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

每当 Router 通过其 RouteMatchCallback 将网址/请求与 Route 匹配时,系统就会调用“handler”回调。此处理程序回调应返回使用 Response 进行解析的 Promise

如果 RouteMatchCallback 返回非空数组或对象,它将作为此处理程序的 options.params 参数传入。

返回

  • Promise<Response>

ManualHandlerCallbackOptions

传递给 ManualHandlerCallback 函数的选项。

属性

  • event

    ExtendableEvent

  • request

    字符串 | 请求

MapLikeObject

PluginState

目前使用的是普通 MapLikeObject,但将来可以对其进行扩展/限制。

类型

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

返回

  • Promise<Request>

RequestWillFetchCallbackParam

属性

  • event

    ExtendableEvent

  • request

    请求

  • state

RouteHandler

可以是 RouteHandlerCallbackRouteHandlerObjectworkbox-routing 中接受路由处理程序的大多数 API 都采用上述任一方式。

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

每当 Router 通过其 RouteMatchCallback 将网址/请求与 Route 匹配时,系统就会调用“handler”回调。此处理程序回调应返回使用 Response 进行解析的 Promise

如果 RouteMatchCallback 返回非空数组或对象,它将作为此处理程序的 options.params 参数传入。

返回

  • Promise<Response>

RouteHandlerCallbackOptions

传递给 RouteHandlerCallback 函数的选项。

属性

  • event

    ExtendableEvent

  • params

    string[] | MapLikeObject 可选

  • request

    请求

  • 网址

    网址

RouteHandlerObject

一个具有 RouteHandlerCallback 类型的 handle 方法的对象。

您可以使用 RouteHandlerCallback 函数或此 RouteHandler 对象创建 Route 对象。RouteHandler 的优势在于它可以进行扩展(就像 workbox-strategies 软件包一样)。

属性

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

“match”回调用于确定是否应将 Route 应用于特定网址和请求。当发生匹配以响应客户端的提取事件时,系统也会提供 event 对象。但是,由于匹配回调可在提取事件之外调用,因此匹配逻辑不应假定 event 对象始终可用。如果匹配回调返回 TRUE 值,则会立即调用匹配路由的 RouteHandlerCallback。如果返回的值是非空数组或对象,该值将在处理程序的 options.params 参数上设置。

返回

  • 任意

RouteMatchCallbackOptions

传递给 RouteMatchCallback 函数的选项。

属性

  • event

    ExtendableEvent

  • request

    请求

  • sameOrigin

    boolean

  • 网址

    网址

WorkboxPlugin

一个对象,该对象具有用于提取和缓存操作的可选生命周期回调属性。

属性

WorkboxPluginCallbackParam

属性

cacheNames

获取 Workbox 使用的当前缓存名称和前缀/后缀。

cacheNames.precache 用于存储预缓存的资产,cacheNames.googleAnalytics 用于存储workbox-google-analytics存储analytics.jscacheNames.runtime用于存储所有其他数据。

cacheNames.prefix 可用于仅检索当前前缀值。cacheNames.suffix 可用于仅检索当前的后缀值。

类型

对象

属性

  • googleAnalytics

    string

  • 预缓存

    string

  • 前缀

    string

  • 运行时

    string

  • 后缀

    string

方法

clientsClaim()

workbox-core.clientsClaim()

在 Service Worker 变为活动状态后声明所有当前可用的客户端。此字段通常与 skipWaiting() 结合使用。

copyResponse()

workbox-core.copyResponse(
  response: Response,
  modifier?: function,
)

允许开发者复制响应并修改其 headersstatusstatusText 值(可通过构造函数中的 [ResponseInit]https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax 对象设置的值)。如需修改这些值,请将函数作为第二个参数传递。该函数将通过具有响应属性 {headers, status, statusText} 的单个对象调用。此函数的返回值将用作新 ResponseResponseInit。要更改值,请修改传递的参数并返回它,或返回全新的对象。

此方法被特意限制为同源响应,无论是否使用 CORS 都是如此。

参数

  • 条回复

    响应

  • 修饰符

    函数(可选)

    modifier 参数如下所示:

    (responseInit: ResponseInit) => ResponseInit

    • responseInit

      ResponseInit

    • 返回

      ResponseInit

返回

  • Promise<Response>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

向配额错误集添加一个函数,该函数将在出现配额错误时执行。

参数

  • callback

    函数

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

修改了 Workbox 软件包使用的默认缓存名称。 缓存名称会生成为 <prefix>-<Cache Name>-<suffix>

参数

  • 详细信息

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

此方法已废弃,并将从 Workbox v7 中移除。

调用 self.skipWaiting() 是等效的,您应改为使用。