Clients.get() — Methode · JavaScript-Referenz

Signatur

Clients.prototype.get(id)

Beschreibung

Clients.get() wird im Service Worker über self.clients.get(id) aufgerufen. Die Methode sucht unter allen Clients mit demselben Ursprung wie der Service Worker nach dem Client mit der passenden ID. Gefunden wird ein Client-Objekt, bei Browserfenstern bzw. Tabs ein WindowClient.

Meist stammt die ID aus FetchEvent.clientId (oder resultingClientId) oder aus event.source.id in einem message-Ereignis. Damit kann der Service Worker gezielt genau der Seite antworten, die eine Anfrage ausgelöst hat, zum Beispiel per postMessage().

Gibt es keinen passenden Client, etwa weil der Tab inzwischen geschlossen wurde, wird das Promise mit undefined erfüllt und nicht abgelehnt. Prüfe den Rückgabewert deshalb immer, bevor du ihn verwendest.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die eindeutige ID des gesuchten Clients, z. B. aus `FetchEvent.clientId` oder `Client.id`.

Rückgabewert

Typ

Promise<Client | WindowClient | undefined>

Beschreibung

Ein Promise, das mit dem passenden Client-Objekt erfüllt wird oder mit undefined, wenn kein Client mit dieser ID existiert.

Beispiele

Der auslösenden Seite im fetch-Handler eine Nachricht senden

// sw.js
self.addEventListener('fetch', (event) => {
  if (!event.clientId) return; // z. B. bei Navigationsanfragen leer

  event.waitUntil((async () => {
    const client = await self.clients.get(event.clientId);
    if (!client) return; // Tab wurde bereits geschlossen

    client.postMessage({
      type: 'FETCH_LOG',
      url: event.request.url
    });
  })());
});

Antwort auf eine Nachricht an genau einen Client

// sw.js
self.addEventListener('message', (event) => {
  event.waitUntil((async () => {
    const client = await self.clients.get(event.source.id);
    if (client) {
      client.postMessage({ type: 'PONG', received: event.data });
    }
  })());
});

// Seite (main.js)
navigator.serviceWorker.addEventListener('message', (e) => {
  console.log('Antwort vom SW:', e.data.type);
});
navigator.serviceWorker.controller?.postMessage('PING');

Antwort vom SW: PONG

Client-Typ prüfen und Fenster fokussieren

// sw.js – ID wurde zuvor z. B. in IndexedDB gespeichert
const focusClientById = async (id) => {
  const client = await self.clients.get(id);
  if (!client) {
    console.log('Client nicht gefunden');
    return null;
  }
  console.log(client.type, client.url);
  if (client.type === 'window' && 'focus' in client) {
    return client.focus(); // focus() nur innerhalb einer Nutzerinteraktion, z. B. notificationclick
  }
  return client;
};

window https://example.com/app

// Wichtig · Fallstricke

Kein Fehler bei unbekannter ID: Das Promise wird mit undefined erfüllt. Deshalb immer auf undefined prüfen.
FetchEvent.clientId ist bei Navigationsanfragen oft ein leerer String. Nutze dann resultingClientId, beachte aber, dass dieser Client beim Aufruf eventuell noch nicht vollständig existiert.
Gefunden werden nur Clients mit demselben Ursprung wie der Service Worker. Ob sie gerade vom Service Worker gesteuert werden, spielt keine Rolle.
Asynchrone Arbeit in Event-Handlern immer in event.waitUntil() einschließen. Sonst kann der Browser den Service Worker vorzeitig beenden.
Nur im Service-Worker-Kontext verfügbar, nicht auf normalen Seiten. Service Worker brauchen einen sicheren Kontext (HTTPS oder localhost).
Client-IDs sind nicht dauerhaft gültig: Wird die Seite neu geladen, bekommt sie eine neue ID.

Siehe auch

Clients Clients.claim() Client Clients.matchAll() Clients.openWindow()