VirtualKeyboard — Schnittstelle · JavaScript-Referenz

Signatur

interface VirtualKeyboard extends EventTarget

Beschreibung

Die Schnittstelle VirtualKeyboard gehört zur VirtualKeyboard API. Man erreicht sie über navigator.virtualKeyboard. Sie ist für Geräte ohne Hardwaretastatur gedacht, etwa Tablets, Smartphones oder Kiosk-Terminals. Normalerweise verkleinert oder verschiebt der Browser beim Einblenden der Bildschirmtastatur den sichtbaren Bereich (Viewport). Mit dieser Schnittstelle übernimmt die Webanwendung diese Aufgabe selbst.

Die wichtigsten Mitglieder:

overlaysContent (boolean): Bei true legt sich die Tastatur über den Inhalt, und der Browser passt den Viewport nicht mehr an. Die Seite ist dann selbst für das Layout zuständig.
boundingRect (DOMRect, nur lesbar): Position und Größe der Tastatur. Sinnvolle Werte gibt es nur, wenn overlaysContent auf true steht.
show() / hide(): Blendet die Tastatur per Skript ein oder aus. Das wirkt nur, wenn das fokussierte Element das Attribut virtualkeyboardpolicy="manual" hat.
Event geometrychange: Wird ausgelöst, wenn sich die Tastaturgeometrie ändert, also beim Ein- oder Ausblenden. Man registriert es mit addEventListener("geometrychange", …) oder über die Eigenschaft ongeometrychange.

Wenn overlaysContent aktiv ist, stellt der Browser außerdem die CSS-Umgebungsvariablen keyboard-inset-top, keyboard-inset-right, keyboard-inset-bottom, keyboard-inset-left, keyboard-inset-width und keyboard-inset-height bereit. So lässt sich das Layout mit env() rein in CSS anpassen, zum Beispiel für eine Chat-Eingabeleiste, die direkt über der Tastatur bleiben soll.

Die API ist nur in sicheren Kontexten (HTTPS) verfügbar und kann nur im obersten Browsing-Kontext genutzt werden, nicht in iframes.

Rückgabewert

Typ

VirtualKeyboard

Beschreibung

Die Instanz wird nicht über einen Konstruktor erzeugt, sondern über navigator.virtualKeyboard abgerufen. In Browsern ohne Unterstützung ist der Wert undefined.

Beispiele

Unterstützung prüfen und Layout-Steuerung übernehmen

if ('virtualKeyboard' in navigator) {
  // Browser soll den Viewport nicht mehr automatisch anpassen
  navigator.virtualKeyboard.overlaysContent = true;
  console.log('overlaysContent:', navigator.virtualKeyboard.overlaysContent);
} else {
  console.log('VirtualKeyboard API nicht verfügbar');
}

overlaysContent: true

Chat-Eingabeleiste über der Tastatur halten (geometrychange)

const vk = navigator.virtualKeyboard;
const inputBar = document.querySelector('#chat-input');

if (vk) {
  vk.overlaysContent = true;

  const onGeometryChange = (event) => {
    const { x, y, width, height } = event.target.boundingRect;
    console.log(`Tastatur: ${width}x${height} bei (${x}, ${y})`);
    inputBar.style.marginBottom = `${height}px`;
  };

  vk.addEventListener('geometrychange', onGeometryChange);

  // Später wieder abmelden, z. B. beim Verlassen der Ansicht
  // vk.removeEventListener('geometrychange', onGeometryChange);
}

Tastatur: 412x280 bei (0, 635)

Tastatur manuell ein- und ausblenden

// HTML: <div id="editor" contenteditable virtualkeyboardpolicy="manual"></div>
//       <button id="kb-toggle">Tastatur</button>
const editor = document.querySelector('#editor');
const toggle = document.querySelector('#kb-toggle');
let visible = false;

toggle.addEventListener('click', () => {
  editor.focus();
  if (visible) {
    navigator.virtualKeyboard.hide();
  } else {
    navigator.virtualKeyboard.show();
  }
  visible = !visible;
});

// Alternativ per on-Property
navigator.virtualKeyboard.ongeometrychange = (e) => {
  visible = e.target.boundingRect.height > 0;
};

Layout rein per CSS mit env()-Variablen

navigator.virtualKeyboard.overlaysContent = true;

const style = document.createElement('style');
style.textContent = `
  .toolbar {
    position: fixed;
    left: 0;
    right: 0;
    bottom: env(keyboard-inset-height, 0px);
  }
`;
document.head.append(style);

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Chrome, Edge und Opera unterstützen die API ab Version 94. Firefox und Safari (auch unter iOS) unterstützen sie nicht. Deshalb immer mit 'virtualKeyboard' in navigator prüfen und eine Alternative vorsehen, etwa window.visualViewport mit dem resize-Event.
show() und hide() wirken nur, wenn das fokussierte Element virtualkeyboardpolicy="manual" gesetzt hat. show() braucht außerdem eine Nutzeraktion (transiente Aktivierung), etwa einen Klick.
boundingRect und die keyboard-inset-*-Variablen liefern nur dann echte Werte, wenn overlaysContent = true gesetzt ist. Andernfalls sind sie 0.
Mit overlaysContent = true kann die Tastatur Eingabefelder verdecken. Das Layout muss also selbst angepasst werden, sonst leidet die Bedienbarkeit.
Die API gibt es nur in sicheren Kontexten (HTTPS) und im obersten Dokument. In iframes steht sie nicht zur Verfügung.
Auf Desktop-Geräten mit Hardwaretastatur wird geometrychange in der Regel nie ausgelöst.

Siehe auch

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