VirtualKeyboard.boundingRect — Eigenschaft · JavaScript-Referenz

Signatur

get VirtualKeyboard.prototype.boundingRect

Beschreibung

Die Eigenschaft boundingRect der Schnittstelle VirtualKeyboard (erreichbar über navigator.virtualKeyboard) gibt ein DOMRect zurück. Es beschreibt, wo die Bildschirmtastatur liegt und wie groß sie ist. Die Koordinaten beziehen sich auf den Viewport, also das Fenster, in dem die Seite angezeigt wird.

Sinnvolle Werte liefert die Eigenschaft nur, wenn die Seite das Layout selbst steuert, also navigator.virtualKeyboard.overlaysContent = true gesetzt hat. Normalerweise verkleinert der Browser beim Öffnen der Tastatur den sichtbaren Bereich. Mit overlaysContent legt sich die Tastatur dagegen über den Inhalt, und die Seite muss selbst dafür sorgen, dass Eingabefelder, Chat-Leisten oder Werkzeugleisten sichtbar bleiben.

Ist die Tastatur geschlossen, sind x, y, width und height alle 0. Ändert sich die Geometrie, löst navigator.virtualKeyboard das Ereignis geometrychange aus. In diesem Ereignis liest man boundingRect am besten neu aus. Für reines CSS-Layout gibt es außerdem die Umgebungsvariablen env(keyboard-inset-top), env(keyboard-inset-height) usw., die dieselben Werte enthalten.

Rückgabewert

Typ

DOMRect

Beschreibung

Ein schreibgeschütztes DOMRect mit x, y, width, height sowie top, right, bottom und left in CSS-Pixeln, relativ zum Viewport. Bei geschlossener Tastatur sind alle Werte 0.

Beispiele

Tastaturgröße bei jeder Geometrieänderung auslesen

if ('virtualKeyboard' in navigator) {
  // Tastatur soll den Inhalt überlagern, statt den Viewport zu verkleinern
  navigator.virtualKeyboard.overlaysContent = true;

  navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
    const { x, y, width, height } = event.target.boundingRect;
    console.log(`Tastatur: x=${x}, y=${y}, ${width}×${height}`);
  });
} else {
  console.log('VirtualKeyboard-API wird nicht unterstützt');
}

Tastatur: x=0, y=520, 412×300 Tastatur: x=0, y=0, 0×0

Chat-Eingabeleiste über der Tastatur halten

const inputBar = document.querySelector('#chat-input-bar');

if ('virtualKeyboard' in navigator) {
  const vk = navigator.virtualKeyboard;
  vk.overlaysContent = true;

  vk.addEventListener('geometrychange', () => {
    const { height } = vk.boundingRect;
    // Leiste um die Tastaturhöhe nach oben schieben (0 bei geschlossener Tastatur)
    inputBar.style.transform = `translateY(-${height}px)`;
  });
}

Prüfen, ob die Tastatur gerade sichtbar ist

const isKeyboardVisible = () => {
  if (!('virtualKeyboard' in navigator)) return false;
  const rect = navigator.virtualKeyboard.boundingRect;
  return rect.width > 0 && rect.height > 0;
};

document.querySelector('input').addEventListener('focus', () => {
  // Kurz warten, bis die Tastatur eingeblendet ist
  setTimeout(() => console.log('Tastatur sichtbar:', isKeyboardVisible()), 300);
});

Tastatur sichtbar: true

// Wichtig · Fallstricke

Experimentell: Die API gibt es nur in Chromium-Browsern (Chrome und Edge ab Version 94, vor allem unter Android und ChromeOS). Firefox und Safari unterstützen sie nicht. Deshalb vorher mit 'virtualKeyboard' in navigator prüfen, ob sie vorhanden ist.
Nur in sicheren Kontexten (HTTPS) verfügbar.
Ohne overlaysContent = true sind die Werte in der Regel 0. Der Browser passt dann den Viewport selbst an.
Der Wert ist eine Momentaufnahme. Nicht zwischenspeichern, sondern im geometrychange-Ereignis neu auslesen.
Direkt nach focus kann das Rechteck noch leer sein, weil die Tastatur animiert eingeblendet wird. Verlässlicher ist geometrychange.
Für Layouts, die nur CSS brauchen, sind env(keyboard-inset-*) oft einfacher und schneller als JavaScript.
Browserübergreifend lässt sich als Ersatz window.visualViewport mit seinem resize-Ereignis nutzen.

Siehe auch

VirtualKeyboard VirtualKeyboard.overlaysContent VirtualKeyboard.show() VirtualKeyboard.hide() DOMRect VisualViewport