JavaScript/Objekte/ServiceWorkerContainer

Das ServiceWorkerContainer-Objekt ist ein Teil des Serviceworker-API. Der Browser erzeugt ein ServiceWorkerContainer Objekt im Verlauf der Initialisierung einer Webseite oder eines Web Workers und stellt es über die Eigenschaft serviceWorker des Navigator-Objekts zur Verfügung.

Der ServiceWorkerContainer ist der Verbindungspunkt, über den eine Webseite oder ein Web-Worker Informationen über den ServiceWorker erhält, mit dem sie verbunden ist, und über den sie Nachrichten vom ServiceWorker erhält.

Das Nachrichtenprotokoll entspricht generell dem Worker-Prinzip. Nachrichten werden über postMessage verwendet und über message-Events empfangen. Der Unterschied ist nur, dass die message-Events nicht auf dem gleichen Objekt empfangen werden, auf dem postMessage aufgerufen wird.

Eigenschaften

• controller
• ready

Methoden

• register()
• getRegistration()
• getRegistrations()
• startMessages()

Ereignisse

• controllerchange
• message
• messageerror

Ein Beispiel

Dieses Beispiel zeigt einen Code-Schnipsel, mit dem eine Webseite einen Serviceworker anbinden oder registrieren könnte. Um nicht zu umfangreich zu sein, werden bestimmte Timing-Probleme außer Acht gelassen. Auf diese Aspekte geht das App-Tutorial ausführlicher ein.

Registrieren eines Serviceworkers

  const swContainer = navigator.serviceWorker;
  if (swContainer) {
    if (swContainer.controller) {
       runWithServiceworker(swContainer.controller);
    }
    else {
       swContainer.register("./serviceWorker.js")
    }
  }

Sie sehen die Initialisierung einer Webseite, die einen Serviceworker nutzt. Zunächst muss geprüft werden, ob der Browser überhaupt das Serviceworker-API unterstützt, was daran erkennbar ist, dass window.navigator einen Wert liefert, der als true interpretiert wird. Es handelt sich dabei um das hier beschriebene ServiceWorkerContainer-Objekt.

Wenn es bereits einen Serviceworker für die aktuelle Seite gibt, findet sich das zugehörige ServiceWorker-Objekt in der controller-Eigenschaft des Serviceworkercontainers. Sofern die Client-Seite mit dem Serviceworker interagieren möchte (z.B. Messages empfangen), kann sie das nun initialisieren, was durch den Aufruf von runWithServiceworker angedeutet sein soll. Andernfalls sollte sie den Serviceworker registrieren.

Eigenschaften

controller

Liefert das ServiceWorker Objekt für die Seite, dessen Zustand active oder activating ist. Das gleiche Objekt findet sich in der active Eigenschaft des für die Seite gültigen ServiceWorkerRegistration Objekts.

Die controller-Eigenschaft liefert null, wenn die Seite keinen zugeordneten akiven Serviceworker hat, oder wenn der Anwender einen erzwungenen Refresh der Seite (Shift + Refresh) durchführt.

ready

Liefert ein Promise, das mit der ServiceWorkerRegistration der Seite resolved, sobald die Seite über einen aktiven Serviceworker verfügt. Das API sichert zu, dass dieses Promise niemals rejected wird.

Methoden

getRegistration(scopeURL)

Die Methode ermittelt die ServiceWorkerRegistration, die für die angegebene Scope-URL gilt. Das muss nicht die gleiche Registrierung sein, die von ready zurückgemeldet wird, weil ready die Registrierung sucht, deren Scope-URL für die geladene Seite gilt, während diese Methode eine beliebige Scope-URL akzeptiert, solange sie den gleichen Origin hat wie die geladene Seite.

Parameter

scopeURL

URL, die den Scope für die Registrierungssuche festlegt.

Rückgabe

Ein Promise, das zu einem ServiceWorkerRegistration Objekt resolved. Wird keine Registrierung zu diesem Scope gefunden, resolved das Promise zu undefined.

Eine Abfrage auf einen fremden Origin führt zu einem Reject des Promise mit einer SecurityError DOMException.

getRegistrations()

Die Methode ermittelt alle ServiceWorkerRegistration Objekte, die zum Origin der Webseite gehören.

Parameter

keine

Rückgabe

Ein Promise, das zu einem Array mit allen gefundenen Registrierungen resolved.

register()

