WorkerGlobalScope: offline — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("offline", handler)

Beschreibung

Das Ereignis offline wird am globalen Objekt eines Workers (DedicatedWorkerGlobalScope, SharedWorkerGlobalScope, eingeschränkt auch ServiceWorkerGlobalScope) ausgelöst, sobald der Browser meldet, dass keine Netzwerkverbindung mehr besteht. Gleichzeitig wechselt self.navigator.onLine (ein WorkerNavigator) auf false. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften, es steigt nicht auf und lässt sich nicht abbrechen.

Nützlich ist es für Worker, die selbstständig Netzwerkarbeit erledigen – etwa Synchronisation, Polling, WebSocket-Verbindungen oder Upload-Warteschlangen. Statt fehlschlagende Anfragen erst per catch zu bemerken, kann der Worker bei offline seine Timer anhalten, Aufträge zwischenspeichern (z. B. in IndexedDB) und die Seite per postMessage() informieren. Beim Gegenstück online wird die Arbeit wieder aufgenommen.

Registrieren lässt sich der Handler entweder mit self.addEventListener("offline", handler) oder über die Eigenschaft self.onoffline = handler. Innerhalb eines Workers verweist self auf den WorkerGlobalScope; ein window-Objekt gibt es dort nicht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"offline"`.
$handler Pflicht	(event: Event) => void \| EventListenerObject		Callback, der beim Verbindungsverlust aufgerufen wird. Erhält ein einfaches `Event`-Objekt mit `type === "offline"`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Beispiele

Worker pausiert Polling bei Verbindungsverlust

// worker.js
let timerId = null;

const poll = async () => {
  try {
    const res = await fetch('/api/status');
    const data = await res.json();
    self.postMessage({ type: 'status', data });
  } catch (err) {
    console.warn('Polling fehlgeschlagen:', err.message);
  }
};

const startPolling = () => {
  if (timerId === null) timerId = setInterval(poll, 5000);
};

const stopPolling = () => {
  clearInterval(timerId);
  timerId = null;
};

self.addEventListener('offline', () => {
  console.log('Worker: offline – Polling angehalten');
  stopPolling();
  self.postMessage({ type: 'connection', online: false });
});

self.addEventListener('online', () => {
  console.log('Worker: wieder online – Polling läuft');
  startPolling();
  self.postMessage({ type: 'connection', online: true });
});

if (self.navigator.onLine) startPolling();

Worker: offline – Polling angehalten

Handler über die onoffline-Eigenschaft setzen

// worker.js
self.onoffline = (event) => {
  console.log(`Ereignis: ${event.type}, onLine = ${self.navigator.onLine}`);
};

// Handler später wieder entfernen
// self.onoffline = null;

Ereignis: offline, onLine = false

Listener per AbortController entfernen und Seite informieren

// main.js
const worker = new Worker('worker.js');
worker.addEventListener('message', ({ data }) => {
  if (data.type === 'connection') {
    document.body.classList.toggle('is-offline', !data.online);
  }
});

// worker.js
const controller = new AbortController();

self.addEventListener('offline', () => {
  self.postMessage({ type: 'connection', online: false });
}, { signal: controller.signal });

self.addEventListener('message', ({ data }) => {
  if (data === 'shutdown') {
    controller.abort(); // entfernt den offline-Listener
    self.close();
  }
});

// Wichtig · Fallstricke

Unzuverlässige Aussagekraft: offline bedeutet nur, dass der Browser keine Netzwerkschnittstelle mehr sieht. Umgekehrt heißt „online“ nicht, dass das Internet oder dein Server wirklich erreichbar ist (z. B. WLAN ohne Uplink, Captive Portal). Netzwerkfehler bei fetch() daher immer zusätzlich abfangen.
Browser-Kompatibilität: Die Unterstützung in Workern ist uneinheitlicher als bei window. Manche Browser lösen das Ereignis in Workern nicht oder verspätet aus. Im Zweifel den Status im Hauptthread über window beobachten und per postMessage() an den Worker weiterreichen.
Service Worker: Service Worker können jederzeit beendet werden; ein dort registrierter offline-Listener eignet sich nicht für dauerhaften Zustand. Für Offline-Synchronisation eher die Background Sync API bzw. Caching-Strategien im fetch-Handler nutzen.
Listener synchron auf oberster Ebene des Worker-Skripts registrieren, damit keine Ereignisse verloren gehen.
Einige Browser feuern das Ereignis auch, wenn der Nutzer den „Offline-Modus“ in den DevTools aktiviert – praktisch zum Testen.

Siehe auch

WorkerNavigator.onLine WorkerGlobalScope Worker.prototype.postMessage() EventTarget.prototype.addEventListener() LanguageModel: contextoverflow