Diese Seite wurde von der Cloud Translation API übersetzt.

Vollständige Kontrolle über die VirtualKeyboard API

Thomas Steiner

Browser Support

Geräte wie Tablets oder Smartphones haben in der Regel eine virtuelle Tastatur zum Eingeben von Text. Im Gegensatz zu einer physischen Tastatur, die immer vorhanden und immer gleich ist, wird eine virtuelle Tastatur je nach Nutzeraktionen ein- und ausgeblendet. Sie kann sich auch dynamisch anpassen, z. B. basierend auf dem Attribut inputmode.

Diese Flexibilität hat jedoch den Nachteil, dass die Layout-Engine des Browsers über das Vorhandensein der virtuellen Tastatur informiert werden muss und das Layout des Dokuments möglicherweise angepasst werden muss. Beispiel: Ein Eingabefeld, in das der Nutzer gerade etwas eingeben möchte, wird möglicherweise von der virtuellen Tastatur verdeckt. Der Browser muss es dann in den sichtbaren Bereich scrollen.

Bisher haben Browser diese Herausforderung selbst bewältigt, aber komplexere Anwendungen erfordern möglicherweise mehr Kontrolle über das Verhalten des Browsers. Ein Beispiel sind Mobilgeräte mit mehreren Bildschirmen, bei denen der herkömmliche Ansatz zu „verschwendetem“ Platz auf dem Bildschirm führen würde, wenn die virtuelle Tastatur nur auf einem Bildschirmsegment angezeigt wird, der verfügbare Viewport aber trotzdem auf beiden Bildschirmen verkleinert wird. Das Bild unten zeigt, wie die VirtualKeyboard API verwendet werden kann, um das Layout des Dokuments dynamisch zu optimieren und die Darstellung der virtuellen Tastatur zu berücksichtigen.

Der traditionelle Ansatz führt zu

In solchen Situationen ist die VirtualKeyboard API hilfreich. Sie besteht aus drei Teilen:

Die VirtualKeyboard-Schnittstelle für das navigator-Objekt für den programmatischen Zugriff auf die virtuelle Tastatur über JavaScript.
Eine Reihe von CSS-Umgebungsvariablen, die Informationen zum Erscheinungsbild der virtuellen Tastatur liefern.
Eine Richtlinie für die Bildschirmtastatur, die bestimmt, ob die Bildschirmtastatur angezeigt werden soll.

Aktueller Status

Die VirtualKeyboard API ist ab Chromium 94 auf Computern und Mobilgeräten verfügbar.

Funktionserkennung und Browserunterstützung

Mit dem folgenden Snippet können Sie erkennen, ob die VirtualKeyboard API im aktuellen Browser unterstützt wird:

if ('virtualKeyboard' in navigator) {
  // The VirtualKeyboard API is supported!
}

VirtualKeyboard API verwenden

Die VirtualKeyboard API fügt dem navigator-Objekt eine neue Schnittstelle VirtualKeyboard hinzu.

Neues Verhalten der Bildschirmtastatur aktivieren

Damit der Browser weiß, dass Sie sich selbst um die Verdeckung durch die virtuelle Tastatur kümmern, müssen Sie zuerst das neue Verhalten der virtuellen Tastatur aktivieren, indem Sie die boolesche Eigenschaft overlaysContent auf true setzen.

navigator.virtualKeyboard.overlaysContent = true;

Bildschirmtastatur ein- und ausblenden

Sie können die virtuelle Tastatur programmgesteuert einblenden, indem Sie ihre show()-Methode aufrufen. Damit das funktioniert, muss das fokussierte Element ein Formularsteuerelement (z. B. ein textarea-Element) oder ein Bearbeitungs-Host sein (z. B. durch Verwendung des Attributs contenteditable). Die Methode gibt immer undefined zurück, löst aber ein geometrychange-Ereignis aus, wenn die Bildschirmtastatur zuvor nicht angezeigt wurde.

navigator.virtualKeyboard.show();

Rufen Sie zum Ausblenden der virtuellen Tastatur die Methode hide() auf. Die Methode gibt immer undefined zurück, löst aber ein geometrychange-Ereignis aus, wenn die Bildschirmtastatur zuvor angezeigt wurde.

