Contrôle total avec l'API VirtualKeyboard

Thomas Steiner

Twitter GitHub Glitch Mastodon Page d'accueil

Navigateurs pris en charge

• 94
• 94
• x
• x

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

Cette flexibilité se fait au prix que le moteur de mise en page du navigateur doit être informé de la présence du clavier virtuel et qu'il doit potentiellement 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 peut être masqué par le clavier virtuel, auquel cas le navigateur doit le faire défiler.

Traditionnellement, les navigateurs ont géré eux-mêmes ce défi, mais les applications plus complexes peuvent nécessiter davantage de contrôle sur le comportement du navigateur. Par exemple, il peut s'agir d'appareils mobiles multi-écrans pour lesquels l'approche traditionnelle générait de l'espace d'écran "gâché" si le clavier virtuel s'affiche sur un seul segment d'écran, mais où la fenêtre d'affichage disponible est tout de même réduite sur les deux écrans. L'image ci-dessous montre comment utiliser l'API VirtualKeyboard pour optimiser la mise en page du document de manière dynamique afin de compenser la présence du clavier virtuel.

C'est dans des situations comme celle-ci que l'API VirtualKeyboard entre en jeu. Elle se compose de trois parties :

• L'interface VirtualKeyboard sur l'objet navigator pour l'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 depuis Chromium 94 sur ordinateur et sur mobile.

Détection de fonctionnalités et prise en charge des 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 de 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 de manière programmatique en appelant sa méthode show(). Pour que cela fonctionne, l'élément sélectionné doit être une commande de formulaire (par exemple, 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 s'affichait précédemment.

navigator.virtualKeyboard.hide();

Obtenir la géométrie actuelle

Pour obtenir la géométrie actuelle du clavier virtuel, consultez la propriété boundingRect. Il expose les dimensions actuelles du clavier virtuel en tant qu'objet DOMRect. L'encart correspond aux propriétés supérieure, droite, inférieure et/ou gauche.

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

Être informé des changements de géométrie

Chaque fois que le clavier virtuel apparaît ou disparaît, l'événement geometrychange est envoyé. 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);
});

Les 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 la même manière que la propriété CSS inset, c'est-à-dire qu'ils correspondent aux propriétés haut, droite, bas et/ou gauche.

• 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 une ergonomie développeur, 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);
}

Règle de clavier virtuel

Il arrive que le clavier virtuel ne s'affiche pas lorsqu'un élément modifiable 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'elle est spécifiée sur un élément qui est un hôte contenteditable, auto entraîne l'affichage automatique du clavier virtuel lorsque l'élément est sélectionné ou appuyé dessus, et manual dissocie le curseur et appuie 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émonstration

Vous pouvez voir l'API VirtualKeyboard en action dans une démonstration sur Glitch. Veillez à parcourir le code source pour voir comment il est mis en œuvre. Bien que les événements geometrychange puissent être observés dans l'intégration iFrame, 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 W3C TAG
• Demande de positionnement en vertu des normes Mozilla
• Demande de position en fonction des normes WebKit

Remerciements

L'API VirtualKeyboard a été spécifiée par Anupam Snigdha de Microsoft, avec des contributions de l'ancienne rédactrice Grisha Lyukshin, ainsi que de Microsoft. Image principale créée par @freestocks sur Unsplash.