WindowControlsOverlayGeometryChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface WindowControlsOverlayGeometryChangeEvent extends Event

Beschreibung

WindowControlsOverlayGeometryChangeEvent gehört zur Window Controls Overlay API. Installierte Desktop-Progressive-Web-Apps, die im Manifest "display_override": ["window-controls-overlay"] angeben, können damit den Bereich der Titelleiste selbst nutzen. Das Betriebssystem zeichnet nur noch die Fenstersteuerungen (Minimieren, Maximieren, Schließen) als Überlagerung. Den restlichen Platz füllt die App mit eigenen Inhalten wie Suchfeld, Tabs oder Logo.

Das Ereignis wird am Objekt navigator.windowControlsOverlay ausgelöst, und zwar immer dann, wenn sich die Fenstergröße ändert oder die Person die Überlagerung ein- bzw. ausschaltet. Es hat zwei eigene schreibgeschützte Eigenschaften:

titlebarAreaRect: ein DOMRect mit Position und Größe des Titelleistenbereichs, den die App nutzen darf.
visible: ein boolean, der angibt, ob die Überlagerung gerade sichtbar ist.

Für das reine Layout reichen meistens 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 auf Änderungen reagieren muss, etwa um Menüeinträge je nach verfügbarer Breite auszublenden oder um Analysedaten zu erfassen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"geometrychange"`.
$options Pflicht	Object		Initialisierungsobjekt (erbt von `EventInit`). Enthält `titlebarAreaRect` (`DOMRect`, Pflicht) und `visible` (`boolean`, Standard `false`) sowie optional `bubbles`, `cancelable` und `composed`.

Rückgabewert

Typ

WindowControlsOverlayGeometryChangeEvent

Beschreibung

Das Ereignis-Objekt mit den schreibgeschützten Eigenschaften titlebarAreaRect (DOMRect) und visible (boolean).

Beispiele

Auf Geometrieänderungen per addEventListener reagieren

// Nur in installierten PWAs mit window-controls-overlay verfügbar
if ('windowControlsOverlay' in navigator) {
  const onGeometryChange = (event) => {
    const { x, y, width, height } = event.titlebarAreaRect;
    console.log(`Überlagerung sichtbar: ${event.visible}`);
    console.log(`Titelleiste: x=${x}, y=${y}, ${width}×${height}px`);
  };

  navigator.windowControlsOverlay.addEventListener('geometrychange', onGeometryChange);
}

Überlagerung sichtbar: true Titelleiste: x=0, y=0, 1128×33px

Menü je nach verfügbarer Breite anpassen (entprellt, mit ongeometrychange)

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

const updateMenu = (event) => {
  const menu = document.querySelector('#titlebar-menu');
  if (!menu) return;
  // Kompaktes Menü, wenn der Platz knapp wird oder die Überlagerung aus ist
  const compact = !event.visible || event.titlebarAreaRect.width < 600;
  menu.classList.toggle('compact', compact);
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.ongeometrychange = debounce(updateMenu, 200);
}

Ereignis manuell erzeugen und Listener wieder entfernen

const handler = (e) => console.log(e.type, e.visible, e.titlebarAreaRect.width);

const target = new EventTarget();
target.addEventListener('geometrychange', handler);

// Eigenes Ereignis erzeugen, z. B. für Tests
const evt = new WindowControlsOverlayGeometryChangeEvent('geometrychange', {
  titlebarAreaRect: new DOMRect(0, 0, 800, 32),
  visible: true
});
target.dispatchEvent(evt);

target.removeEventListener('geometrychange', handler);
target.dispatchEvent(evt); // keine Ausgabe mehr

geometrychange true 800

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und nur in Chromium-basierten Desktop-Browsern (Chrome, Edge ab Version 105) vorhanden. Firefox, Safari und mobile Browser unterstützen sie nicht. Prüfe deshalb immer vorher mit 'windowControlsOverlay' in navigator.
Das Ereignis wird nur in einer installierten PWA ausgelöst, deren Manifest "display_override": ["window-controls-overlay"] enthält. Die Seite muss außerdem über einen sicheren Kontext (HTTPS) laufen. In einem normalen Browser-Tab passiert nichts.
Beim Ziehen der Fenstergröße wird geometrychange sehr oft ausgelöst. Rechenintensive Handler solltest du entprellen (Debounce).
Für reines Layout sind die CSS-Variablen env(titlebar-area-*) meist die bessere Wahl, weil sie ohne JavaScript und ohne Verzögerung funktionieren.
Bereiche in der Titelleiste, mit denen man das Fenster verschieben können soll, brauchen app-region: drag. Bedienelemente wie Schaltflächen oder Eingabefelder brauchen dagegen app-region: no-drag, sonst lassen sie sich nicht anklicken.

Siehe auch

Event WindowControlsOverlay NavigationCurrentEntryChangeEvent IDBVersionChangeEvent TaskPriorityChangeEvent