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 連接埠,為每個模組設定自訂前置字串,就能避免快取彼此衝突。
客戶宣稱
有些開發人員希望能夠發布新的服務工作者,並在服務工作者啟用後立即控制已開啟的網頁,但這並非預設行為。
如果您想要這類行為,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
事件監聽器新增至服務工作者,並在其中呼叫 self.clients.claim()
。在目前服務 worker 啟動前呼叫 self.clients.claim()
會導致執行階段例外狀況,而 workbox-core
的包裝函式可確保您在適當時間呼叫該函式。
已淘汰 skipWaiting 包裝函式
在 Workbox 6 之前,我們也鼓勵開發人員使用 workbox-core
中的 skipWaiting()
方法。不過,除了開發人員明確呼叫 self.skipWaiting()
所獲得的價值之外,這個方法幾乎沒有提供任何價值。
由於舊版 workbox-core
包裝函式也會在其中呼叫 self.skipWaiting()
時註冊 install
事件處理常式,因此如果在安裝完成後,在 message
等其他事件處理常式中呼叫包裝函式,包裝函式就不會正常運作。
基於這些原因,workbox-core
的 skipWaiting()
已淘汰,開發人員應改為直接呼叫 self.skipWaiting()
。與 self.clients.claim()
不同,如果在「錯誤」時間點呼叫 self.skipWaiting()
,系統不會擲回例外狀況,因此不需要在事件處理常式中包裝 self.skipWaiting()
。
類型
CacheDidUpdateCallback()
workbox-core.CacheDidUpdateCallback(
param: CacheDidUpdateCallbackParam,
)
傳回
-
Promise<void>
CacheDidUpdateCallbackParam
屬性
-
cacheName
字串
-
活動
ExtendableEvent
-
newResponse
回應
-
oldResponse
回應 選填
-
申請。
要求
-
州
CachedResponseWillBeUsedCallback()
workbox-core.CachedResponseWillBeUsedCallback(
param: CachedResponseWillBeUsedCallbackParam,
)
傳回
-
Promise<void | Response>
CachedResponseWillBeUsedCallbackParam
屬性
-
cacheName
字串
-
cachedResponse
回應 選填
-
活動
ExtendableEvent
-
matchOptions
CacheQueryOptions 選填
-
申請。
要求
-
州
CacheKeyWillBeUsedCallback()
workbox-core.CacheKeyWillBeUsedCallback(
param: CacheKeyWillBeUsedCallbackParam,
)
傳回
-
Promise<字串 | 要求>
CacheKeyWillBeUsedCallbackParam
屬性
-
活動
ExtendableEvent
-
模式
字串
-
參數
任何選填
-
申請。
要求
-
州
CacheWillUpdateCallback()
workbox-core.CacheWillUpdateCallback(
param: CacheWillUpdateCallbackParam,
)
傳回
-
Promise<void | Response>
CacheWillUpdateCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
回應
回應
-
州
FetchDidFailCallback()
workbox-core.FetchDidFailCallback(
param: FetchDidFailCallbackParam,
)
傳回
-
Promise<void>
FetchDidFailCallbackParam
屬性
-
錯誤
錯誤
-
活動
ExtendableEvent
-
originalRequest
要求
-
申請。
要求
-
州
FetchDidSucceedCallback()
workbox-core.FetchDidSucceedCallback(
param: FetchDidSucceedCallbackParam,
)
傳回
-
Promise<Response>
FetchDidSucceedCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
回應
回應
-
州
HandlerCallbackOptions
HandlerDidCompleteCallback()
workbox-core.HandlerDidCompleteCallback(
param: HandlerDidCompleteCallbackParam,
)
傳回
-
Promise<void>
HandlerDidCompleteCallbackParam
屬性
-
錯誤
錯誤 (選填)
-
活動
ExtendableEvent
-
申請。
要求
-
回應
回應 選填
-
州
HandlerDidErrorCallback()
workbox-core.HandlerDidErrorCallback(
param: HandlerDidErrorCallbackParam,
)
傳回
-
Promise<Response>
HandlerDidErrorCallbackParam
屬性
-
錯誤
錯誤
-
活動
ExtendableEvent
-
申請。
要求
-
州
HandlerDidRespondCallback()
workbox-core.HandlerDidRespondCallback(
param: HandlerDidRespondCallbackParam,
)
傳回
-
Promise<void>
HandlerDidRespondCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
回應
回應 選填
-
州
HandlerWillRespondCallback()
workbox-core.HandlerWillRespondCallback(
param: HandlerWillRespondCallbackParam,
)
傳回
-
Promise<Response>
HandlerWillRespondCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
回應
回應
-
州
HandlerWillStartCallback()
workbox-core.HandlerWillStartCallback(
param: HandlerWillStartCallbackParam,
)
傳回
-
Promise<void>
HandlerWillStartCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
州
ManualHandlerCallback()
workbox-core.ManualHandlerCallback(
options: ManualHandlerCallbackOptions,
)
每當 Router
透過其 RouteMatchCallback
比對 Route
的網址/要求時,系統就會叫用「handler」回呼。這個處理常式回呼應傳回可透過 Response
解析的 Promise
。
如果 RouteMatchCallback
傳回非空白陣列或物件,則會將其傳入做為這個處理常式 options.params
的引數。
傳回
-
Promise<Response>
ManualHandlerCallbackOptions
傳遞至 ManualHandlerCallback
函式的選項。
屬性
-
活動
ExtendableEvent
-
申請。
字串 | 要求
MapLikeObject
PluginState
目前使用一般 MapLikeObject
,但日後可能會擴大/限制這個功能。
RequestWillFetchCallback()
workbox-core.RequestWillFetchCallback(
param: RequestWillFetchCallbackParam,
)
傳回
-
Promise<Request>
RequestWillFetchCallbackParam
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
州
RouteHandler
RouteHandlerCallback
或 RouteHandlerObject
。workbox-routing
中接受路徑處理常式的大多數 API 都會採用這兩種方式。
RouteHandlerCallback()
workbox-core.RouteHandlerCallback(
options: RouteHandlerCallbackOptions,
)
每當 Router
透過其 RouteMatchCallback
比對 Route
的網址/要求時,系統就會叫用「handler」回呼。這個處理常式回呼應傳回可透過 Response
解析的 Promise
。
如果 RouteMatchCallback
傳回非空白陣列或物件,則會將其傳入做為這個處理常式 options.params
的引數。
傳回
-
Promise<Response>
RouteHandlerCallbackOptions
傳遞至 RouteHandlerCallback
函式的選項。
屬性
-
活動
ExtendableEvent
-
參數
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
函式的選項。
屬性
-
活動
ExtendableEvent
-
申請。
要求
-
sameOrigin
布林值
-
網址
網址
WorkboxPlugin
物件,其中包含擷取和快取作業的選用生命週期回呼屬性。
屬性
-
cacheDidUpdate
-
cacheKeyWillBeUsed
-
cacheWillUpdate
-
cachedResponseWillBeUsed
-
fetchDidFail
-
fetchDidSucceed
-
handlerDidComplete
-
handlerDidError
-
handlerDidRespond
-
handlerWillRespond
-
handlerWillStart
-
requestWillFetch
WorkboxPluginCallbackParam
屬性
-
cacheDidUpdate
-
cacheKeyWillBeUsed
-
cacheWillUpdate
-
cachedResponseWillBeUsed
-
fetchDidFail
-
fetchDidSucceed
-
handlerDidComplete
-
handlerDidError
-
handlerDidRespond
-
handlerWillRespond
-
handlerWillStart
-
requestWillFetch
屬性
cacheNames
取得 Workbox 使用的目前快取名稱和前置字串/後置字串。
cacheNames.precache
用於預快取的素材資源,cacheNames.googleAnalytics
則由 workbox-google-analytics
用於儲存 analytics.js
,而 cacheNames.runtime
則用於其他所有情況。
cacheNames.prefix
可用來擷取目前的前置字元值。cacheNames.suffix
可用來擷取目前的後置字串值。
類型
物件
屬性
-
googleAnalytics
字串
-
precache
字串
-
前置字串
字串
-
執行階段
字串
-
字尾
字串
方法
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,
)
將函式新增至 quotaErrorCallbacks 集合,在發生配額錯誤時執行。
參數
-
回呼
函式
setCacheNameDetails()
workbox-core.setCacheNameDetails(
details: PartialCacheNameDetails,
)
修改 Workbox 套件使用的預設快取名稱。快取名稱會以 <prefix>-<Cache Name>-<suffix>
的形式產生。
參數
-
詳細資料
PartialCacheNameDetails
skipWaiting()
workbox-core.skipWaiting()
這個方法已淘汰,並將在 Workbox 7 版中移除。
呼叫 self.skipWaiting() 的效果相同,因此應改為使用此方法。