JavaScript/Objekte/ServiceWorkerRegistration

Aus SELFHTML-Wiki
Wechseln zu: Navigation, Suche

ServiceWorkerRegistration-Objekte sind ein Teil des Serviceworker-API. Sie stellen die Verbindung zwischen einer Scope-URL und den zugehörigen ServiceWorker Objekten her.

Sie können ServiceWorkerRegistration-Objekte entweder als Ergebnis der Registrierung eines Serviceworkers mit register() erhalten, oder Sie fragen vorhandene ServiceWorker durch getRegistration() bzw. getRegistrations().

Eigenschaften

index
Liefert den ContentIndex für diese Registrierung. Aktuell (August 2021) nur auf Chromium-Browsern unter Android verfügbar.
installing, waiting und active
Diese Eigenschaften liefern Serviceworker-Objekte der entsprechenden Kategorie, oder null. Die Kategorien und Zustände werden im Serviceworker-Artikel beschrieben.
navigationPreload
Liefert den NavigationPreloadManager dieser Registrierung
pushManager
(Erweiterung aus dem Push-API): Liefert den PushManager dieser Registrierung
scope
Die scope-Eigenschaft liefert den Scope-URL, für den dieses ServiceWorkerRegistration-Objekt die ServiceWorker bereithält, als absolute URL, inklusive des Origins.
sync
(Erweiterung aus dem inoffiziellen Background Sync API): Liefert den SyncManager dieser Registrierung.
updateViaCache
Eine der Zeichenketten 'all', 'imports' oder 'none'. Die Werte entsprechen der updateViaCache-Option aus der ServiceWorkerContainer.register() Methode; das Updateverhalten von Serviceworkern wird auf der Seite ServiceWorker beschrieben.

Methoden

getNotifications()

Erweiterung aus dem Notifications API.

Die Methode ermittelt die vorhandenen Benachrichtigungen, die über den zugeordneten Serviceworker erstellt wurden. Beachten Sie bitte, dass Benachrichtigungensowohl vom Serviceworker als auch von einer Webseite, die Client eines Serviceworkers ist, erstellt werden können, aber alle dem Serviceworker zugeordnet sind.

Parameter
options
(optional) Ein Objekt mit Filterbedingungen für die Benachrichtigungen, die ermittelt werden sollen. Zur Zeit ist nur die tag-Eigenschaft definiert, um Benachrichtigungen zu finden, die mit diesem tag-Wert an showNotification übergeben wurden.
Rückgabewert
Ein Promise, das zu einem Array resolved. Es enthält alle Benachrichtigungen, auf die der options-Parameter zutrifft und die noch nicht vom Benutzer oder mit der close()-Methode geschlossen wurden.

showNotification()

Erweiterung aus dem Notifications API.

Ausgeben einer Benachrichtigung im Benachrichtigungssystem des Gerätes. Es muss eine Benutzereinwilligung für Benachrichtigungen vorliegen, siehe Notification-Objekt.

Parameter
title
die Überschrift für die Benachrichtigung
options
(optional) Ein Objekt mit weiteren Optionen zur Benachrichtigung
Rückgabewert
Ein Promise, das im Erfolgsfall zu einem ServiceWorkerRegistration-Objekt resolved wird. Es gibt diverse Gründe, weshalb das Promise rejected werden kann.


Optionen

Hierfür verwenden Sie ein Objektliteral mit den folgenden, optionalen Eigenschaften:

