new WindowControlsOverlayGeometryChangeEvent() — Methode · JavaScript-Referenz

Signatur

new WindowControlsOverlayGeometryChangeEvent(type, options)

Beschreibung

Der Konstruktor WindowControlsOverlayGeometryChangeEvent() erzeugt ein Ereignisobjekt vom Typ WindowControlsOverlayGeometryChangeEvent. Der Browser löst dieses Ereignis normalerweise selbst als geometrychange auf navigator.windowControlsOverlay aus. Das passiert, wenn sich bei einer installierten Desktop-Progressive-Web-App (PWA) mit Window Controls Overlay die Größe oder Sichtbarkeit des Titelleistenbereichs ändert, etwa weil das Fenster verkleinert wird oder die Nutzerin das Overlay ein- oder ausschaltet.

Den Konstruktor selbst aufzurufen lohnt sich vor allem in Tests und Simulationen. Sie können damit ein künstliches Ereignis mit einer beliebigen DOMRect-Geometrie erzeugen und an Ihre Layout-Logik weitergeben, ohne die App zu installieren oder das Fenster tatsächlich zu verändern. Das Ereignisobjekt stellt die Eigenschaften titlebarAreaRect (ein DOMRect) und visible (ein boolean) bereit.

Das Overlay steht nur zur Verfügung, wenn im Web-App-Manifest "display_override": ["window-controls-overlay"] gesetzt ist und die App als eigenständiges Fenster läuft. In CSS können Sie den Titelleistenbereich alternativ über die Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) und env(titlebar-area-height) ansprechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Der Browser verwendet `"geometrychange"`. Die Groß- und Kleinschreibung wird beachtet.
$options Pflicht	object		Wörterbuch mit Initialisierungswerten. Neben den unten beschriebenen Feldern werden auch die allgemeinen `Event`-Optionen `bubbles`, `cancelable` und `composed` (Standard jeweils `false`) akzeptiert.
$options.titlebarAreaRect Pflicht	DOMRect		Position und Größe des Titelleistenbereichs neben den Fenstersteuerelementen, in CSS-Pixeln. Fehlt dieses Feld, wirft der Konstruktor einen `TypeError`.
$options.visible	boolean	false	Gibt an, ob das Window Controls Overlay sichtbar ist.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

const rect = new DOMRect(0, 0, 820, 33);

const event = new WindowControlsOverlayGeometryChangeEvent('geometrychange', {
  titlebarAreaRect: rect,
  visible: true
});

console.log(event.type);
console.log(event.visible);
console.log(event.titlebarAreaRect.width, event.titlebarAreaRect.height);
console.log(event.isTrusted);

geometrychange true 820 33 false

Auf echte Geometrieänderungen reagieren

const titlebar = document.querySelector('#titlebar');

const updateTitlebar = (event) => {
  const { width, height } = event.titlebarAreaRect;
  titlebar.hidden = !event.visible;
  // Suchfeld nur zeigen, wenn genug Platz vorhanden ist
  titlebar.classList.toggle('compact', width < 400);
  console.log(`Titelleiste: ${width}×${height}, sichtbar: ${event.visible}`);
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', updateTitlebar);
}

Titelleiste: 1180×33, sichtbar: true

Handler ohne installierte PWA testen

// Handler, der in der App an 'geometrychange' hängt
const layoutState = { compact: false, visible: false };
const onGeometryChange = (event) => {
  layoutState.visible = event.visible;
  layoutState.compact = event.titlebarAreaRect.width < 400;
};

// Schmales Fenster simulieren
const fakeEvent = new WindowControlsOverlayGeometryChangeEvent('geometrychange', {
  titlebarAreaRect: new DOMRect(0, 0, 320, 33),
  visible: true
});

onGeometryChange(fakeEvent);
console.log(layoutState);

{ compact: true, visible: true }

// Wichtig · Fallstricke

Experimentell: Die API gibt es nur in Chromium-basierten Desktop-Browsern (Chrome und Edge ab Version 105). Firefox, Safari und mobile Browser unterstützen sie nicht. Prüfen Sie deshalb vorher, ob sie vorhanden ist, z. B. mit 'WindowControlsOverlayGeometryChangeEvent' in window bzw. 'windowControlsOverlay' in navigator.
titlebarAreaRect ist Pflicht. Fehlt das Feld oder ist sein Wert kein DOMRect, wirft der Konstruktor einen TypeError.
Selbst erzeugte Ereignisse haben isTrusted === false und ändern das tatsächliche Fenster-Layout nicht. Sie ändern auch nicht den Rückgabewert von navigator.windowControlsOverlay.getTitlebarAreaRect().
geometrychange kann beim Ändern der Fenstergröße sehr oft ausgelöst werden. Teure Layout-Arbeit sollten Sie deshalb drosseln (Debounce oder requestAnimationFrame).
Ohne "display_override": ["window-controls-overlay"] im Manifest und ohne installierte App löst der Browser das Ereignis nie aus.

Siehe auch

new NavigationCurrentEntryChangeEvent() new IDBVersionChangeEvent() new TaskPriorityChangeEvent() new XRInputSourcesChangeEvent() new ContentVisibilityAutoStateChangeEvent()