Vollständige Kontrolle über die VirtualKeyboard API

Unterstützte Browser

  • Chrome: 94.
  • Edge: 94.
  • Firefox: Nicht unterstützt.
  • Safari: Nicht unterstützt.

Quelle

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 Aktion des Nutzers angezeigt und wieder ausgeblendet. Sie kann sich auch dynamisch anpassen, z. B. basierend auf dem Attribut inputmode.

Diese Flexibilität hat jedoch den Preis, dass das Layout-Engine des Browsers über die Anwesenheit der virtuellen Tastatur informiert werden muss und das Layout des Dokuments möglicherweise entsprechend angepasst werden muss. Beispielsweise kann ein Eingabefeld, in das der Nutzer gerade etwas eingeben möchte, von der virtuellen Tastatur verdeckt werden. In diesem Fall muss der Browser es in den Blickbereich scrollen.

Traditionell haben Browser diese Herausforderung selbst gemeistert. Bei komplexeren Anwendungen ist jedoch möglicherweise mehr Kontrolle über das Verhalten des Browsers erforderlich. Beispiele hierfür sind Mobilgeräte mit mehreren Bildschirmen, bei denen der traditionelle Ansatz zu „verschwendetem“ Bildschirmplatz führen würde, wenn die virtuelle Tastatur nur auf einem Bildschirmsegment angezeigt wird, der verfügbare Darstellungsbereich aber trotzdem auf beiden Bildschirmen verkleinert wird. Das Bild unten zeigt, wie mit der VirtualKeyboard API das Layout des Dokuments dynamisch optimiert werden kann, um die virtuelle Tastatur zu berücksichtigen.

Der traditionelle Ansatz führt zu

In solchen Fällen kommt die VirtualKeyboard API ins Spiel. Sie besteht aus drei Teilen:

  • Die VirtualKeyboard-Schnittstelle des navigator-Objekts 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, mit der festgelegt wird, ob die Bildschirmtastatur angezeigt werden soll.

Aktueller Status

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

Funktionserkennung und Browserunterstützung

Mit dem folgenden Snippet können Sie prüfen, 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 VirtualKeyboard-Schnittstelle hinzu.

Neue Funktion für die Bildschirmtastatur aktivieren

Wenn Sie dem Browser mitteilen möchten, dass Sie die Bildschirmtastaturen selbst verdecken, müssen Sie zuerst das neue Verhalten der Bildschirmtastatur aktivieren. Setzen Sie dazu die boolesche Eigenschaft overlaysContent auf true.

navigator.virtualKeyboard.overlaysContent = true;

Bildschirmtastatur ein- und ausblenden

Sie können die virtuelle Tastatur programmgesteuert anzeigen lassen, indem Sie die Methode show() aufrufen. Dazu muss das fokussierte Element ein Formularkontrollelement (z. B. ein textarea-Element) oder ein Bearbeitungshost sein (z. B. mit dem Attribut 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();

Wenn Sie die virtuelle Tastatur ausblenden möchten, rufen Sie die Methode hide() auf. Die Methode gibt immer undefined zurück, löst aber ein geometrychange-Ereignis aus, wenn die virtuelle Tastatur zuvor angezeigt wurde.

navigator.virtualKeyboard.hide();

Aktuelle Geometrie abrufen

Die aktuelle Geometrie der virtuellen Tastatur finden Sie in der Property boundingRect. Die aktuellen Abmessungen der Bildschirmtastatur werden als DOMRect-Objekt angezeigt. Der Einzug entspricht den Eigenschaften „oben“, „rechts“, „unten“ und/oder „links“.

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

Über Geometrieänderungen informiert werden

Jedes Mal, wenn die virtuelle Tastatur angezeigt oder ausgeblendet wird, wird das Ereignis geometrychange gesendet. Die target-Eigenschaft des Ereignisses enthält das virtualKeyboard-Objekt, das wie oben erläutert die neue Geometrie des Einsetzens der Bildschirmtastatur 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);
});

CSS-Umgebungsvariablen

Die VirtualKeyboard API stellt eine Reihe von CSS-Umgebungsvariablen bereit, die Informationen über das Aussehen der Bildschirmtastatur liefern. Sie werden ähnlich wie die CSS-Property inset modelliert, das heißt, sie entsprechen 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 Einzüge der virtuellen Tastatur sind sechs Umgebungsvariablen, die ein Rechteck durch die Einzüge oben, rechts, unten und links vom Rand des Darstellungsbereichs definieren. Die Einzüge für Breite und Höhe werden aus den anderen Einzügen für die Ergonomie der Entwickler berechnet. Der Standardwert für jeden Tastatur-Einschnitt 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 für die Bildschirmtastatur

Manchmal sollte die virtuelle Tastatur nicht angezeigt werden, wenn ein bearbeitbares Element den Fokus hat. Ein Beispiel ist eine Tabellenanwendung, in der Nutzer auf eine Zelle tippen können, damit ihr Wert in die Formel einer anderen Zelle aufgenommen wird. virtualkeyboardpolicy ist ein Attribut, dessen Schlüsselwörter die Strings auto und manual sind. Wenn auto für ein Element angegeben wird, das ein contenteditable-Host ist, wird die virtuelle Tastatur automatisch angezeigt, wenn das entsprechende bearbeitbare Element den Fokus erhält oder angetippt wird. manual trennt den Fokus und das Tippen auf das bearbeitbare Element von Änderungen am aktuellen Status der virtuellen Tastatur.

<!-- 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

In einer Demo auf Glitch können Sie sich die VirtualKeyboard API in Aktion ansehen. Sehen Sie sich den Quellcode an, um zu sehen, wie er implementiert ist. geometrychange-Ereignisse können im iframe-Embed beobachtet werden, das tatsächliche Verhalten der virtuellen Tastatur erfordert jedoch, dass die Demo in einem eigenen Browsertab geöffnet wird.

Danksagungen

Die VirtualKeyboard API wurde von Anupam Snigdha von Microsoft mit Beiträgen des ehemaligen Redakteurs Grisha Lyukshin, ebenfalls von Microsoft, spezifiziert.