WindowControlsOverlay.getTitlebarAreaRect() — Methode · JavaScript-Referenz

Signatur

WindowControlsOverlay.prototype.getTitlebarAreaRect()

Beschreibung

Die Methode getTitlebarAreaRect() des Interfaces WindowControlsOverlay (erreichbar über navigator.windowControlsOverlay) gibt die aktuelle Geometrie des Titelleistenbereichs einer installierten Progressive Web App zurück. Gemeint ist der freie Bereich neben den systemeigenen Fenster-Schaltflächen (Minimieren, Maximieren, Schließen), in dem die App eigene Inhalte wie Suchfeld, Tabs oder Menüs anzeigen kann.

Die Funktion steht nur zur Verfügung, wenn im Web-App-Manifest "display_override": ["window-controls-overlay"] gesetzt ist, die App als eigenständiges Fenster installiert läuft und das Overlay aktiv ist. Ist das Overlay nicht sichtbar, z. B. weil der Nutzer es über die Titelleiste ausgeschaltet hat, liefert die Methode ein DOMRect, bei dem alle Werte 0 sind.

In der Praxis wird die Methode meist zusammen mit dem Ereignis geometrychange und der Eigenschaft visible verwendet, um das Layout per JavaScript anzupassen. Für reine Layoutfragen sind oft die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) und env(titlebar-area-height) einfacher. Die Methode ist dann nützlich, wenn man die Maße im Skript braucht, etwa um Elemente per Canvas zu zeichnen oder um abhängig von der verfügbaren Breite verschiedene Komponenten anzuzeigen.

Rückgabewert

Typ

DOMRect

Beschreibung

Ein DOMRect mit x, y, width und height (in CSS-Pixeln) des verfügbaren Titelleistenbereichs. Ist das Overlay nicht sichtbar, sind alle Werte 0.

Beispiele

Titelleistenbereich auslesen mit Feature-Erkennung

// Manifest: "display_override": ["window-controls-overlay"]
const wco = navigator.windowControlsOverlay;

if (wco && wco.visible) {
  const { x, y, width, height } = wco.getTitlebarAreaRect();
  console.log(`Titelleiste: x=${x}, y=${y}, ${width}×${height}px`);
} else {
  console.log('Window Controls Overlay nicht aktiv');
}

Titelleiste: x=0, y=0, 1146×33px

Layout bei Größenänderung anpassen (geometrychange)

const wco = navigator.windowControlsOverlay;
const header = document.querySelector('#app-titlebar');

const applyTitlebarRect = () => {
  const rect = wco.getTitlebarAreaRect();
  header.hidden = !wco.visible;
  header.style.left = `${rect.x}px`;
  header.style.width = `${rect.width}px`;
  header.style.height = `${rect.height}px`;
  // Bei wenig Platz das Suchfeld ausblenden
  header.classList.toggle('compact', rect.width < 400);
};

if (wco) {
  applyTitlebarRect();
  wco.addEventListener('geometrychange', applyTitlebarRect);
}

Overlay ausgeschaltet: alle Werte sind 0

const wco = navigator.windowControlsOverlay;

if (wco) {
  const rect = wco.getTitlebarAreaRect();
  const isEmpty = rect.width === 0 && rect.height === 0;
  console.log(wco.visible, isEmpty);
}

false true

// Wichtig · Fallstricke

Browser-Kompatibilität: Experimentell und nur in Chromium-basierten Desktop-Browsern (Chrome/Edge ab 105) verfügbar. Firefox und Safari kennen die API nicht, daher immer per if (navigator.windowControlsOverlay) prüfen.
Nur im sicheren Kontext (HTTPS) und nur in einer installierten PWA mit display_override: ["window-controls-overlay"] im Manifest. In einem normalen Browser-Tab gibt es kein sichtbares Overlay.
Der Rückgabewert ist nur eine Momentaufnahme: Die Maße ändern sich beim Ändern der Fenstergröße und beim Ein- oder Ausschalten des Overlays. Aktualisieren Sie deshalb im geometrychange-Ereignis. Das Ereignis wird gedrosselt ausgelöst, also keine aufwendige Arbeit pro Aufruf erledigen.
Der Bereich ist standardmäßig nicht verschiebbar. Damit das Fenster weiter an der Titelleiste gezogen werden kann, braucht der Bereich app-region: drag (bzw. -webkit-app-region: drag). Interaktive Elemente darin brauchen app-region: no-drag.
Für reines Layout sind die CSS-Variablen env(titlebar-area-*) oft robuster, weil sie ohne JavaScript und ohne Flackern beim ersten Rendern funktionieren.

Siehe auch

DOMRect new WindowControlsOverlayGeometryChangeEvent() Window.requestIdleCallback() VRDisplay.getEyeParameters() Window.cancelAnimationFrame()