WindowControlsOverlay.visible — Eigenschaft · JavaScript-Referenz

Signatur

WindowControlsOverlay.visible

Beschreibung

Die Eigenschaft visible des WindowControlsOverlay-Interfaces, das Sie über navigator.windowControlsOverlay erreichen, liefert true, wenn eine installierte Progressive Web App (PWA) gerade im Modus Window Controls Overlay läuft. In diesem Modus entfällt die normale Titelleiste. Der Webinhalt reicht dann bis zum oberen Fensterrand, und nur die Fenstersteuerelemente (Minimieren, Maximieren, Schließen) werden als Overlay über der App angezeigt.

Diesen Wert brauchen Sie, wenn Ihre App eine eigene Titelleiste zeichnet und das Layout davon abhängt, ob das Overlay aktiv ist. Die Nutzerin kann jederzeit zwischen der Standard-Titelleiste und dem Overlay umschalten. Die Eigenschaft sagt Ihnen, welcher Zustand gerade gilt.

Voraussetzung ist, dass das Web-App-Manifest "display_override": ["window-controls-overlay"] enthält und die App als eigenes Fenster installiert ist. In einem normalen Browser-Tab ist visible immer false. Wenn sich der Zustand ändert, löst das Objekt das Ereignis geometrychange aus. Dessen Ereignisobjekt (WindowControlsOverlayGeometryChangeEvent) enthält ebenfalls eine Eigenschaft visible.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Window Controls Overlay sichtbar ist, sonst false.

Beispiele

Sichtbarkeit mit Feature-Erkennung abfragen

const wco = navigator.windowControlsOverlay;

if (wco) {
  console.log(`Overlay sichtbar: ${wco.visible}`);
} else {
  console.log('Window Controls Overlay wird nicht unterstützt');
}

Overlay sichtbar: true

Eigene Titelleiste passend zum Zustand ein- und ausblenden

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

const updateTitlebar = () => {
  const visible = wco?.visible ?? false;
  titlebar.hidden = !visible;
  document.body.classList.toggle('wco-active', visible);
};

updateTitlebar();
// Auf Umschalten durch die Nutzerin oder Größenänderungen reagieren
wco?.addEventListener('geometrychange', updateTitlebar);

Sichtbarkeit und Titelleisten-Bereich gemeinsam auswerten

const wco = navigator.windowControlsOverlay;

wco?.addEventListener('geometrychange', (event) => {
  if (!event.visible) {
    console.log('Standard-Titelleiste aktiv');
    return;
  }
  const { x, width, height } = event.titlebarAreaRect;
  console.log(`Freier Titelbereich: x=${x}, Breite=${width}px, Höhe=${height}px`);
});

Freier Titelbereich: x=0, Breite=1140px, Höhe=33px

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist experimentell und nur in Chromium-Browsern auf dem Desktop verfügbar (Chrome, Edge ab Version 105). Firefox und Safari unterstützen sie nicht, auf Mobilgeräten gibt es sie ebenfalls nicht. Prüfen Sie deshalb immer zuerst mit 'windowControlsOverlay' in navigator, ob die Schnittstelle vorhanden ist.
Nur in installierten PWAs: Ohne display_override mit dem Wert window-controls-overlay im Manifest und ohne Installation als eigenes Fenster ist der Wert immer false.
Schreibgeschützt: Wenn Sie visible einen Wert zuweisen, passiert nichts (im Strict Mode wird ein TypeError ausgelöst). Das Umschalten bleibt der Nutzerin über die Browser-Oberfläche vorbehalten.
Einmaliges Abfragen reicht nicht: Der Zustand kann sich zur Laufzeit ändern. Reagieren Sie deshalb auf geometrychange. Für reine Layout-Anpassungen reichen oft die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) und env(titlebar-area-height) oder die Media Query @media (display-mode: window-controls-overlay).
Bereiche Ihrer eigenen Titelleiste, mit denen das Fenster verschoben werden soll, müssen Sie mit app-region: drag (bzw. -webkit-app-region: drag) markieren.

Siehe auch

IntersectionObserver.trackVisibility Navigator.windowControlsOverlay ShadowRoot.serializable AbortController.signal Window.crossOriginIsolated