WindowControlsOverlayGeometryChangeEvent.visible — Eigenschaft · JavaScript-Referenz

Signatur

WindowControlsOverlayGeometryChangeEvent.visible

Beschreibung

Die Eigenschaft visible des WindowControlsOverlayGeometryChangeEvent ist schreibgeschützt und liefert einen Booleschen Wert. Er zeigt an, ob das Window Controls Overlay (WCO) zu dem Zeitpunkt sichtbar ist, an dem das Ereignis geometrychange ausgelöst wurde. Das Overlay kann eine auf dem Desktop installierte Progressive Web App (PWA) nutzen, deren Manifest in display_override den Wert "window-controls-overlay" enthält.

Ist das Overlay aktiv, reicht der Inhalt der App bis in die Titelleiste. Die Fenstersteuerungen (Minimieren, Maximieren, Schließen) werden dann über den App-Inhalt gelegt. Die Nutzer können das Overlay über einen Schalter in der Titelleiste ein- und ausschalten. Genau dann wird geometrychange auf navigator.windowControlsOverlay ausgelöst, außerdem bei jeder Größenänderung des Fensters.

Mit visible passen Sie Ihr Layout an. Bei true zeichnen Sie z. B. eine eigene Titelleiste mit Suchfeld oder Tabs. Bei false blenden Sie diese aus, weil der Browser wieder seine Standard-Titelleiste zeigt. Zusammen mit titlebarAreaRect aus demselben Ereignis lässt sich der freie Bereich genau berechnen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Fenstersteuerungs-Overlay sichtbar ist, sonst false.

Beispiele

Sichtbarkeit bei Geometrieänderung protokollieren

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', (event) => {
    console.log(`Overlay sichtbar: ${event.visible}`);
  });
}

Overlay sichtbar: true

Eigene Titelleiste abhängig von visible ein- und ausblenden

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

const updateTitlebar = (visible, rect) => {
  titlebar.hidden = !visible;
  if (visible) {
    titlebar.style.setProperty('--titlebar-width', `${rect.width}px`);
    titlebar.style.setProperty('--titlebar-height', `${rect.height}px`);
  }
};

if ('windowControlsOverlay' in navigator) {
  const wco = navigator.windowControlsOverlay;
  // Anfangszustand setzen
  updateTitlebar(wco.visible, wco.getTitlebarAreaRect());

  wco.addEventListener('geometrychange', (event) => {
    updateTitlebar(event.visible, event.titlebarAreaRect);
  });
}

Mit on-Property und Debouncing (Fenster-Resize)

let timer;

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.ongeometrychange = (event) => {
    clearTimeout(timer);
    timer = setTimeout(() => {
      document.body.classList.toggle('wco-active', event.visible);
      console.log('WCO-Klasse gesetzt:', event.visible);
    }, 100);
  };
}

WCO-Klasse gesetzt: false

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist experimentell und wird nur von Chromium-basierten Desktop-Browsern (Chrome, Edge) unterstützt. Firefox und Safari kennen sie nicht. Prüfen Sie die Unterstützung vorher mit 'windowControlsOverlay' in navigator.
Das Ereignis wird nur in einer installierten PWA ausgelöst, deren Manifest "display_override": ["window-controls-overlay"] enthält. In einem normalen Browser-Tab kommt es nie an.
visible gibt nur den Zustand zum Zeitpunkt des Ereignisses wieder. Den aktuellen Zustand liefert jederzeit navigator.windowControlsOverlay.visible. Beim Laden der Seite wird kein Ereignis ausgelöst, deshalb sollten Sie den Anfangszustand selbst abfragen.
geometrychange kann bei einer Fenstergrößenänderung sehr oft hintereinander ausgelöst werden. Teure Layout-Arbeit sollten Sie daher entprellen (Debouncing).
Ohne JavaScript können Sie auch die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-width) usw. und das Media-Feature display-mode: window-controls-overlay verwenden.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.

Siehe auch

WindowControlsOverlayGeometryChangeEvent WindowControlsOverlayGeometryChangeEvent.titlebarAreaRect WindowControlsOverlay WindowControlsOverlay.visible WindowControlsOverlay.getTitlebarAreaRect()