工作箱核心

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() 方法會自動將 activate 事件監聽器新增至 Service Worker，並在其中呼叫 self.clients.claim()。如果在目前的服務工作站啟動之前呼叫 self.clients.claim()，將導致執行階段例外狀況，而 workbox-core 的包裝函式可協助您在適當時機呼叫該例外狀況。

淘汰了 SkipWaiting 包裝函式

在 Workbox v6 之前，我們也建議開發人員使用 workbox-core 的 skipWaiting() 方法。不過，這個方法幾乎沒有開發人員明確呼叫 self.skipWaiting() 時能得到的價值。

由於舊版 workbox-core 包裝函式也會在呼叫 self.skipWaiting() 的 install 事件處理常式中註冊 install 事件處理常式，因此在安裝完成後，如果包裝函式是在其他事件處理常式 (例如 message) 中呼叫，則包裝函式不會出現預期行為。

基於這些原因，workbox-core 的 skipWaiting() 已淘汰，開發人員應改為直接呼叫 self.skipWaiting()。與 self.clients.claim() 不同，如果在「錯誤」時間呼叫 self.skipWaiting() 不會擲回例外狀況，所以不需要將其納入事件處理常式中。

類型

CacheDidUpdateCallback()

workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
)

參數

傳回

  • Promise<void>

CacheDidUpdateCallbackParam

屬性

  • cacheName

    字串

  • event

    ExtendableEvent

  • newResponse

    回應

  • oldResponse

    回覆 (選填)

  • 申請。

    要求

  • state

    MapLikeObject 選用

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

參數

傳回

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

屬性

  • cacheName

    字串

  • cachedResponse

    回覆 (選填)

  • event

    ExtendableEvent

  • matchOptions

    CacheQueryOptions 選用

  • 申請。

    要求

  • state

    MapLikeObject 選用

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

參數

傳回

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

屬性

  • event

    ExtendableEvent

  • 模式

    字串

  • params

    任何選填

  • 申請。

    要求

  • state

    MapLikeObject 選用

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

參數

傳回

  • Promise<void | Response>

CacheWillUpdateCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • 則回應

    回應

  • state

    MapLikeObject 選用

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

參數

傳回

  • Promise<void>

FetchDidFailCallbackParam

屬性

  • 錯誤

    發生錯誤

  • event

    ExtendableEvent

  • originalRequest

    要求

  • 申請。

    要求

  • state

    MapLikeObject 選用

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

參數

傳回

  • Promise<Response>

FetchDidSucceedCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • 則回應

    回應

  • state

    MapLikeObject 選用

HandlerCallbackOptions

列舉

RouteHandlerCallbackOptions

ManualHandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

參數

傳回

  • Promise<void>

HandlerDidCompleteCallbackParam

屬性

  • 錯誤

    錯誤 選填

  • event

    ExtendableEvent

  • 申請。

    要求

  • 則回應

    回覆 (選填)

  • state

    MapLikeObject 選用

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

參數

傳回

  • Promise<Response>

HandlerDidErrorCallbackParam

屬性

  • 錯誤

    發生錯誤

  • event

    ExtendableEvent

  • 申請。

    要求

  • state

    MapLikeObject 選用

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

參數

傳回

  • Promise<void>

HandlerDidRespondCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • 則回應

    回覆 (選填)

  • state

    MapLikeObject 選用

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

參數

傳回

  • Promise<Response>

HandlerWillRespondCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • 則回應

    回應

  • state

    MapLikeObject 選用

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

參數

傳回

  • Promise<void>

HandlerWillStartCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • state

    MapLikeObject 選用

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

每當 Router 透過其 RouteMatchCallback 比對與 Route 的網址/要求時，就會叫用「處理常式」回呼。這個處理常式回呼應傳回由 Response 解析的 Promise。

如果 RouteMatchCallback 傳回非空白陣列或物件，系統會將其做為此處理常式的 options.params 引數傳入。

參數

傳回

  • Promise<Response>

ManualHandlerCallbackOptions

傳遞至 ManualHandlerCallback 函式的選項。

屬性

  • event

    ExtendableEvent

  • 申請。

    string | 要求

MapLikeObject

PluginState

目前使用一般的 MapLikeObject，但日後可擴大/限制此內容。

