Navigator.virtualKeyboard — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.virtualKeyboard

Beschreibung

navigator.virtualKeyboard ist der Einstiegspunkt in die VirtualKeyboard API. Das zurückgegebene VirtualKeyboard-Objekt ermöglicht es Webanwendungen, auf Geräten mit Bildschirmtastatur (Tablets, Smartphones, Touch-Laptops) selbst zu bestimmen, wie das Layout auf das Ein- und Ausblenden der Tastatur reagiert.

Normalerweise verkleinert der Browser den sichtbaren Bereich (Viewport), sobald die Bildschirmtastatur erscheint. Setzt man navigator.virtualKeyboard.overlaysContent = true, schaltet man dieses Verhalten ab: Die Tastatur legt sich über den Inhalt, und die Seite kann ihr Layout selbst anpassen – etwa über das Ereignis geometrychange, die Eigenschaft boundingRect oder die CSS-Umgebungsvariablen env(keyboard-inset-height) und Verwandte.

Außerdem bietet das Objekt die Methoden show() und hide(), um die Tastatur für Elemente mit dem Attribut virtualkeyboardpolicy="manual" gezielt ein- oder auszublenden. Das ist praktisch für Editoren, Chat-Oberflächen oder Spiele, in denen die Tastatur nicht bei jedem Fokus automatisch aufgehen soll.

Die Eigenschaft ist schreibgeschützt und gibt bei jedem Zugriff dieselbe Instanz zurück. Sie steht nur in sicheren Kontexten (HTTPS) zur Verfügung.

Rückgabewert

Typ

VirtualKeyboard

Beschreibung

Das VirtualKeyboard-Objekt des aktuellen Dokuments mit overlaysContent, boundingRect, show(), hide() und dem Ereignis geometrychange. In Browsern ohne Unterstützung ist die Eigenschaft nicht vorhanden (undefined).

Beispiele

Unterstützung prüfen und Tastatur überlagern lassen

if ('virtualKeyboard' in navigator) {
  // Viewport nicht mehr automatisch verkleinern
  navigator.virtualKeyboard.overlaysContent = true;
  console.log('VirtualKeyboard API aktiv');
} else {
  console.log('VirtualKeyboard API nicht verfügbar – Standardverhalten bleibt');
}

VirtualKeyboard API aktiv

Layout bei Geometrieänderung anpassen

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

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

  vk.addEventListener('geometrychange', (event) => {
    const { height } = event.target.boundingRect;
    // Eingabeleiste über die Tastatur schieben
    toolbar.style.transform = `translateY(-${height}px)`;
    console.log(`Tastaturhöhe: ${height}px`);
  });
}

Tastaturhöhe: 312px

Tastatur manuell ein- und ausblenden

// HTML: <div id="editor" contenteditable virtualkeyboardpolicy="manual"></div>
const editor = document.querySelector('#editor');
const btn = document.querySelector('#tastatur-umschalten');
let sichtbar = false;

btn.addEventListener('click', () => {
  if (!('virtualKeyboard' in navigator)) return;
  editor.focus();
  if (sichtbar) {
    navigator.virtualKeyboard.hide();
  } else {
    navigator.virtualKeyboard.show();
  }
  sichtbar = !sichtbar;
});

Alternative per CSS-Umgebungsvariablen

navigator.virtualKeyboard.overlaysContent = true;

// CSS kann nun auf die Tastaturgröße reagieren:
const style = document.createElement('style');
style.textContent = `
  #chat-eingabe {
    position: fixed;
    bottom: env(keyboard-inset-height, 0px);
  }
`;
document.head.append(style);

// Wichtig · Fallstricke

Experimentell: Nur in Chromium-Browsern (Chrome, Edge, Opera, ab Version 94) verfügbar. Firefox und Safari unterstützen die API nicht – immer per 'virtualKeyboard' in navigator prüfen und ein sinnvolles Standardverhalten beibehalten.
Nur in sicheren Kontexten (HTTPS bzw. localhost) verfügbar.
show() und hide() wirken nur, wenn das fokussierte Element editierbar ist und virtualkeyboardpolicy="manual" trägt; show() erfordert zudem eine Nutzeraktivierung (z. B. einen Klick).
Nach overlaysContent = true ist die Seite selbst dafür verantwortlich, dass Eingabefelder nicht von der Tastatur verdeckt werden – sonst leidet die Bedienbarkeit.
Auf Geräten ohne Bildschirmtastatur (klassischer Desktop) ist boundingRect leer (alle Werte 0) und geometrychange wird nie ausgelöst.
Die Eigenschaft ist schreibgeschützt; eine Zuweisung an navigator.virtualKeyboard wird ignoriert.

Siehe auch

VirtualKeyboard VirtualKeyboard.overlaysContent VirtualKeyboard.boundingRect VirtualKeyboard.show() VirtualKeyboard.hide() Navigator VisualViewport