ServiceWorkerRegistration.active — Eigenschaft · JavaScript-Referenz

Signatur

ServiceWorkerRegistration.active

Beschreibung

Die schreibgeschützte Eigenschaft active eines ServiceWorkerRegistration-Objekts verweist auf den Service Worker, der gerade aktiviert wird oder schon aktiv ist. Sein ServiceWorker.state ist also "activating" oder "activated". Gibt es noch keinen solchen Worker, zum Beispiel direkt nach der ersten Registrierung während der Installation, ist der Wert null.

Eine Registrierung kann bis zu drei Worker gleichzeitig haben: installing, waiting und active. Mit active erreichst du den Worker, der Fetch-Anfragen abfängt und Push- oder Sync-Ereignisse verarbeitet. Das gilt für alle Seiten, die er kontrolliert (clients). Über registration.active.postMessage() kannst du ihm Nachrichten schicken, etwa um den Cache zu leeren oder die Version abzufragen.

Wichtig: Ein aktiver Worker muss die aktuelle Seite nicht zwingend kontrollieren. Beim ersten Laden ist registration.active nach der Aktivierung zwar gesetzt, navigator.serviceWorker.controller bleibt aber null. Das ändert sich erst beim nächsten Neuladen oder wenn der Worker clients.claim() aufruft.

Rückgabewert

Typ

ServiceWorker | null

Beschreibung

Der ServiceWorker im Zustand "activating" oder "activated", oder null, wenn für diese Registrierung noch kein Worker aktiviert wurde.

Beispiele

Aktiven Worker nach der Registrierung prüfen

if ('serviceWorker' in navigator) {
  const registration = await navigator.serviceWorker.register('/sw.js');

  if (registration.active) {
    console.log('Aktiver Worker:', registration.active.scriptURL, registration.active.state);
  } else {
    console.log('Noch kein aktiver Worker – Installation läuft.');
  }
}

Aktiver Worker: https://example.com/sw.js activated

Mit navigator.serviceWorker.ready auf den aktiven Worker warten

// ready wird erst erfüllt, wenn die Registrierung einen aktiven Worker hat
const registration = await navigator.serviceWorker.ready;

// Hier ist active garantiert nicht null
registration.active.postMessage({ type: 'CLEAR_CACHE' });
console.log('Nachricht gesendet an', registration.active.scriptURL);

Nachricht gesendet an https://example.com/sw.js

Version des aktiven Workers per MessageChannel abfragen

const getWorkerVersion = async () => {
  const { active } = await navigator.serviceWorker.ready;
  const channel = new MessageChannel();

  return new Promise((resolve) => {
    channel.port1.onmessage = (event) => resolve(event.data.version);
    active.postMessage({ type: 'GET_VERSION' }, [channel.port2]);
  });
};

// In sw.js:
// self.addEventListener('message', (e) => {
//   if (e.data.type === 'GET_VERSION') e.ports[0].postMessage({ version: '1.4.2' });
// });

console.log('SW-Version:', await getWorkerVersion());

SW-Version: 1.4.2

Zustandswechsel des Workers beobachten

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

worker?.addEventListener('statechange', () => {
  console.log('Neuer Zustand:', worker.state);
  if (worker.state === 'activated') {
    console.log('Jetzt aktiv:', registration.active === worker);
  }
});

Neuer Zustand: installed Neuer Zustand: activating Neuer Zustand: activated Jetzt aktiv: true

// Wichtig · Fallstricke

Kann null sein: Prüfe den Wert direkt nach register() immer, bevor du ihn benutzt. Oder warte auf navigator.serviceWorker.ready. Dieses Promise wird erst erfüllt, wenn ein aktiver Worker existiert.
active ist nicht controller: Ein aktiver Worker kontrolliert die aktuelle Seite nicht automatisch. Ob die Seite wirklich kontrolliert wird, zeigt navigator.serviceWorker.controller. Mit clients.claim() im Worker übernimmt er die Kontrolle sofort.
Updates: Ein neuer Worker bleibt im Zustand waiting, bis kein Tab mehr vom alten Worker kontrolliert wird. Erst dann ändert sich active. Mit skipWaiting() lässt sich das beschleunigen.
Sicherer Kontext: Service Worker funktionieren nur über HTTPS (oder localhost). In manchen privaten Browserfenstern (z. B. im privaten Modus von Firefox) ist navigator.serviceWorker nicht verfügbar.
Nachrichten: Prüfe in postMessage-Handlern im Worker die Struktur der Daten. Nimm eingehende Nachrichten nicht ungeprüft als vertrauenswürdig an.

Siehe auch

ServiceWorkerRegistration.scope ServiceWorkerRegistration.waiting ServiceWorkerRegistration.cookies ServiceWorkerRegistration.index ServiceWorkerRegistration.sync