navigator.virtualKeyboard.hide();

Aktuelle Geometrie abrufen

Die aktuelle Geometrie der virtuellen Tastatur können Sie über die boundingRect-Eigenschaft abrufen. Sie stellt die aktuellen Abmessungen der virtuellen Tastatur als DOMRect-Objekt zur Verfügung. Der Einzug entspricht den Eigenschaften „top“, „right“, „bottom“ und/oder „left“.

const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);

Über Geometrieänderungen informiert werden

Immer wenn die Bildschirmtastatur angezeigt oder ausgeblendet wird, wird das geometrychange-Ereignis ausgelöst. Die target-Eigenschaft des Ereignisses enthält das virtualKeyboard-Objekt, das (wie oben beschrieben) die neue Geometrie des virtuellen Tastatureinsatzes als DOMRect enthält.

navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
  const { x, y, width, height } = event.target.boundingRect;
  console.log('Virtual keyboard geometry changed:', x, y, width, height);
});

Umgebungsvariablen für CSS

Die VirtualKeyboard API stellt eine Reihe von CSS-Umgebungsvariablen zur Verfügung, die Informationen zum Erscheinungsbild der virtuellen Tastatur liefern. Sie werden ähnlich wie die CSS-Property inset modelliert, d. h. entsprechend den Properties „top“, „right“, „bottom“ und/oder „left“.

keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height

Die Insets der Bildschirmtastatur sind sechs Umgebungsvariablen, die ein Rechteck durch seine oberen, rechten, unteren und linken Insets vom Rand des Darstellungsbereichs definieren. Die Insets für Breite und Höhe werden aus den anderen Insets berechnet, um die Entwicklerfreundlichkeit zu erhöhen. Der Standardwert für jeden Tastatureinsatz ist 0px, wenn kein Fallback-Wert angegeben ist.

Normalerweise verwenden Sie die Umgebungsvariablen wie im folgenden Beispiel:

.some-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the fallback value of `50px`.
   */
  margin-block-end: env(keyboard-inset-height, 50px);
}

.some-other-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the default fallback value of `0px`.
   */
  margin-block-end: env(keyboard-inset-height);
}

Richtlinie zur Bildschirmtastatur

Manchmal sollte die Bildschirmtastatur nicht angezeigt werden, wenn ein bearbeitbares Element fokussiert ist. Ein Beispiel ist eine Tabellenkalkulationsanwendung, in der der Nutzer auf eine Zelle tippen kann, damit ihr Wert in eine Formel einer anderen Zelle aufgenommen wird. virtualkeyboardpolicy ist ein Attribut, dessen Keywords die Strings auto und manual sind. Wenn contenteditable für ein Element angegeben wird, das ein auto-Host ist, wird bei Fokussierung oder Tippen auf das entsprechende bearbeitbare Element automatisch die virtuelle Tastatur angezeigt. Mit manual werden Fokus und Tippen auf das bearbeitbare Element von Änderungen am aktuellen Status der virtuellen Tastatur entkoppelt.

<!-- Do nothing on regular focus, but show the virtual keyboard on double-click. -->
<div
  contenteditable
  virtualkeyboardpolicy="manual"
  inputmode="text"
  ondblclick="navigator.virtualKeyboard.show();"
>
  Double-click to edit.
</div>

Demo

Hier finden Sie eine Demo auf Glitch, in der die VirtualKeyboard API in Aktion zu sehen ist. Sehen Sie sich den Quellcode an, um zu erfahren, wie er implementiert wird. geometrychange-Ereignisse können zwar in der iFrame-Einbettung beobachtet werden, das tatsächliche Verhalten der virtuellen Tastatur erfordert jedoch, dass die Demo in einem eigenen Browser-Tab geöffnet wird.

Nützliche Links

Danksagungen

Die VirtualKeyboard API wurde von Anupam Snigdha von Microsoft spezifiziert. Der ehemalige Editor Grisha Lyukshin, ebenfalls von Microsoft, hat dazu beigetragen.