Signatur
Beschreibung
Das online-Ereignis wird am globalen Objekt eines Workers (WorkerGlobalScope, also self in einem Dedicated Worker, Shared Worker oder Service Worker) ausgelöst, sobald der Browser erkennt, dass wieder eine Netzwerkverbindung besteht. Gleichzeitig wechselt self.navigator.onLine (ein WorkerNavigator) auf true.
Das Ereignis ist nützlich, um in Hintergrund-Threads auf Verbindungswechsel zu reagieren – etwa um eine Warteschlange mit zwischengespeicherten Anfragen abzuarbeiten, Synchronisationen fortzusetzen oder dem Hauptthread per postMessage() den neuen Status mitzuteilen. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften; es lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling).
Registriert wird der Handler entweder mit self.addEventListener("online", handler) oder über die Eigenschaft self.ononline = handler. Das Gegenstück ist das offline-Ereignis, das beim Verlust der Verbindung feuert.
Wichtig: „online“ bedeutet lediglich, dass das Gerät mit einem Netzwerk verbunden ist – nicht, dass das Internet oder ein bestimmter Server tatsächlich erreichbar ist. Für verlässliche Aussagen sollte man zusätzlich eine echte Anfrage (z. B. per fetch()) absetzen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Der Ereignisname, hier immer "online". |
|
| $handler Pflicht | (event: Event) => void | Callback, der beim Wiederherstellen der Verbindung aufgerufen wird. Erhält ein einfaches Event-Objekt. |
|
| $options | boolean|AddEventListenerOptions | false | Optionale Listener-Optionen wie once oder signal (zum Entfernen per AbortController). |
Rückgabewert
addEventListener() gibt nichts zurück. Der Handler erhält ein Event mit type === "online".Beispiele
Verbindungsstatus im Worker an den Hauptthread melden
// worker.js
const report = () => {
self.postMessage({ type: 'network', online: self.navigator.onLine });
};
self.addEventListener('online', report);
self.addEventListener('offline', report);
// main.js
const worker = new Worker('worker.js');
worker.addEventListener('message', ({ data }) => {
if (data.type === 'network') {
console.log(`Netzwerk: ${data.online ? 'online' : 'offline'}`);
}
});Warteschlange nach Wiederverbindung abarbeiten
// worker.js
const queue = [];
self.addEventListener('message', ({ data }) => {
queue.push(data);
if (self.navigator.onLine) flushQueue();
});
const flushQueue = async () => {
while (queue.length > 0) {
const item = queue[0];
try {
await fetch('/api/events', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(item)
});
queue.shift();
} catch (err) {
console.warn('Senden fehlgeschlagen, später erneut:', err.message);
break;
}
}
};
self.addEventListener('online', flushQueue);on-Property verwenden und Listener wieder entfernen
// worker.js – Variante über die Eigenschaft
self.ononline = () => {
console.log('Worker: wieder online');
};
// Variante mit AbortController zum sauberen Entfernen
const controller = new AbortController();
self.addEventListener('online', () => {
console.log('Einmalige Reaktion auf Wiederverbindung');
}, { signal: controller.signal });
// Später: Listener entfernen
controller.abort();
self.ononline = null;// Wichtig · Fallstricke
- Kein Garant für Internetzugang: Das Ereignis signalisiert nur eine Netzwerkverbindung (z. B. WLAN ohne Internet, Captive Portal). Prüfen Sie die Erreichbarkeit mit einer echten Anfrage und Fehlerbehandlung.
- Browser-Unterschiede: Die Unterstützung von
online/offlinein Workern ist uneinheitlich; ältere Browser und manche Worker-Typen lösen das Ereignis nicht aus. Als Fallback kann der Hauptthread dasonline-Ereignis vonwindowabfangen und perpostMessage()weiterreichen. - Service Worker: Ein Service Worker kann jederzeit beendet werden – verlassen Sie sich nicht darauf, dass er beim Wiederverbinden läuft. Für zuverlässige Hintergrund-Synchronisation eignet sich die Background Sync API (
sync-Ereignis), wo verfügbar. - Das Ereignis kann bei instabilen Verbindungen mehrfach kurz hintereinander feuern; aufwendige Aktionen ggf. entprellen.