HTMLElement.virtualKeyboardPolicy — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.virtualKeyboardPolicy

Beschreibung

Die Eigenschaft virtualKeyboardPolicy spiegelt das HTML-Attribut virtualkeyboardpolicy wider. Sie legt fest, wie sich die Bildschirmtastatur auf Tablets, Smartphones und anderen Touch-Geräten verhält, wenn ein editierbares Element den Fokus bekommt. Das sind z. B. Elemente mit contenteditable, aber auch <input> und <textarea>.

Mögliche Werte:

"auto" – Der Browser blendet die Tastatur wie gewohnt ein, sobald das Element fokussiert oder angetippt wird.
"manual" – Der Browser zeigt die Tastatur nicht automatisch an. Du steuerst sie selbst über navigator.virtualKeyboard.show() und navigator.virtualKeyboard.hide().
"" (leerer String) – Das Attribut ist nicht gesetzt. Der Browser verhält sich dann wie bei "auto".

Sinnvoll ist "manual" bei eigenen Editoren, Spielen oder Zeichen-Apps. Dort soll ein Antippen oft etwas anderes auslösen, etwa eine Textstelle markieren oder ein Objekt verschieben, und die Tastatur soll erst nach einer bewussten Geste erscheinen, z. B. nach einem Doppeltipp oder über einen Button. Die Eigenschaft gehört zur VirtualKeyboard API und wird meist zusammen mit navigator.virtualKeyboard verwendet.

Parameter

Name	Typ	Default	Beschreibung
$value	"auto" \| "manual" \| ""	"" (verhält sich wie "auto")	Neuer Wert beim Setzen der Eigenschaft. Er wird in das Attribut `virtualkeyboardpolicy` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs virtualkeyboardpolicy: "auto", "manual" oder "", wenn das Attribut fehlt.

Beispiele

Tastatur erst nach Doppeltipp anzeigen

// HTML: <div id="editor" contenteditable></div>
const editor = document.getElementById('editor');

if ('virtualKeyboard' in navigator) {
  editor.virtualKeyboardPolicy = 'manual';

  editor.addEventListener('dblclick', () => {
    editor.focus();
    navigator.virtualKeyboard.show();
  });
}

console.log(editor.virtualKeyboardPolicy);

manual

Aktuelle Richtlinie auslesen und Attribut spiegeln

// HTML: <textarea id="notiz" virtualkeyboardpolicy="auto"></textarea>
const notiz = document.getElementById('notiz');

console.log(notiz.virtualKeyboardPolicy);            // aus dem Attribut
notiz.virtualKeyboardPolicy = 'manual';
console.log(notiz.getAttribute('virtualkeyboardpolicy'));

const ohne = document.createElement('div');
console.log(JSON.stringify(ohne.virtualKeyboardPolicy));

auto manual ""

Eigener Button zum Ein- und Ausblenden der Tastatur

// HTML: <div id="feld" contenteditable virtualkeyboardpolicy="manual"></div>
//       <button id="toggle">Tastatur</button>
const feld = document.getElementById('feld');
const toggle = document.getElementById('toggle');
let sichtbar = false;

// Überlagert die Tastatur den Inhalt, liefert boundingRect ihre Größe
navigator.virtualKeyboard?.addEventListener('geometrychange', (e) => {
  sichtbar = e.target.boundingRect.height > 0;
});

toggle.addEventListener('pointerdown', (e) => {
  e.preventDefault(); // Fokus bleibt im Feld
  if (!('virtualKeyboard' in navigator)) return;
  feld.focus();
  sichtbar ? navigator.virtualKeyboard.hide() : navigator.virtualKeyboard.show();
});

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die Eigenschaft gibt es in Chrome und Edge ab Version 94. Firefox und Safari (auch unter iOS) unterstützen sie nicht. Prüfe die Unterstützung vorher, z. B. mit 'virtualKeyboardPolicy' in HTMLElement.prototype oder 'virtualKeyboard' in navigator, und plane ein Verhalten für Browser ohne diese API ein. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung.

Die Richtlinie wirkt nur bei editierbaren Elementen. Bei einem normalen <div> ohne contenteditable hat sie keine Wirkung.
navigator.virtualKeyboard.show() funktioniert nur, wenn das fokussierte Element virtualKeyboardPolicy = "manual" hat. Außerdem setzt der Aufruf in der Regel eine Benutzeraktion voraus (transient user activation), also einen Klick oder Tipp. Einfach beim Laden der Seite aufgerufen, passiert nichts.
Mit "manual" kann ein Tippen ins Feld die Tastatur nicht mehr öffnen. Biete deshalb immer einen gut sichtbaren Weg an, sie einzublenden. Sonst können Nutzer auf Touch-Geräten nichts eingeben (Barrierefreiheit).
Die Eigenschaft ist nicht zu verwechseln mit navigator.virtualKeyboard.overlaysContent. Diese Eigenschaft steuert, ob die Tastatur den Inhalt überlagert oder den sichtbaren Bereich (Viewport) verkleinert.

Siehe auch

TrustedTypePolicyFactory.defaultPolicy HTMLElement.accessKeyLabel HTMLElement.enterKeyHint HTMLElement.autocapitalize HTMLElement.autocorrect