Navigator.windowControlsOverlay — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.windowControlsOverlay

Beschreibung

navigator.windowControlsOverlay gibt ein WindowControlsOverlay-Objekt zurück. Darüber steuert eine installierte Desktop-Progressive-Web-App (PWA) ihre eigene Titelleiste. Hat die App im Web-App-Manifest unter display_override den Wert "window-controls-overlay" eingetragen, kann der Nutzer die Standard-Titelleiste ausblenden. Der Web-Inhalt füllt dann das ganze Fenster. Nur die Fenster-Bedienelemente des Betriebssystems (Minimieren, Maximieren, Schließen) bleiben als Overlay sichtbar.

Das Objekt hat die Eigenschaft visible. Sie zeigt an, ob das Overlay gerade aktiv ist. Die Methode getTitlebarAreaRect() liefert ein DOMRect mit dem freien Bereich, in dem eigene Inhalte wie Suchfeld, Tabs oder App-Name Platz haben. Das Ereignis geometrychange meldet Änderungen, etwa wenn sich die Fenstergröße ändert oder der Nutzer das Overlay ein- oder ausschaltet.

Für das reine Layout reichen oft die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) und env(titlebar-area-height). Die JavaScript-API braucht man, wenn die Logik von der Geometrie abhängt. Beispiele: Elemente je nach verfügbarer Breite ein- oder ausblenden oder den Overlay-Zustand speichern.

Rückgabewert

Typ

WindowControlsOverlay | undefined

Beschreibung

Ein WindowControlsOverlay-Objekt (erbt von EventTarget) mit visible, getTitlebarAreaRect() und ongeometrychange. In Browsern ohne Unterstützung ist die Eigenschaft nicht vorhanden, der Wert ist also undefined.

Beispiele

Unterstützung und Sichtbarkeit prüfen

const overlay = navigator.windowControlsOverlay;

if (overlay) {
  console.log('Overlay aktiv:', overlay.visible);
  const rect = overlay.getTitlebarAreaRect();
  console.log(`Titelleisten-Bereich: x=${rect.x}, breite=${rect.width}, höhe=${rect.height}`);
} else {
  console.log('Window Controls Overlay wird nicht unterstützt.');
}

Overlay aktiv: true Titelleisten-Bereich: x=0, breite=1080, höhe=33

Auf Geometrieänderungen reagieren (mit Entprellung)

const overlay = navigator.windowControlsOverlay;
const search = document.querySelector('#titlebar-search');

const debounce = (fn, ms) => {
  let t;
  return (...args) => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
};

const updateLayout = ({ visible, titlebarAreaRect }) => {
  // Suchfeld nur zeigen, wenn Overlay aktiv und genug Platz ist
  search.hidden = !visible || titlebarAreaRect.width < 400;
};

if (overlay) {
  overlay.addEventListener('geometrychange', debounce(updateLayout, 200));
  updateLayout({ visible: overlay.visible, titlebarAreaRect: overlay.getTitlebarAreaRect() });
}

Manifest und CSS für die eigene Titelleiste

// manifest.webmanifest (Auszug):
// { "display_override": ["window-controls-overlay"], "display": "standalone" }

// Titelleiste per CSS positionieren und als Zieh-Bereich markieren
const style = document.createElement('style');
style.textContent = `
  .titlebar {
    position: fixed;
    left: env(titlebar-area-x, 0);
    top: env(titlebar-area-y, 0);
    width: env(titlebar-area-width, 100%);
    height: env(titlebar-area-height, 33px);
    -webkit-app-region: drag;
    app-region: drag;
  }
  .titlebar button, .titlebar input { app-region: no-drag; }
`;
document.head.append(style);

// Alternativ per on-Property:
if (navigator.windowControlsOverlay) {
  navigator.windowControlsOverlay.ongeometrychange = (e) =>
    document.body.classList.toggle('wco-active', e.visible);
}

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Chrome und Edge ab Version 105 auf Desktop-Systemen unterstützen die API. Firefox und Safari unterstützen sie nicht. Vor der Nutzung immer prüfen, z. B. mit if ('windowControlsOverlay' in navigator).
Die API funktioniert nur in einer installierten PWA, die im Manifest display_override: ["window-controls-overlay"] einträgt. Im normalen Browser-Tab ist visible immer false.
Nur in sicherem Kontext (HTTPS) verfügbar.
Das Ereignis geometrychange kann beim Ändern der Fenstergröße sehr oft auslösen. Aufwendige Handler sollte man daher entprellen.
Ohne app-region: drag lässt sich das Fenster nicht mehr verschieben. Interaktive Elemente brauchen dagegen app-region: no-drag, sonst reagieren sie nicht auf Klicks.
Sicherheit: Die eigene Titelleiste darf nicht wie Browser- oder Systemoberfläche aussehen (Spoofing-Gefahr). Der Browser blendet deshalb beim Start den App-Ursprung ein.

Siehe auch

Navigator Navigator.activeVRDisplays Navigator.webdriver Navigator.contacts Navigator.credentials