類型

MapLikeObject

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

參數

傳回

  • Promise<Request>

RequestWillFetchCallbackParam

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • state

    MapLikeObject 選用

RouteHandler

RouteHandlerCallback 或 RouteHandlerObject。workbox-routing 中大部分接受路徑處理常式的 API 也會採用。

列舉

RouteHandlerCallback

RouteHandlerObject

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

每當 Router 透過其 RouteMatchCallback 比對與 Route 的網址/要求時，就會叫用「處理常式」回呼。這個處理常式回呼應傳回由 Response 解析的 Promise。

如果 RouteMatchCallback 傳回非空白陣列或物件，系統會將其做為此處理常式的 options.params 引數傳入。

參數

傳回

  • Promise<Response>

RouteHandlerCallbackOptions

傳遞至 RouteHandlerCallback 函式的選項。

屬性

  • event

    ExtendableEvent

  • params

    string[] | MapLikeObject 選用

  • 申請。

    要求

  • 網址

    網址

RouteHandlerObject

含有 RouteHandlerCallback 類型的 handle 方法的物件。

您可以使用 RouteHandlerCallback 函式或此 RouteHandler 物件建立 Route 物件。RouteHandler 的好處是可以擴充 (正由 workbox-strategies 套件執行)。

屬性

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

「match」回呼可用來判斷 Route 是否應套用至特定網址和要求。當比對以回應用戶端的擷取事件時，也會提供 event 物件。不過，由於比對回呼可在擷取事件之外叫用，因此比對邏輯不應假設 event 物件隨時可用。如果比對回呼傳回三重值，系統會立即叫用相符路徑的 RouteHandlerCallback。如果傳回的值是非空白的陣列或物件，該值會在處理常式的 options.params 引數上設定。

參數

傳回

  • 不限

RouteMatchCallbackOptions

傳遞至 RouteMatchCallback 函式的選項。

屬性

  • event

    ExtendableEvent

  • 申請。

    要求

  • sameOrigin

    boolean

  • 網址

    網址

WorkboxPlugin

包含可選用生命週期回呼屬性的物件，用於擷取和快取作業。

屬性

WorkboxPluginCallbackParam

屬性

屬性

cacheNames

取得 Workbox 目前使用的快取名稱和前置字串/後置字串。

cacheNames.precache 是用於友善快取資產，workbox-google-analytics 則透過 cacheNames.googleAnalytics 儲存 analytics.js，cacheNames.runtime 則用於其他所有內容。

cacheNames.prefix 可用來只擷取目前的前置字元值。cacheNames.suffix 可用來只擷取目前的後置字串值。

類型

物件

屬性

  • googleAnalytics

    字串

  • 預先快取

    字串

  • 前置字串

    字串

  • 執行階段

    字串

  • 稱謂

    字串

方法

clientsClaim()

workbox-core.clientsClaim()

服務工作站啟用後，請領取目前可用的用戶端。這通常會和 skipWaiting() 搭配使用。

copyResponse()

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

允許開發人員複製回應，並修改其 headers、status 或 statusText 值 (可透過建構函式中的 [ResponseInit]https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax 物件設定的值)。如要修改這些值，請將函式做為第二個引數傳遞。系統會使用回應屬性 {headers, status, statusText} 的單一物件叫用該函式。此函式的傳回值將做為新 Response 的 ResponseInit。如要變更值，請修改傳遞的參數並傳回，或傳回完全新物件。

無論 CORS 是否使用，此方法都刻意限制於相同來源的回應。

參數

  • 則回應

    回應

  • 修飾符

    函式選用

    modifier 參數如下所示： 

    (responseInit: ResponseInit) => ResponseInit

    • responseInit

      ResponseInit

    • returns

      ResponseInit

傳回

  • Promise<Response>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

新增函式至一組配額錯誤呼叫，若發生配額錯誤時，就會執行該函式。

參數

  • 回呼

    函式

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

修改 Workbox 套件使用的預設快取名稱。 快取名稱的產生格式為 <prefix>-<Cache Name>-<suffix>。

參數

  • 詳細資料

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

這個方法已淘汰，並將在 Workbox 第 7 版中移除。

呼叫 self.skipWaiting() 等同於，應改用。