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 coût : le moteur de mise en page du navigateur doit être informé de la présence du clavier virtuel et doit éventuellement ajuster la mise en page du document pour compenser. Par exemple, un champ de saisie dans lequel l'utilisateur est sur le point de saisir du texte peut être masqué par le clavier virtuel. Le navigateur doit donc le faire défiler pour qu'il soit visible.

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

C'est là que l'API VirtualKeyboard intervient. Elle se compose de trois parties :

• Interface VirtualKeyboard sur l'objet navigator pour un accès programmatique au clavier virtuel à partir de 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 de 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 vous occupez vous-même des 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 de modification (par exemple, à l'aide de l'attribut contenteditable). La méthode renvoie toujours undefined, mais déclenche un événement geometrychange si le clavier virtuel n'était pas affiché précédemment.

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 a déjà été affiché.

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 de géométrie

Chaque fois que le clavier virtuel apparaît ou disparaît, l'événement geometrychange est distribué. 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. Elles sont modélisées de manière similaire à la propriété CSS inset, c'est-à-dire qu'elles 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. Pour des raisons d'ergonomie, les encarts de largeur et de hauteur sont calculés à partir des autres encarts. La valeur par défaut de chaque encart de clavier est 0px si aucune valeur de remplacement n'est fournie.

Vous devez généralement utiliser 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);
}

Stratégie de clavier virtuel

Il arrive que le clavier virtuel ne s'affiche pas lorsqu'un élément éditable est sélectionné. Par exemple, une application de feuille de calcul dans laquelle 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 qui est un hôte contenteditable, auto affiche automatiquement le clavier virtuel sur l'élément éditable correspondant lorsqu'il est sélectionné ou appuyé, et manual dissocie la sélection et l'appui sur l'élément éditable des modifications apportées à 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émo sur Glitch. Veillez à explorer le code source pour voir comment il est implémenté. Bien que les événements geometrychange puissent être observés dans l'intégration d'iFrame, le comportement réel du clavier virtuel nécessite d'ouvrir la démonstration dans son propre onglet de navigateur.

Liens utiles

• Spécification
• Dépôt
• Enregistrement ChromeStatus
• Bug Chromium
• Examen du TAG du W3C
• Demande de position standard Mozilla
• Demande de position standard WebKit

Remerciements

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