Diese Seite wurde von der Cloud Translation API übersetzt.

Vollständige Kontrolle über die VirtualKeyboard API

Thomas Steiner

Unterstützte Browser

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 die 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 Browserverhalten 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 enthalten.
Eine Richtlinie für die Bildschirmtastatur, die festlegt, 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 Schnittstelle VirtualKeyboard hinzu.

Neues Verhalten der Bildschirmtastatur aktivieren

Wenn Sie dem Browser mitteilen möchten, dass Sie die Blockierung der virtuellen Tastatur selbst übernehmen, müssen Sie zuerst das neue Verhalten der virtuellen Tastatur aktivieren, indem Sie die boolesche Eigenschaft overlaysContent auf true festlegen.

navigator.virtualKeyboard.overlaysContent = true;

Bildschirmtastatur ein- und ausblenden

Sie können die virtuelle Tastatur programmgesteuert anzeigen lassen, indem Sie die show()-Methode 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 virtuelle Tastatur 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 virtuellen Tastatur werden als DOMRect-Objekt freigegeben. 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);

Benachrichtigungen über Änderungen an der Geometrie

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 virtuellen Tastatur-Eintrags 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 zum Erscheinungsbild der virtuellen Tastatur enthalten. Sie sind ähnlich wie die CSS-Property inset modelliert, d. h. 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-Inset 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 Keywords 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.

Nützliche Links

Danksagungen

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