Diese Seite wurde von der Cloud Translation API übersetzt.

Vollständige Kontrolle über die VirtualKeyboard API

Thomas Steiner

Twitter GitHub Glitch Mastodon Startseite

Unterstützte Browser

Geräte wie Tablets oder Smartphones verfügen in der Regel über eine Bildschirmtastatur für die Texteingabe. Im Gegensatz zu einer physischen Tastatur, die immer vorhanden und immer gleich ist, wird eine virtuelle Tastatur abhängig von den Aktionen des Nutzers angezeigt und wieder ausgeblendet. Sie kann sich außerdem dynamisch anpassen lassen, z. B. basierend auf dem Attribut inputmode.

Diese Flexibilität hat den Preis, dass die Layout-Engine des Browsers über die Anwesenheit der virtuellen Tastatur informiert werden muss und möglicherweise das Layout des Dokuments anpassen muss, um dies zu kompensieren. Beispielsweise kann ein Eingabefeld, in das der Nutzer eingeben wird, von der virtuellen Tastatur verdeckt werden, sodass der Browser es durch Scrollen sichtbar machen muss.

Traditionell haben Browser diese Herausforderung allein gemeistert, aber komplexere Anwendungen erfordern möglicherweise mehr Kontrolle über das Browserverhalten. Beispiele hierfür sind Mobilgeräte mit mehreren Bildschirmen, bei denen der traditionelle Ansatz „verschwendete“ Bildschirmfläche zur Folge hätte, wenn die Bildschirmtastatur nur auf einem Bildschirmsegment angezeigt würde, der verfügbare Darstellungsbereich aber trotzdem auf beiden Bildschirmen verkleinert wird. Die folgende Abbildung zeigt, wie die VirtualKeyboard API verwendet werden kann, um das Layout des Dokuments dynamisch zu optimieren, um die Präsenz der Bildschirmtastatur auszugleichen.

Der traditionelle Ansatz führt zu

In solchen Situationen kommt die VirtualKeyboard API ins Spiel. 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 zur Darstellung der Bildschirmtastatur liefern.
Eine Richtlinie für virtuelle Tastaturen, die festlegt, ob die Bildschirmtastatur angezeigt werden soll.

Aktueller Status

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

Funktionserkennung und Browserunterstützung

Mit dem folgenden Snippet können Sie feststellen, 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 Objekt navigator die neue Schnittstelle VirtualKeyboard hinzu.

Das neue Verhalten der Bildschirmtastatur aktivieren

Damit der Browser weiß, dass du das Verdecken der virtuellen Tastatur selbst verwaltest, musst du zuerst das neue Verhalten der virtuellen Tastatur aktivieren. Dazu setzt du die boolesche Eigenschaft overlaysContent auf true.

navigator.virtualKeyboard.overlaysContent = true;

Bildschirmtastatur ein- und ausblenden

Sie können die Bildschirmtastatur programmatisch anzeigen, indem Sie ihre show()-Methode aufrufen. Damit das funktioniert, muss das hervorgehobene Element ein Formularsteuerelement (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();

Rufen Sie die Methode hide() auf, um die Bildschirmtastatur auszublenden. Die Methode gibt immer undefined zurück, löst jedoch ein geometrychange-Ereignis aus, wenn zuvor die Bildschirmtastatur angezeigt wurde.

navigator.virtualKeyboard.hide();

Aktuelle Geometrie abrufen

Die aktuelle Geometrie der Bildschirmtastatur findest du in der boundingRect-Eigenschaft. Es stellt die aktuellen Abmessungen der Bildschirmtastatur als DOMRect-Objekt bereit. Die Einfügung 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 sein

Immer wenn die Bildschirmtastatur ein- oder ausgeblendet wird, wird das Ereignis geometrychange ausgelöst. Die Eigenschaft target des Ereignisses enthält das virtualKeyboard-Objekt, das (wie oben erläutert) die neue Geometrie 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 zur Darstellung der Bildschirmtastatur liefern. Sie sind ähnlich modelliert wie die CSS-Eigenschaft inset, 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 Einsätze der virtuellen Tastatur sind sechs Umgebungsvariablen, die ein Rechteck anhand seiner Einsätze oben, rechts, unten und links vom Rand des Darstellungsbereichs definieren. Die Werte für Breite und Höhe werden aus Gründen der Ergonomie der Entwickler aus den anderen Einsätzen berechnet. Der Standardwert für jeden Tastatureinsatz ist 0px, wenn kein Fallback-Wert angegeben ist.

In der Regel 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 hervorgehoben ist. Ein Beispiel ist eine Tabellenkalkulationsanwendung, bei der der Nutzer auf eine Zelle tippen kann, damit ihr Wert in die Formel einer anderen Zelle eingefügt wird. virtualkeyboardpolicy ist ein Attribut, dessen Schlüsselwörter die Strings auto und manual sind. Wird diese Richtlinie für ein Element angegeben, das ein contenteditable-Host ist, auto blendet das entsprechende bearbeitbare Element automatisch die Bildschirmtastatur ein, wenn es fokussiert oder angetippt wird. Außerdem wird manual der Fokus entkoppelt und das bearbeitbare Element wird 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

In einer Demo auf Glitch kannst du dir die VirtualKeyboard API in Aktion ansehen. Sehen Sie sich den Quellcode an, um zu sehen, wie er implementiert wird. Während geometrychange-Ereignisse in der iFrame-Einbettung beobachtet werden können, muss die Demo für das tatsächliche Verhalten der Bildschirmtastatur in einem eigenen Browsertab geöffnet werden.

Nützliche Links

Danksagungen

Die VirtualKeyboard API wurde von Anupam Snigdha von Microsoft mit Beiträgen der ehemaligen Redakteurin Grisha Lyukshin, ebenfalls von Microsoft, spezifiziert. Hero-Image von @freestocks auf Unsplash