WindowControlsOverlay: geometrychange — Ereignis · JavaScript-Referenz

Signatur

navigator.windowControlsOverlay.addEventListener("geometrychange", handler)

Beschreibung

Das Ereignis geometrychange gehört zum Interface WindowControlsOverlay, das über navigator.windowControlsOverlay erreichbar ist. Es tritt nur in installierten Desktop-PWAs auf, die im Web-App-Manifest "display_override": ["window-controls-overlay"] angeben. Die App darf dann den Bereich der Titelleiste selbst gestalten, während das Betriebssystem nur noch die Fenster-Steuerelemente (Minimieren, Maximieren, Schließen) einblendet.

Ausgelöst wird das Ereignis, wenn sich die Fenstergröße ändert, der Nutzer das Overlay ein- oder ausschaltet (Schalter in der Titelleiste) oder sich die Lage der Steuerelemente ändert. Der Handler bekommt ein WindowControlsOverlayGeometryChangeEvent mit den Eigenschaften titlebarAreaRect (ein DOMRect des frei nutzbaren Titelbereichs) und visible (ob das Overlay gerade aktiv ist).

Typische Anwendungen sind: eigene Suchleisten oder Tabs in der Titelleiste neu anordnen, Layout zwischen „Overlay an“ und „Overlay aus“ umschalten oder Messwerte an JavaScript-gestützte Layouts weitergeben. Für reines Layout reichen oft die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) und env(titlebar-area-height); das Ereignis braucht man, wenn JavaScript reagieren soll.

Registrieren lässt sich der Handler per addEventListener("geometrychange", …) oder über die Eigenschaft navigator.windowControlsOverlay.ongeometrychange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"geometrychange"`.
$handler Pflicht	(event: WindowControlsOverlayGeometryChangeEvent) => void		Callback; erhält ein Ereignisobjekt mit `titlebarAreaRect` (`DOMRect`) und `visible` (`boolean`).
$options	boolean\|AddEventListenerOptions	false	Übliche Listener-Optionen wie `once`, `passive` oder `signal`.

Beispiele

Titelleisten-Geometrie per addEventListener verfolgen

// Funktioniert nur in einer installierten PWA mit display_override: ["window-controls-overlay"]
if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', (event) => {
    const { x, y, width, height } = event.titlebarAreaRect;
    console.log(`Overlay sichtbar: ${event.visible}`);
    console.log(`Titelbereich: x=${x}, y=${y}, ${width}×${height}px`);
  });
}

Overlay sichtbar: true Titelbereich: x=0, y=0, 1100×33px

Layout umschalten mit ongeometrychange und Entprellung

const header = document.querySelector('#app-header');
let timer;

const applyLayout = ({ visible, titlebarAreaRect }) => {
  header.classList.toggle('in-titlebar', visible);
  // Suchfeld an verfügbare Breite anpassen
  header.style.setProperty('--search-width', `${Math.max(titlebarAreaRect.width - 200, 120)}px`);
};

const wco = navigator.windowControlsOverlay;
if (wco) {
  // Initialzustand setzen – das Ereignis feuert nicht beim Laden
  applyLayout({ visible: wco.visible, titlebarAreaRect: wco.getTitlebarAreaRect() });

  wco.ongeometrychange = (event) => {
    clearTimeout(timer);
    timer = setTimeout(() => applyLayout(event), 100);
  };
}

Listener wieder entfernen

const controller = new AbortController();

navigator.windowControlsOverlay?.addEventListener(
  'geometrychange',
  (e) => console.log('Neue Breite:', e.titlebarAreaRect.width),
  { signal: controller.signal }
);

// Später, z. B. beim Verlassen einer Ansicht:
controller.abort(); // entspricht removeEventListener
// Alternativ bei on-Property:
// navigator.windowControlsOverlay.ongeometrychange = null;

Neue Breite: 980

// Wichtig · Fallstricke

Kompatibilität: Nur in Chromium-basierten Browsern (Chrome, Edge) auf Desktop-Systemen und nur in installierten PWAs mit display_override: ["window-controls-overlay"]. In normalen Browser-Tabs, Firefox und Safari ist navigator.windowControlsOverlay undefined – immer per Feature-Erkennung prüfen.
Das Ereignis wird nicht beim Seitenladen ausgelöst. Den Anfangszustand über navigator.windowControlsOverlay.visible und getTitlebarAreaRect() ermitteln.
Beim Ziehen der Fenstergröße kann es sehr häufig feuern – aufwendige Arbeit entprellen oder per requestAnimationFrame bündeln.
Ist das Overlay ausgeblendet (visible === false), hat titlebarAreaRect die Größe 0.
Eigene Elemente in der Titelleiste brauchen -webkit-app-region: drag bzw. no-drag für interaktive Teile, sonst lässt sich das Fenster nicht verschieben oder Buttons sind nicht klickbar.
Für reines Layout sind die CSS-Variablen env(titlebar-area-*) meist performanter als JavaScript.

Siehe auch

CaptureController: zoomlevelchange VirtualKeyboard: geometrychange Window: vrdisplaypresentchange Window: languagechange Window: orientationchange