Signatur
Client.frameType
Beschreibung
Die Eigenschaft frameType der Client-Schnittstelle zeigt, in welcher Art von Browsing-Kontext ein vom Service Worker kontrollierter (oder erreichbarer) Client läuft. So kann ein Service Worker unterscheiden, ob eine Seite als eigenständiger Tab, in einem <iframe> oder als per window.open() geöffnetes Hilfsfenster angezeigt wird.
Mögliche Werte:
"top-level"– ein normales Fenster oder ein Tab auf oberster Ebene."nested"– ein eingebetteter Kontext, z. B. ein<iframe>oder<frame>."auxiliary"– ein Hilfsfenster mit Bezug zu einem öffnenden Fenster (window.open(),target="_blank"mit Opener)."none"– kein Browsing-Kontext, etwa bei Workern (Worker,SharedWorker).
In der Praxis nutzt man frameType nach clients.matchAll(), um gezielt nur Tabs auf oberster Ebene zu fokussieren, Benachrichtigungen nicht an eingebettete Frames zu schicken oder beim Klick auf eine Push-Benachrichtigung das richtige Fenster auszuwählen.
Rückgabewert
Typ
"auxiliary" | "top-level" | "nested" | "none"
Beschreibung
Eine Zeichenkette, die den Typ des Browsing-Kontexts des Clients beschreibt.
Beispiele
Alle Clients mit ihrem Frame-Typ auflisten
// sw.js
self.addEventListener('message', async (event) => {
if (event.data !== 'list-clients') return;
const allClients = await self.clients.matchAll({ includeUncontrolled: true });
for (const client of allClients) {
console.log(client.url, client.frameType);
}
});https://example.com/ top-level
https://example.com/widget.html nested
Bei Klick auf Benachrichtigung nur Tabs oberster Ebene fokussieren
// sw.js
self.addEventListener('notificationclick', (event) => {
event.notification.close();
event.waitUntil((async () => {
const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
// iframes ausschließen – die lassen sich nicht sinnvoll fokussieren
const topLevel = windows.find((c) => c.frameType === 'top-level');
if (topLevel) {
await topLevel.focus();
} else {
await self.clients.openWindow('/posteingang');
}
})());
});Nachrichten nur an eingebettete Frames senden
// sw.js
const notifyEmbeds = async (payload) => {
const windows = await self.clients.matchAll({ type: 'window' });
const nested = windows.filter((c) => c.frameType === 'nested');
nested.forEach((c) => c.postMessage({ type: 'update', payload }));
return nested.length;
};
self.addEventListener('push', (event) => {
event.waitUntil(notifyEmbeds(event.data?.text() ?? ''));
});// Wichtig · Fallstricke
frameTypeist schreibgeschützt; Zuweisungen werden ignoriert (im Strict Mode ggf.TypeError).- Die Eigenschaft ist nur im Service-Worker-Kontext verfügbar, da
Client-Objekte ausschließlich überself.clientsbzw.event.sourceerreichbar sind. Service Worker erfordern HTTPS (Ausnahme:localhost). - Nicht verwechseln mit
Client.type:typebeschreibt die Art des Clients ("window","worker","sharedworker"),frameTypedagegen die Einbettung des Browsing-Kontexts. - Für Worker-Clients ist der Wert immer
"none". - Browser-Kompatibilität: in allen modernen Browsern (Chromium, Firefox, Safari) unterstützt; nicht im Internet Explorer.