ServiceWorker.state — Eigenschaft · JavaScript-Referenz

Signatur

ServiceWorker.state

Beschreibung

Die schreibgeschützte Eigenschaft state des ServiceWorker-Interfaces gibt an, in welcher Phase seines Lebenszyklus sich ein Service Worker gerade befindet. Mögliche Werte sind:

"parsed" – das Skript wurde geladen und geparst, die Installation hat aber noch nicht begonnen.
"installing" – das install-Ereignis läuft (z. B. Vorab-Caching von Ressourcen).
"installed" – Installation abgeschlossen, der Worker wartet auf die Aktivierung (in der Registrierung als waiting sichtbar).
"activating" – das activate-Ereignis läuft (z. B. Aufräumen alter Caches).
"activated" – der Worker ist aktiv und kann fetch-, push- und weitere funktionale Ereignisse verarbeiten.
"redundant" – der Worker wurde verworfen, weil die Installation fehlschlug oder er durch eine neuere Version ersetzt wurde.

In der Praxis liest man state meist in Kombination mit dem Ereignis statechange, das bei jeder Zustandsänderung am ServiceWorker-Objekt ausgelöst wird. Typische Einsatzfälle sind das Anzeigen eines Hinweises „Neue Version verfügbar“, sobald ein aktualisierter Worker den Zustand "installed" erreicht, oder das Warten auf "activated", bevor die Seite auf Offline-Funktionen vertraut.

Man erhält ServiceWorker-Objekte über ServiceWorkerRegistration.installing, .waiting und .active sowie über navigator.serviceWorker.controller. Innerhalb des Worker-Skripts selbst ist der eigene Zustand über self.serviceWorker.state abrufbar (neuere Browser).

Rückgabewert

Typ

Beschreibung

Ein String, der den aktuellen Lebenszyklus-Zustand des Service Workers beschreibt.

Beispiele

Zustand nach der Registrierung ausgeben

const registerSW = async () => {
  if (!('serviceWorker' in navigator)) return;

  const registration = await navigator.serviceWorker.register('/sw.js');
  const worker = registration.installing ?? registration.waiting ?? registration.active;

  if (worker) {
    console.log('Aktueller Zustand:', worker.state);
  }
};

registerSW();

Aktueller Zustand: installing

Zustandsänderungen mit statechange verfolgen

const registration = await navigator.serviceWorker.register('/sw.js');
const worker = registration.installing;

if (worker) {
  worker.addEventListener('statechange', () => {
    console.log('Neuer Zustand:', worker.state);
    if (worker.state === 'redundant') {
      console.warn('Installation fehlgeschlagen oder Worker ersetzt.');
    }
  });
}

Neuer Zustand: installed Neuer Zustand: activating Neuer Zustand: activated

Hinweis „Update verfügbar“ anzeigen

const registration = await navigator.serviceWorker.getRegistration();

registration?.addEventListener('updatefound', () => {
  const newWorker = registration.installing;

  newWorker.addEventListener('statechange', () => {
    // Nur ein Update, wenn bereits ein Worker die Seite steuert
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      const banner = document.querySelector('#update-banner');
      banner.hidden = false;
      banner.querySelector('button').onclick = () => {
        newWorker.postMessage({ type: 'SKIP_WAITING' });
      };
    }
  });
});

Auf Aktivierung warten (Promise-Helfer)

const waitForActivation = (worker) =>
  new Promise((resolve, reject) => {
    if (worker.state === 'activated') return resolve(worker);
    const onChange = () => {
      if (worker.state === 'activated') {
        worker.removeEventListener('statechange', onChange);
        resolve(worker);
      } else if (worker.state === 'redundant') {
        worker.removeEventListener('statechange', onChange);
        reject(new Error('Service Worker wurde verworfen'));
      }
    };
    worker.addEventListener('statechange', onChange);
  });

const reg = await navigator.serviceWorker.register('/sw.js');
await waitForActivation(reg.installing ?? reg.waiting ?? reg.active);
console.log('Offline-Modus bereit');

Offline-Modus bereit

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen an state werden ignoriert; Zustandsübergänge steuert ausschließlich der Browser (bzw. indirekt skipWaiting() und clients.claim()).
Momentaufnahme: Der Wert kann sich jederzeit ändern. Nach einem await ist ein zuvor gelesener Zustand eventuell veraltet – immer auf statechange reagieren statt zu pollen.
Zustände können übersprungen werden: Registriert man den statechange-Listener zu spät, verpasst man frühe Übergänge. Deshalb vor dem Warten den aktuellen Wert prüfen (siehe Promise-Helfer).
"parsed" ist für Seitenskripte praktisch nie sichtbar, da register() den Worker erst im Zustand "installing" liefert.
Ein Worker im Zustand "installed" ohne bestehenden controller ist eine Erstinstallation, kein Update.
Kompatibilität: In allen modernen Browsern verfügbar; Service Worker erfordern einen sicheren Kontext (HTTPS oder localhost) und sind in privaten Fenstern mancher Browser (z. B. Firefox) deaktiviert.

Siehe auch

ServiceWorker ServiceWorkerRegistration ServiceWorkerContainer.register() ServiceWorkerGlobalScope.skipWaiting() MediaRecorder.stream