Workbox Core

Die Workbox ist modular aufgebaut, sodass Entwickler die zu verwendenden Teile auswählen können, ohne alles in einer einzigen Datei herunterladen zu müssen.

Es gibt jedoch Überschneidungen zwischen den Modulen. Zum Beispiel muss jedes Modul mit der Konsole interagieren, gibt aussagekräftige Fehler aus und nutzt das Netzwerk oder den Cache. Damit nicht jedes Modul dieselbe Logik implementiert, enthält workbox-core diesen allgemeinen Code, auf dem sich jedes Modul stützt.

Dieses Modul bietet Entwicklern einige Funktionen, aber workbox-core bietet neben Logebenen und Caching auch für jedes Modul interne Logik, nicht für den Endentwickler.

Standard-Cache-Namen ansehen und ändern

Die Workbox definiert die Caches über cacheNames:

import {cacheNames} from 'workbox-core';

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

Diese Cache-Namen werden im Format eines Präfixes, Namens und Suffixes erstellt, wobei sich der Name je nach Verwendung des Cache ändert.

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

Sie können diese Standardnamen ändern. Ändern Sie dazu alle oder einige der an setCacheNameDetails() übergebenen Werte.

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);

Wenn Sie Workbox für mehrere Projekte und denselben Localhost-Port für jedes Projekt verwenden, wird durch das Festlegen eines benutzerdefinierten Präfixes für jedes Modul verhindert, dass die Caches miteinander in Konflikt stehen.

Kundenanspruch

Einige Entwickler möchten einen neuen Service Worker veröffentlichen und ihn bereits geöffnete Webseiten sofort nach der Aktivierung steuern lassen, was standardmäßig nicht der Fall ist.

Für dieses Verhalten bietet workbox-core eine Hilfsmethode:

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();

Die Methode clientsClaim() in workbox-core fügt Ihrem Service Worker automatisch einen Ereignis-Listener vom Typ activate hinzu und ruft darin self.clients.claim() auf. Wenn Sie self.clients.claim() aufrufen, bevor der aktuelle Dienst-Worker aktiviert wird, führt dies zu einer Laufzeitausnahme. Der Wrapper von workbox-core sorgt dafür, dass Sie ihn zur richtigen Zeit aufrufen.

Der Wrapper „skipWarteing“ wurde eingestellt

Vor Workbox v6 wurde Entwicklern außerdem empfohlen, die Methode skipWaiting() aus workbox-core zu verwenden. Diese Methode bietet jedoch über den Wert hinaus, den Entwickler erhalten, wenn sie self.skipWaiting() explizit aufrufen.

Da der Legacy-Wrapper workbox-core auch einen install-Event-Handler registriert hat, in dem self.skipWaiting() aufgerufen wurde, verhält sich der Wrapper nicht wie erwartet, wenn er innerhalb eines anderen Event-Handlers wie message aufgerufen würde, nachdem die Installation bereits abgeschlossen war.

Aus diesen Gründen wurde skipWaiting() von workbox-core eingestellt. Entwickler sollten self.skipWaiting() direkt aufrufen. Im Gegensatz zu self.clients.claim() löst self.skipWaiting() keine Ausnahme aus, wenn der Aufruf zum „falschen“ Zeitpunkt erfolgt. Daher ist es nicht erforderlich, den Ereignis-Handler in einen Event-Handler einzubinden.

Typen

CacheDidUpdateCallback()

workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
)

Parameter

Rückgabe

  • Promise<void>

CacheDidUpdateCallbackParam

Attribute

  • cacheName

    String

  • event

    ExtendableEvent

  • newResponse

    Antwort

  • oldResponse

    Antwort optional

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

Parameter

Rückgabe

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

Attribute

  • cacheName

    String

  • cachedResponse

    Antwort optional

  • event

    ExtendableEvent

  • matchOptions

    CacheQueryOptions optional

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

Parameter

Rückgabe

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

Attribute

  • event

    ExtendableEvent

  • Modus

    String

  • params

    Beliebig optional

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

