Signatur
Beschreibung
Die Eigenschaft titlebarAreaRect gehört zum Ereignis WindowControlsOverlayGeometryChangeEvent, das am Objekt navigator.windowControlsOverlay als geometrychange ausgelöst wird. Sie liefert ein DOMRect mit dem Bereich der Titelleiste, den die Web-App selbst gestalten darf. Die vom Betriebssystem gezeichneten Fensterschaltflächen (Minimieren, Maximieren, Schließen) gehören nicht dazu.
Nutzbar ist das nur in installierten Desktop-PWAs, deren Web-App-Manifest "display_override": ["window-controls-overlay"] enthält und bei denen der Nutzer das Overlay aktiviert hat. Ändert sich die Fenstergröße oder wird das Overlay ein- oder ausgeschaltet, feuert das Ereignis. Über titlebarAreaRect lassen sich dann Suchfelder, Tabs oder Menüs exakt in die Titelleiste einpassen.
Die Werte x, y, width und height sind CSS-Pixel relativ zum Viewport. Ist das Overlay nicht sichtbar (siehe event.visible), sind alle Werte 0. Für reine Layout-Anpassungen reichen oft die CSS-Umgebungsvariablen env(titlebar-area-x), env(titlebar-area-width) usw.; die JavaScript-Eigenschaft braucht man, wenn die Logik von der Größe abhängt, z. B. wenn Elemente ein- oder ausgeblendet werden sollen.
Rückgabewert
DOMRect mit x, y, width, height (sowie top, left, right, bottom) des frei nutzbaren Titelleistenbereichs in CSS-Pixeln. Bei nicht sichtbarem Overlay sind alle Werte 0.Beispiele
Geometrieänderung protokollieren
if ('windowControlsOverlay' in navigator) {
navigator.windowControlsOverlay.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.titlebarAreaRect;
console.log(`Overlay sichtbar: ${event.visible}`);
console.log(`Titelleiste: x=${x}, y=${y}, ${width}×${height}px`);
});
}Suchfeld abhängig von der Breite ein- oder ausblenden
const search = document.querySelector('#titlebar-search');
// Nicht bei jedem Resize-Schritt neu rechnen
const debounce = (fn, ms = 100) => {
let t;
return (...args) => {
clearTimeout(t);
t = setTimeout(() => fn(...args), ms);
};
};
const onGeometryChange = debounce((event) => {
const { width } = event.titlebarAreaRect;
// Unter 400px ist in der Titelleiste kein Platz für das Suchfeld
search.hidden = !event.visible || width < 400;
});
navigator.windowControlsOverlay?.addEventListener('geometrychange', onGeometryChange);Startwert per getTitlebarAreaRect() und Ereignis kombinieren
const wco = navigator.windowControlsOverlay;
const header = document.querySelector('header');
const applyRect = (rect) => {
header.style.left = `${rect.x}px`;
header.style.width = `${rect.width}px`;
header.style.height = `${rect.height}px`;
};
if (wco?.visible) {
// Das Ereignis feuert erst bei einer Änderung, deshalb den Startwert direkt abfragen
applyRect(wco.getTitlebarAreaRect());
}
wco?.addEventListener('geometrychange', (e) => applyRect(e.titlebarAreaRect));// Wichtig · Fallstricke
- Kompatibilität: Die Eigenschaft ist experimentell und gibt es nur in Chromium-basierten Browsern (Chrome, Edge ab 105) auf Desktop-Systemen. Firefox und Safari unterstützen sie nicht. Vor der Nutzung immer mit
'windowControlsOverlay' in navigatorprüfen, ob die Funktion vorhanden ist. - Nur verfügbar in installierten PWAs mit
display_override: ["window-controls-overlay"]im Manifest. Im normalen Browser-Tab wird das Ereignis nie ausgelöst. - Das Ereignis feuert nicht beim Laden der Seite. Den Startwert holt man mit
navigator.windowControlsOverlay.getTitlebarAreaRect(). geometrychangekann beim Ändern der Fenstergröße sehr oft feuern. Rechenintensive Logik deshalb verzögern (Debounce) oder mitrequestAnimationFramebündeln.- Ist
event.visiblegleichfalse, sind alle Werte0. Das sollte man nicht als echte Größe auswerten. - Für ziehbare Bereiche braucht man zusätzlich
app-region: drag(bzw.-webkit-app-region) in CSS. Interaktive Elemente solltenno-dragerhalten. - Für reines Styling sind die CSS-Variablen
env(titlebar-area-*)oft einfacher und performanter als JavaScript.