ServiceWorkerRegistration.scope — Eigenschaft · JavaScript-Referenz

Signatur

ServiceWorkerRegistration.scope

Beschreibung

Die schreibgeschützte Eigenschaft scope eines ServiceWorkerRegistration-Objekts gibt eine absolute URL als String zurück. Diese URL legt fest, welche Seiten der Service Worker kontrolliert: Jede Navigation und jeder Abruf von einer Seite, deren URL mit dem Scope beginnt, kann über den Worker laufen, zum Beispiel über das fetch-Event.

Den Scope legst du beim Aufruf von navigator.serviceWorker.register(scriptURL, { scope }) fest. Gibst du keinen an, verwendet der Browser standardmäßig das Verzeichnis des Worker-Skripts (bei /app/sw.js also /app/). Auch relative Angaben wie './' werden aufgelöst, sodass scope immer die vollständige URL samt Ursprung (Origin) enthält.

In der Praxis brauchst du scope vor allem, um mehrere Registrierungen auseinanderzuhalten, gezielt eine bestimmte Registrierung abzumelden, beim Debuggen zu protokollieren, welcher Bereich abgedeckt ist, oder im Worker selbst (über self.registration.scope) URLs relativ zum Scope zu bilden.

Rückgabewert

Typ

string

Beschreibung

Absolute URL des Registrierungsbereichs, z. B. "https://example.com/app/".

Beispiele

Scope nach der Registrierung ausgeben

const registerWorker = async () => {
  if (!('serviceWorker' in navigator)) return;
  try {
    const registration = await navigator.serviceWorker.register('/app/sw.js', {
      scope: '/app/'
    });
    console.log('Registriert für:', registration.scope);
  } catch (err) {
    console.error('Registrierung fehlgeschlagen:', err);
  }
};

registerWorker();

Registriert für: https://example.com/app/

Nur eine bestimmte Registrierung abmelden

const unregisterByScope = async (path) => {
  const target = new URL(path, location.origin).href;
  const registrations = await navigator.serviceWorker.getRegistrations();

  for (const reg of registrations) {
    if (reg.scope === target) {
      const ok = await reg.unregister();
      console.log(`Abgemeldet (${reg.scope}):`, ok);
    }
  }
};

unregisterByScope('/legacy/');

Abgemeldet (https://example.com/legacy/): true

Scope im Service Worker für Offline-Seite nutzen

// sw.js
const offlineUrl = new URL('offline.html', self.registration.scope).href;

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('v1').then((cache) => cache.add(offlineUrl))
  );
});

self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    event.respondWith(
      fetch(event.request).catch(() => caches.match(offlineUrl))
    );
  }
});

// Wichtig · Fallstricke

Standardmäßig höchstens das Skriptverzeichnis: Ein Worker unter /app/sw.js darf nur einen Scope von /app/ oder tiefer haben. Für einen weiter gefassten Scope (z. B. /) muss der Server das Skript mit dem HTTP-Header Service-Worker-Allowed: / ausliefern, sonst wirft register() einen SecurityError.
Präfix-Abgleich: Der Scope wird rein als Zeichenketten-Präfix verglichen. /app (ohne abschließenden Schrägstrich) passt auch auf /apple.html. Hänge deshalb am besten immer einen / an.
Vergleiche mit absoluten URLs: scope ist immer absolut. Wandle relative Pfade vorher mit new URL(pfad, location.origin).href um.
Die Eigenschaft ist schreibgeschützt. Um den Scope zu ändern, musst du den Worker neu registrieren und die alte Registrierung per unregister() abmelden.
Service Worker gibt es nur in sicheren Kontexten (HTTPS oder localhost). Im privaten Modus mancher Browser (z. B. Firefox) sind sie nicht verfügbar.

Siehe auch

ServiceWorker.scriptURL ServiceWorkerRegistration.active ServiceWorkerRegistration.sync ServiceWorkerRegistration.cookies ServiceWorkerRegistration.index