Parameter

Rückgabe

  • Promise<void | Response>

CacheWillUpdateCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • Antwort

    Antwort

  • state

    MapLikeObject optional

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

Parameter

Rückgabe

  • Promise<void>

FetchDidFailCallbackParam

Attribute

  • error

    Fehler

  • event

    ExtendableEvent

  • originalRequest

    Anfragen

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

Parameter

Rückgabe

  • Promise<Antwort>

FetchDidSucceedCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • Antwort

    Antwort

  • state

    MapLikeObject optional

HandlerCallbackOptions

Enum

RouteHandlerCallbackOptions

ManualHandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

Parameter

Rückgabe

  • Promise<void>

HandlerDidCompleteCallbackParam

Attribute

  • error

    Fehler optional

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • Antwort

    Antwort optional

  • state

    MapLikeObject optional

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

Parameter

Rückgabe

  • Promise<Antwort>

HandlerDidErrorCallbackParam

Attribute

  • error

    Fehler

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

Parameter

Rückgabe

  • Promise<void>

HandlerDidRespondCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • Antwort

    Antwort optional

  • state

    MapLikeObject optional

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

Parameter

Rückgabe

  • Promise<Antwort>

HandlerWillRespondCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • Antwort

    Antwort

  • state

    MapLikeObject optional

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

Parameter

Rückgabe

  • Promise<void>

HandlerWillStartCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

Der Callback „handler“ wird immer dann aufgerufen, wenn ein Router eine URL/eine Anfrage über seine RouteMatchCallback mit einem Route übereinstimmt. Dieser Handler-Callback sollte ein Promise zurückgeben, das mit einem Response aufgelöst wird.

Wenn vom RouteMatchCallback ein nicht leeres Array oder Objekt zurückgegeben wird, wird es als options.params-Argument dieses Handlers übergeben.

Parameter

Rückgabe

  • Promise<Antwort>

ManualHandlerCallbackOptions

Optionen, die an eine ManualHandlerCallback-Funktion übergeben werden.

Attribute

  • event

    ExtendableEvent

  • Anfrage

    String | Anfrage

MapLikeObject

PluginState

Wenn Sie vorerst ein einfaches MapLikeObject verwenden, könnte dies in Zukunft erweitert/eingegrenzt werden.

Typ

MapLikeObject

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

Parameter

Rückgabe

  • Promise<Anfrage>

RequestWillFetchCallbackParam

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • state

    MapLikeObject optional

RouteHandler

Entweder RouteHandlerCallback oder RouteHandlerObject. Die meisten APIs in workbox-routing, die Routen-Handler akzeptieren, verwenden beides.

Enum

RouteHandlerCallback

RouteHandlerObject

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

Der Callback „handler“ wird immer dann aufgerufen, wenn ein Router eine URL/eine Anfrage über seine RouteMatchCallback mit einem Route übereinstimmt. Dieser Handler-Callback sollte ein Promise zurückgeben, das mit einem Response aufgelöst wird.

Wenn vom RouteMatchCallback ein nicht leeres Array oder Objekt zurückgegeben wird, wird es als options.params-Argument dieses Handlers übergeben.

Parameter

Rückgabe

  • Promise<Antwort>

RouteHandlerCallbackOptions

Optionen, die an eine RouteHandlerCallback-Funktion übergeben werden.

Attribute

  • event

    ExtendableEvent

  • params

    string[] | MapLikeObject optional

  • Anfrage

    Anfragen

  • url

    URL

RouteHandlerObject

Ein Objekt mit einer handle-Methode des Typs RouteHandlerCallback.

Ein Route-Objekt kann entweder mit einer RouteHandlerCallback-Funktion oder diesem RouteHandler-Objekt erstellt werden. Der Vorteil von RouteHandler besteht darin, dass es erweitert werden kann (wie das Paket workbox-strategies).

Attribute

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

