Contrôle total avec l'API VirtualKeyboard

Thomas Steiner

Les appareils tels que les tablettes ou les téléphones mobiles disposent généralement d'un clavier virtuel pour saisir du texte. Contrairement à un clavier physique qui est toujours présent et toujours le même, un clavier virtuel apparaît et disparaît en fonction des actions de l'utilisateur, auxquelles il peut également s'adapter de manière dynamique, par exemple en fonction de l'attribut inputmode.

Cette flexibilité a un prix : le moteur de mise en page du navigateur doit être informé de la présence du clavier virtuel et peut avoir besoin d'ajuster la mise en page du document pour compenser. Par exemple, un champ de saisie dans lequel l'utilisateur est sur le point de taper peut être masqué par le clavier virtuel. Le navigateur doit donc le faire défiler pour le rendre visible.

Traditionnellement, les navigateurs gèrent ce problème eux-mêmes, mais les applications plus complexes peuvent nécessiter un contrôle plus précis du comportement du navigateur. Par exemple, sur les appareils mobiles à écrans multiples, l'approche traditionnelle entraînerait un "gaspillage" d'espace à l'écran si le clavier virtuel n'était affiché que sur un seul segment d'écran, mais où la fenêtre d'affichage disponible est néanmoins réduite sur les deux écrans. L'image ci-dessous montre comment l'API VirtualKeyboard peut être utilisée pour optimiser la mise en page du document de manière dynamique afin de compenser la présence du clavier virtuel.

C'est dans ce type de situation que l'API VirtualKeyboard intervient. Elle se compose de trois parties :

• Interface VirtualKeyboard sur l'objet navigator pour l'accès programmatique au clavier virtuel depuis JavaScript.
• Ensemble de variables d'environnement CSS qui fournissent des informations sur l'apparence du clavier virtuel.
• Règle de clavier virtuel qui détermine si le clavier virtuel doit être affiché.

État actuel

L'API VirtualKeyboard est disponible à partir de Chromium 94 sur ordinateur et mobile.

Détection des fonctionnalités et compatibilité avec les navigateurs

Pour détecter si l'API VirtualKeyboard est compatible avec le navigateur actuel, utilisez l'extrait de code suivant :

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

Utiliser l'API VirtualKeyboard

L'API VirtualKeyboard ajoute une nouvelle interface VirtualKeyboard à l'objet navigator.

Activer le nouveau comportement du clavier virtuel

Pour indiquer au navigateur que vous gérez vous-même les occlusions du clavier virtuel, vous devez d'abord activer le nouveau comportement du clavier virtuel en définissant la propriété booléenne overlaysContent sur true.

navigator.virtualKeyboard.overlaysContent = true;

Afficher et masquer le clavier virtuel

Vous pouvez afficher le clavier virtuel par programmation en appelant sa méthode show(). Pour que cela fonctionne, l'élément sélectionné doit être un contrôle de formulaire (tel qu'un élément textarea) ou un hôte d'édition (par exemple, en utilisant l'attribut contenteditable). La méthode renvoie toujours undefined, mais déclenche un événement geometrychange si le clavier virtuel n'était pas affiché auparavant.

navigator.virtualKeyboard.show();

Pour masquer le clavier virtuel, appelez la méthode hide(). La méthode renvoie toujours undefined, mais déclenche un événement geometrychange si le clavier virtuel était affiché auparavant.

navigator.virtualKeyboard.hide();

Obtenir la géométrie actuelle

Vous pouvez obtenir la géométrie actuelle du clavier virtuel en examinant la propriété boundingRect. Il expose les dimensions actuelles du clavier virtuel en tant qu'objet DOMRect. L'encart correspond aux propriétés "top", "right", "bottom" et/ou "left".

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

Être informé des modifications apportées à la géométrie

L'événement geometrychange est déclenché chaque fois que le clavier virtuel apparaît ou disparaît. La propriété target de l'événement contient l'objet virtualKeyboard qui (comme indiqué ci-dessus) contient la nouvelle géométrie de l'encart du clavier virtuel en tant que DOMRect.

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

Variables d'environnement CSS

L'API VirtualKeyboard expose un ensemble de variables d'environnement CSS qui fournissent des informations sur l'apparence du clavier virtuel. Ils sont modélisés de la même manière que la propriété CSS inset, c'est-à-dire qu'ils correspondent aux propriétés "top", "right", "bottom" et/ou "left".

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

Les encarts du clavier virtuel sont six variables d'environnement qui définissent un rectangle par ses encarts supérieur, droit, inférieur et gauche à partir du bord de la fenêtre d'affichage. Les encarts de largeur et de hauteur sont calculés à partir des autres encarts pour faciliter le travail des développeurs. La valeur par défaut de chaque encart de clavier est 0px si aucune valeur de remplacement n'est fournie.

Vous utiliserez généralement les variables d'environnement comme dans l'exemple ci-dessous :

.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);
}

Règlement relatif au clavier virtuel

Il arrive que le clavier virtuel ne doive pas s'afficher lorsqu'un élément modifiable est sélectionné. Par exemple, dans une application de feuille de calcul, l'utilisateur peut appuyer sur une cellule pour que sa valeur soit incluse dans la formule d'une autre cellule. virtualkeyboardpolicy est un attribut dont les mots clés sont les chaînes auto et manual. Lorsqu'il est spécifié sur un élément hôte contenteditable, auto permet à l'élément modifiable correspondant d'afficher automatiquement le clavier virtuel lorsqu'il est sélectionné ou appuyé, et manual dissocie la sélection et l'appui sur l'élément modifiable des modifications de l'état actuel du clavier virtuel.

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

Démo

Vous pouvez voir l'API VirtualKeyboard en action dans une démonstration. N'oubliez pas d'explorer le code source pour voir comment il est implémenté. Bien que les événements geometrychange puissent être observés dans l'iframe intégré, le comportement réel du clavier virtuel nécessite d'ouvrir la démo dans son propre onglet de navigateur.

Liens utiles

• Spécification
• Dépôt
• Entrée ChromeStatus
• Bug Chromium
• Examen du TAG W3C
• Demande de position sur les normes Mozilla
• Demande de positionnement selon les normes WebKit

Remerciements

L'API VirtualKeyboard a été spécifiée par Anupam Snigdha de Microsoft, avec des contributions de l'ancien éditeur Grisha Lyukshin, également de Microsoft.