actions Ein Array aus Aktionen. Jede Aktion ist wiederum ein Objektliteral, eine Beschreibung folgt im Anschluss.
badge Der URL eines Icons, das gezeigt wird, wenn für die Benachrichtigung nicht genug Platz ist. Ein Beispiel dafür wäre die Benachrichtigungsleiste von Android.
body ein String mit weiterem Text für die Benachrichtigung
data beliebige Daten, die Sie der Benachrichtigung zuordnen wollen. Solche Daten können nützlich sein, wenn Sie später auf Events reagieren möchten, die durch Benutzerinteraktion mit der Benachrichtigung entstehen.
dir Die Richtung der Benachrichtigung. Entspricht in Funktion und erlaubten Werten dem HTML Universalattribut dir.
icon Der URL eines Icons, das zusammen mit der Benachrichtigung angezeigt wird.
image Der URL für ein Bild, das in der Benachrichtigung angezeigt wird.
lang Die Sprache, in der die Benachrichtigung verfasst ist. Entspricht in Funktion und erlaubten Werten dem HTML Universalattribug lang.
renotify Boolescher Wert, Standardwert ist false. Steuert die Signalisierung (Vibration, Signalton) von Benachrichtigungen mit einem wiederverwendeten Wert in der tag-Eigenschaft. Wenn Sie renotify:true, aber keinen Wert für tag angeben, wird ein TypeError geworfen.
requireInteraction Je nach Betriebssystem werden Benachrichtigungen nach einer gewissen Zeit ausgeblendet. Sie können diese Eigenschaft auf true setzen, um das zu verhindern.
silent Boolescher Wert, Standardwert ist false. Setzen Sie diese Option auf true, um eine stumme Benachrichtigung zu erzeugen. Setzen Sie nicht gleichzeitig vibrate auf true, oder Ihr Browser ist verwirrt und wirft einen TypeError.
tag Ein String, der die Benachrichtigung identifiziert. Sie können Benachrichtigungen auf diesem Weg suchen. Wenn Sie eine Benachrichtigung zeigen, die das gleiche Tag hat wie eine existierende Benachrichtigung, wird diese Benachrichtigung ersetzt. Beachten Sie dazu auch die renotify Option.
timestamp Der DOMTimestamp (Millisekunden seit 01.01.1970), auf den sich diese Notification bezieht. Das ist kein Zeitpunkt, zu dem die Benachrichtigung erscheinen soll.
vibrate Boolescher Wert, Standardwert ist false. Gibt an, ob das Gerät die Benachrichtigung durch Vibration signalisieren soll. Das Gerät muss dafür natürlich über einen Vibrationsalarm verfügen, deswegen unterstützen Desktop-Browser diese Eigenschaft nicht. Die Zeiten, wo man dafür das Diskettenlaufwerk hätte nutzen können, sind vorbei.

Aktionen

In der Option actions hinterlegen Sie ein Array aus Objekten mit den folgenden Einträgen:

action ein String, der die Aktion intern definiert
title der Text, der in der Notification als Beschreibung der Aktion dargestellt wird
icon (optional) der URL für ein Icon, das für die Aktion gezeigt werden soll
Beachten Sie: Das actions-Array kann nicht beliebig groß werden. Überprüfen Sie die Eigenschaft maxActions des Notification-Objekts, um die unterstützte Anzahl zu erfahren. Eventuell werden Aktionen vom Browser oder Betriebssytem auch gar nicht unterstützt. Bevor Sie Aktionen verwenden und sich darauf verlassen, dass Ihre Anwender damit nützliche Dinge tun, müsen Sie prüfen, ob maxActions größer als 0 ist. Im Firefox-Browser, der Aktionen gar nicht unterstützt, fehlt die maxActions Eigenschaft. Die Abfrage Notification.maxActions > 0 liefert dann false.

update()

Die Methode erzwingt das Neuladen des registrierten Serviceworkers. Sie lädt die Scriptdatei erneut vom Server, und führt einen Byte-für-Byte Vergleich mit dem Script des aktiven Serviceworkers aus. Ergibt sich ein Unterschied, wird der neue Serviceworker installiert. Der Serverzugriff wird unter Umgehung von Caches durchgeführt, wenn das Script zuletzt vor mehr als 24 Stunden geladen wurde.

Parameter
Keine
Rückgabewert
Ein Promise, das im Erfolgsfall zu einem ServiceWorkerRegistration-Objekt resolved wird. Es gibt diverse Gründe, weshalb das Promise rejected werden kann.

unregister()

Die Serviceworkerregistrierung, auf der Sie diese Methode aufrufen, wird deaktiviert, d.h. Abrufe weiterer Seiten in seinem Scope verwenden sie nicht mehr. Erst, wenn alle Client-Seiten dieser REgistrierung entladen wurden, wird auch die Serviceworkerregistrierung aus dem Speicher gelöscht.

Parameter
Keine
Rückgabewert
Ein Promise, das im Erfolgsfall zu true resolved. Es resolved zu false, wenn keine Registrierung gefunden wird (was passieren kann, wenn eine andere Clientseite dem unregister-Aufruf zuvor kam). Es kann auch zu unterschiedlichen Fehlern rejected werden.

Ereignisse

updatefound

Dieses Event wird geworfen, wenn der Browser eine neue Version des Serviceworkers findet und mit der Installation beginnt (d.h. der neue Serviceworker in der installing-Eigenschaft des ServiceWorkerRegistration-Objekts verfügbar wird).

Der Eventhandler bekommt ein generisches Event-Objekt übergeben.