WindowClient.navigate() — Methode · JavaScript-Referenz

Signatur

WindowClient.prototype.navigate(url)

Beschreibung

Mit navigate() steuert ein Service Worker die Navigation eines Browserfensters oder Tabs, das er kontrolliert. Das ist so, als würde die Seite selbst location.href setzen. Der Aufruf kommt aber aus dem Worker, also genau dann, wenn die Seite selbst nichts davon weiß. Das WindowClient-Objekt dazu holen Sie sich über clients.matchAll(), clients.get() oder aus event.source eines message-Events.

Typische Einsatzfälle:

Nach einem Update des Service Workers alle offenen Tabs neu laden, damit sie die neuen Ressourcen aus dem Cache verwenden.
Beim Klick auf eine Benachrichtigung (notificationclick) einen schon offenen Tab auf eine bestimmte Seite umleiten, statt ein neues Fenster zu öffnen.
Nutzer nach einer Abmeldung oder bei abgelaufener Sitzung zentral auf die Anmeldeseite schicken.

Das zurückgegebene Promise erfüllt sich mit einem WindowClient, wenn die Zielseite denselben Ursprung (Origin) hat wie der Service Worker. Bei einer Navigation zu einem fremden Ursprung erfüllt es sich mit null, denn aus Sicherheitsgründen darf der Worker keinen Zugriff auf fremde Clients bekommen. Relative URLs werden relativ zur URL des Service-Worker-Skripts aufgelöst, nicht relativ zur aktuellen Seite.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Ziel der Navigation. Relative Angaben werden gegen die Basis-URL des Service-Worker-Skripts aufgelöst. `about:blank` ist nicht erlaubt.

Rückgabewert

Typ

Promise<WindowClient | null>

Beschreibung

Erfüllt sich nach der Navigation mit dem aktualisierten WindowClient, wenn das Ziel denselben Ursprung hat, sonst mit null. Das Promise wird mit einem TypeError abgelehnt, wenn die URL ungültig oder about:blank ist oder wenn der Client nicht von diesem Service Worker kontrolliert wird.

Beispiele

Alle kontrollierten Tabs nach einem Update neu laden

// sw.js
self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    // Sofort die Kontrolle über offene Seiten übernehmen
    await self.clients.claim();
    const windows = await self.clients.matchAll({ type: 'window' });
    for (const client of windows) {
      // Aktuelle URL erneut laden, damit neue Assets greifen
      await client.navigate(client.url);
    }
    console.log(`${windows.length} Tab(s) neu geladen`);
  })());
});

2 Tab(s) neu geladen

Benachrichtigung öffnet vorhandenen Tab statt neuem Fenster

// sw.js
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const target = new URL('/nachrichten', self.location.origin).href;

  event.waitUntil((async () => {
    const windows = await self.clients.matchAll({
      type: 'window',
      includeUncontrolled: false
    });

    if (windows.length > 0) {
      const client = windows[0];
      const navigated = await client.navigate(target);
      // navigate() kann null liefern (fremder Ursprung)
      await (navigated ?? client).focus();
    } else {
      await self.clients.openWindow(target);
    }
  })());
});

Auf Nachricht der Seite hin umleiten, mit Fehlerbehandlung

// sw.js
self.addEventListener('message', (event) => {
  if (event.data?.type !== 'LOGOUT') return;

  event.waitUntil((async () => {
    const client = event.source; // WindowClient der sendenden Seite
    try {
      const result = await client.navigate('/login?grund=abgemeldet');
      console.log('Navigiert zu:', result?.url ?? '(fremder Ursprung)');
    } catch (err) {
      // z. B. TypeError, wenn der Client nicht kontrolliert wird
      console.error('Navigation fehlgeschlagen:', err.name, err.message);
    }
  })());
});

// In der Seite:
// navigator.serviceWorker.controller?.postMessage({ type: 'LOGOUT' });

Navigiert zu: https://example.com/login?grund=abgemeldet

// Wichtig · Fallstricke

Nur kontrollierte Clients: Wenn der Client nicht von diesem Service Worker kontrolliert wird, wird das Promise mit einem TypeError abgelehnt. Das passiert z. B. bei Clients aus matchAll({ includeUncontrolled: true }) oder direkt nach der Installation, solange clients.claim() noch nicht aufgerufen wurde.
Relative URLs: Sie werden gegen die URL des Worker-Skripts aufgelöst, nicht gegen die URL der Seite. Liegt das Skript z. B. unter /js/sw.js, wird 'seite.html' zu /js/seite.html. Verwenden Sie deshalb absolute Pfade oder new URL(pfad, self.location.origin).
Fremder Ursprung ergibt null: Die Navigation selbst findet statt, aber der Worker erhält danach keinen Zugriff mehr auf den Client. Prüfen Sie den Rückgabewert immer auf null.
Nur im Service Worker verfügbar: WindowClient gibt es weder im Fensterkontext noch in normalen Web Workern. Ein Service Worker braucht einen sicheren Kontext (HTTPS oder localhost).
Kompatibilität: Chromium- und Firefox-Browser unterstützen die Methode schon lange, Safari erst seit neueren Versionen. Prüfen Sie für ältere Safari-Versionen mit 'navigate' in WindowClient.prototype, ob die Methode vorhanden ist, und nutzen Sie sonst eine postMessage-Lösung, bei der die Seite selbst navigiert.
Ungespeicherte Formulareingaben in der Seite gehen verloren. Ein beforeunload-Dialog kann die Navigation je nach Browser verhindern oder verzögern.

Siehe auch

Clients.claim() WindowClient.focus() Navigation.navigate() Window.clearImmediate() Window.setImmediate()