Signatur
Beschreibung
Der Konstruktor SyncEvent() erzeugt ein Ereignisobjekt der Background Synchronization API. SyncEvent erbt von ExtendableEvent. Deshalb stehen Methoden wie waitUntil() zur Verfügung, mit denen der Service Worker so lange aktiv bleibt, bis die Synchronisierung abgeschlossen ist.
Normalerweise erzeugt der Browser SyncEvent-Objekte selbst und löst sie im Service Worker als sync-Ereignis aus, sobald wieder eine Netzwerkverbindung besteht und eine Registrierung über SyncManager.register() vorliegt. Selbst ruft man den Konstruktor vor allem in Tests auf, zum Beispiel wenn man eine Synchronisierungslogik gezielt auslösen oder nachbilden möchte, ohne auf die Netzwerkverbindung zu warten.
Der Konstruktor gibt es nur im Service-Worker-Kontext (ServiceWorkerGlobalScope). Im Fenster-Kontext ist SyncEvent nicht definiert. Pflicht ist das Feld tag im Optionsobjekt. Daran erkennt der Handler, welche Aufgabe zu synchronisieren ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, in der Praxis immer "sync". |
|
| $options Pflicht | object | Optionsobjekt. Erbt die Felder von ExtendableEventInit (bubbles, cancelable, composed) und ergänzt diese:
|
Rückgabewert
SyncEvent-Objekt. Die Eigenschaften tag und lastChance sind schreibgeschützt.Beispiele
SyncEvent im Service Worker erzeugen
// sw.js
const event = new SyncEvent('sync', {
tag: 'outbox-senden',
lastChance: false
});
console.log(event.type, event.tag, event.lastChance);Typischer sync-Handler mit waitUntil()
// sw.js
const sendeOutbox = async () => {
const cache = await caches.open('outbox');
const anfragen = await cache.keys();
for (const req of anfragen) {
await fetch(req.clone());
await cache.delete(req);
}
};
self.addEventListener('sync', (event) => {
if (event.tag === 'outbox-senden') {
event.waitUntil(sendeOutbox());
}
if (event.lastChance) {
console.warn('Letzter Versuch für', event.tag);
}
});Synchronisierung für Tests manuell auslösen
// sw.js – nur zu Testzwecken
self.addEventListener('message', (msg) => {
if (msg.data === 'test-sync') {
const testEvent = new SyncEvent('sync', { tag: 'outbox-senden' });
self.dispatchEvent(testEvent);
console.log('Test-Sync ausgelöst:', testEvent.tag);
}
});
// Seite (main.js)
const reg = await navigator.serviceWorker.ready;
reg.active.postMessage('test-sync');Registrierung auf der Seite (auslösende Seite)
// main.js
const registriereSync = async () => {
const reg = await navigator.serviceWorker.ready;
if ('sync' in reg) {
await reg.sync.register('outbox-senden');
console.log('Sync registriert');
} else {
console.log('Background Sync nicht unterstützt – sofort senden');
}
};
registriereSync();// Wichtig · Fallstricke
- Browser-Unterstützung: Die Background Synchronization API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit
'sync' in registrationund sieh eine Ausweichlösung vor, etwa sofortiges Senden. - Nur im Service Worker: Außerhalb von
ServiceWorkerGlobalScopegibt esSyncEventnicht. Ein Aufruf im Fenster-Kontext endet mit einemReferenceError. - Fehlt
tagim Optionsobjekt, wirft der Konstruktor einenTypeError. - Ein selbst erzeugtes und mit
dispatchEvent()ausgelöstes Ereignis ist nicht vertrauenswürdig (isTrusted === false). Der Browser wiederholt fehlgeschlagene Versuche dann nicht automatisch. Solche Ereignisse eignen sich daher nur zum Testen. - Zum Testen echter Sync-Ereignisse gibt es in den Chrome DevTools unter Application → Service Workers das Feld „Sync“.
- Der Service Worker läuft nur für eine begrenzte Zeit. Lang laufende Synchronisierungen bricht der Browser ab. Die Arbeit sollte deshalb kurz sein und nicht von der Reihenfolge der Ausführung abhängen.