Der „Übereinstimmung“-Callback wird verwendet, um zu bestimmen, ob ein Route auf eine bestimmte URL und Anfrage angewendet werden soll. Wenn ein Abgleich als Reaktion auf ein Abrufereignis vom Client erfolgt, wird auch das Objekt event angegeben. Da der Übereinstimmungs-Callback jedoch außerhalb eines Abrufereignisses aufgerufen werden kann, sollte die Abgleichslogik nicht davon ausgehen, dass das event-Objekt immer verfügbar ist. Wenn der Übereinstimmungs-Callback einen Truthy-Wert zurückgibt, wird sofort der RouteHandlerCallback der übereinstimmenden Route aufgerufen. Wenn der zurückgegebene Wert ein nicht leeres Array oder Objekt ist, wird er auf das options.params-Argument des Handlers festgelegt.

Parameter

Rückgabe

  • Beliebig

RouteMatchCallbackOptions

Optionen, die an eine RouteMatchCallback-Funktion übergeben werden.

Attribute

  • event

    ExtendableEvent

  • Anfrage

    Anfragen

  • sameOrigin

    boolean

  • url

    URL

WorkboxPlugin

Ein Objekt mit optionalen Lebenszyklus-Callback-Eigenschaften für die Abruf- und Cache-Vorgänge.

Attribute

WorkboxPluginCallbackParam

Attribute

Attribute

cacheNames

Ruft die aktuellen Cache-Namen und ‐Präfixe/‐Suffixe ab, die von Workbox verwendet werden.

cacheNames.precache wird für vorab im Cache gespeicherte Assets verwendet, cacheNames.googleAnalytics von workbox-google-analytics zum Speichern von analytics.js und cacheNames.runtime für alle anderen Elemente.

Mit cacheNames.prefix kann nur der aktuelle Präfixwert abgerufen werden. Mit cacheNames.suffix kann nur der aktuelle Suffixwert abgerufen werden.

Typ

Objekt

Attribute

  • googleAnalytics

    String

  • vorab im Cache speichern

    String

  • Präfix

    String

  • runtime

    String

  • Suffix

    String

Methoden

clientsClaim()

workbox-core.clientsClaim()

Beanspruchen Sie alle derzeit verfügbaren Clients, sobald der Service Worker aktiviert wird. Wird normalerweise in Verbindung mit skipWaiting() verwendet.

copyResponse()

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

Entwickler können eine Antwort kopieren und ihre headers-, status- oder statusText-Werte ändern. Diese Werte können über ein [ResponseInit]https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax-Objekt im Konstruktor festgelegt werden. Um diese Werte zu ändern, übergeben Sie eine Funktion als zweites Argument. Diese Funktion wird mit einem einzelnen Objekt mit den Antwortattributen {headers, status, statusText} aufgerufen. Der Rückgabewert dieser Funktion wird als ResponseInit für den neuen Response verwendet. Wenn Sie die Werte ändern möchten, ändern Sie entweder die übergebenen Parameter und geben sie zurück oder geben ein völlig neues Objekt zurück.

Diese Methode ist absichtlich auf Antworten vom selben Ursprung beschränkt, unabhängig davon, ob CORS verwendet wurde oder nicht.

Parameter

  • Antwort

    Antwort

  • Modifikator

    Funktion optional

    Der Parameter modifier sieht so aus: 

    (responseInit: ResponseInit) => ResponseInit

    • responseInit

      ResponseInit

    • Gibt zurück

      ResponseInit

Rückgabe

  • Promise<Antwort>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

Fügt eine Funktion zu „quotaErrorCallbacks“ hinzu, die bei einem Kontingentfehler ausgeführt wird.

Parameter

  • callback

    Funktion

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

Ändert die Standard-Cache-Namen, die von den Workbox-Paketen verwendet werden. Cache-Namen werden als <prefix>-<Cache Name>-<suffix> generiert.

Parameter

  • Details

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

Diese Methode wird nicht mehr unterstützt und in Workbox v7 entfernt.

Der Aufruf von „self.skipWarteing()“ ist gleichwertig und sollte stattdessen verwendet werden.