Dies ist die zentrale Methode zum Registrieren neuer Serviceworker. Sie erzeugt oder aktualisiert einen Serviceworker für den Origin der angezeigten Webseite. Wenn es für den Registrierungsscope bereits einen Serviceworker gibt, dessen URL mit der angegebenen Script-URL übereinstimmt, bleibt der alte Serviceworker erhalten und die Methode liefert lediglich die dafür vorhandene Registrierung.

Parameter

scriptURL

Die URL, von der das Serviceworker-Script geladen wird.

options

(optional) Ein Objekt mit Registrierungsoptionen. Mögliche Optionen sind:

scope

Eine URL für den spezifischer Scope, für den der Serviceworker registriert werden soll. Default ist der URL-Pfad, an dem das Serviceworker-Script gespeichert ist.

type

'classic' - Der Serviceworker wird als normales Script geladen. Da jeder Serviceworker seinen eigenen globalen Scope hat, ist dieser Modus nicht so problematisch wie bei JavaScript-Modulen der eigentlichen Webseite. Wenn der Serviceworker zusätzliche JavaScript-Dateien einbinden will, muss er dafür die importScripts()-Funktion verwenden, die der ServiceWorkerGlobalScope von WorkerGlobalScope erbt.

'module' - Der Serviceworker wird als ECMAScript-Modul geladen und kann zusätzlichen Code mit Hilfe des import-Befehls nachladen.

updateViaCache

Diese Option steuert das Updateverhalten des Serviceworkers. Mögliche Werte sind 'all', 'imports' und 'none'. Wie Updates von Serviceworkern ablaufen, steht auf der ServiceWorker Referenzseite.

Rückgabewert

Ein Promise, das zum ServiceWorkerRegistration-Objekt der Scope-URL resolved.

Die Scope-URL ist eine URL, deren Pfad-Anteil den Geltungsbereich (Scope) der Serviceworker-Registrierung festlegt. Wird eine Webseite oder ein Worker aus einer URL geladen, deren Pfad mit dem Scope übereinstimmt oder diesem Pfad untergeordnet ist, wird sie bzw. er zum Client des aktiven Serviceworkers.

Wenn Sie bei der Registrierung nichts anderes angeben, ist die Scope-URL eines ServiceWorkers identisch mit der URL, über die seine Scriptdatei geladen wurde. Wenn für einen ServiceWorker ein andere Scope-URL gelten soll, können Sie das bei der Registrierung angeben, allerdings muss der so spezifierte Geltungsordner dem Order aus der Default-Scope-URL untergeordnet sein. Der Server kann diese Restriktion lösen, indem er die Scriptdatei des Serviceworkers mit dem 'Service-Worker-Allowed' Header ausliefert. Über diesen Header kann ein anderer Stammordner angegeben werden, der die Pfadwurzel für die Scope-URL bildet.

startMessages()

Die Nachrichtenwarteschlange eines ServiceWorkerContainer ist zunächst deaktiviert, d.h. die Nachrichten vom ServiceWorker werden nur gespeichert, aber nicht signalisiert. Es gibt drei mögliche Auslöser, wodurch die message-Eventverarbeitung aktiviert wird:

• das HTML Dokument der Seite ist fertig geladen (d.h. nachdem DOMContentLoaded signalisiert wurde)
• Sie registrieren den Eventhandler für das Message-Event durch eine Zuweisung an die onmessage Eigenschaft, statt über addEventListener()
• Sie rufen explizit die startMessages() Methode auf.

Ereignisse

controllerchange

Typ des Ereignisobjekts: Event

Das Event wird ausgelöst, wenn der aktive Serviceworker der Seite, zu der der Container gehört, sich ändert. Eine solche Änderung passiert nicht von allein. Entweder wurde vom aktiven ServiceWorker die Methode claim() auf dem Clients Objekt aufgerufen, um Clients ohne Serviceworkerzuordnung an sich zu binden, oder ein wartendender ServiceWorker hat die Methode skipWaiting() im ServiceWorkerGlobalScope aufgerufen, um den bisher aktiven ServiceWorker zu verdrängen. Wenn das Ereignis behandelt wird, enthält die controller-Eigenschaft des ServiceWorkerRegistration-Objekts bereits den neuen ServiceWorker.

message

Typ des Ereignisobjekts: MessageEvent

Der Serviceworker-Client, zu dem der Container gehört, erhält eine mit postMessage gesendete Nachricht vom ServiceWorker. Sie finden die gesendeten Daten in der data-Eigenschaft des MessageEvent-Objekts.

messageerror

Typ des Ereignisobjekts: MessageEvent

Dieses Event wird an Stelle eines message Events gesendet, wenn es beim Deserialisieren der Nachricht zu einem Fehler kam.