VirtualKeyboard: geometrychange — Ereignis · JavaScript-Referenz

Signatur

navigator.virtualKeyboard.addEventListener("geometrychange", handler)

Beschreibung

Das Ereignis geometrychange gehört zum Interface VirtualKeyboard, das Sie über navigator.virtualKeyboard erreichen. Der Browser löst es aus, sobald sich die Fläche ändert, die die Bildschirmtastatur einnimmt. Das passiert typischerweise, wenn die Tastatur erscheint oder verschwindet, aber auch, wenn sie ihre Größe wechselt, etwa beim Drehen des Geräts.

Wirklich nützlich ist das Ereignis erst, wenn Sie navigator.virtualKeyboard.overlaysContent = true setzen. Dann verkleinert der Browser den Viewport nicht mehr automatisch, sondern legt die Tastatur über den Inhalt. Ihre Seite ist damit selbst für das Layout zuständig. Mit geometrychange und der Eigenschaft navigator.virtualKeyboard.boundingRect (ein DOMRect) erfahren Sie, wo die Tastatur liegt und wie groß sie ist. So können Sie zum Beispiel Eingabeleisten, Chat-Fenster oder schwebende Bedienelemente passend verschieben.

Das Ereignisobjekt ist ein einfaches Event ohne zusätzliche Eigenschaften. Die Geometrie lesen Sie über event.target.boundingRect aus. Ist die Tastatur ausgeblendet, sind Breite und Höhe dieses Rechtecks 0. Einen Handler registrieren Sie entweder mit addEventListener("geometrychange", …) oder über die Eigenschaft navigator.virtualKeyboard.ongeometrychange.

Wenn Sie das Layout nur mit CSS anpassen wollen, brauchen Sie oft gar kein JavaScript: Die Umgebungsvariablen env(keyboard-inset-top), env(keyboard-inset-height) und weitere stellen dieselben Werte direkt in CSS bereit. Auch sie wirken nur, wenn overlaysContent aktiv ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses: `"geometrychange"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die bei jeder Änderung der Tastatur-Geometrie aufgerufen wird. `event.target` ist das `VirtualKeyboard`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Beispiele

Geometrie der Tastatur mit addEventListener protokollieren

if ('virtualKeyboard' in navigator) {
  // Tastatur überlagert den Inhalt, das Layout steuern wir selbst
  navigator.virtualKeyboard.overlaysContent = true;

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

Tastatur sichtbar: { x: 0, y: 512, width: 412, height: 303 } Tastatur ausgeblendet: { x: 0, y: 0, width: 0, height: 0 }

Chat-Eingabeleiste oberhalb der Tastatur halten (on-Property)

const eingabeLeiste = document.querySelector('#chat-eingabe');

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

  vk.ongeometrychange = () => {
    const { height } = vk.boundingRect;
    // Leiste um die Tastaturhöhe nach oben schieben
    eingabeLeiste.style.transform = `translateY(-${height}px)`;
  };
}

Listener per AbortController wieder entfernen

const controller = new AbortController();

const onGeometryChange = () => {
  const { height } = navigator.virtualKeyboard.boundingRect;
  document.body.classList.toggle('tastatur-offen', height > 0);
};

if ('virtualKeyboard' in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
  navigator.virtualKeyboard.addEventListener('geometrychange', onGeometryChange, {
    signal: controller.signal
  });
}

// Später, z. B. beim Verlassen der Chat-Ansicht:
const aufraeumen = () => {
  controller.abort();
  // Alternativ: navigator.virtualKeyboard.removeEventListener('geometrychange', onGeometryChange);
  navigator.virtualKeyboard.overlaysContent = false;
};

Alternative ohne JavaScript-Layout: CSS-Umgebungsvariablen

// JavaScript aktiviert nur den Overlay-Modus
if ('virtualKeyboard' in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
}

// Passendes CSS (z. B. in einer Stylesheet-Datei):
const css = `
  #chat-eingabe {
    position: fixed;
    bottom: env(keyboard-inset-height, 0px);
  }
`;
const style = document.createElement('style');
style.textContent = css;
document.head.append(style);

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die VirtualKeyboard API gibt es nur in Chromium-Browsern (ab Chrome/Edge 94), und dort vor allem auf Android bzw. Geräten mit Bildschirmtastatur. Firefox und Safari (auch iOS) unterstützen sie nicht. Prüfen Sie die Unterstützung immer mit 'virtualKeyboard' in navigator. Als Ersatz eignet sich die visualViewport-API mit ihrem resize-Ereignis.
Nur in sicheren Kontexten: Die API steht nur unter HTTPS bzw. auf localhost zur Verfügung.
Ohne overlaysContent = true verkleinert der Browser den Viewport selbst. Das Ereignis kann trotzdem feuern, Sie müssen dann aber meist nichts selbst anpassen. Rechnen Sie Layout-Korrekturen nicht doppelt.
Das Ereignisobjekt enthält keine Geometriedaten. Lesen Sie immer navigator.virtualKeyboard.boundingRect aus. Ist die Tastatur ausgeblendet, ist das Rechteck 0×0.
Leistung: Während Animationen kann das Ereignis mehrmals kurz hintereinander feuern. Ändern Sie im Handler bevorzugt transform oder CSS-Variablen, damit der Browser das Layout nicht jedes Mal neu berechnen muss.
Nicht mit der Sichtbarkeit verwechseln: Mit show() und hide() steuern Sie die Tastatur nur, wenn das fokussierte Element virtualkeyboardpolicy="manual" hat. Das Ereignis meldet dagegen jede Änderung, egal wodurch sie ausgelöst wurde.

Siehe auch

VirtualKeyboard VirtualKeyboard.boundingRect VirtualKeyboard.overlaysContent VirtualKeyboard.show() VirtualKeyboard.hide() VisualViewport: resize EventTarget.addEventListener()