Contrôle total avec l'API VirtualKeyboard

Les appareils tels que les tablettes ou les téléphones portables sont généralement équipés 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 s'adapter dynamiquement, par exemple, en fonction inputmode .

Cette flexibilité a un prix : le moteur de mise en page du navigateur doit être informé 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 le clavier virtuel, de sorte que le navigateur doit le faire défiler pour l'afficher.

Traditionnellement, les navigateurs ont résolu ce problème par eux-mêmes, mais les applications plus complexes peut nécessiter davantage de contrôle sur le comportement du navigateur. Exemples : appareils mobiles multi-écrans alors que l'approche traditionnelle entraînerait un "gaspillage" de l'espace à l'écran si le clavier virtuel s'affiche sur un seul segment d'écran, mais où la fenêtre d'affichage disponible est réduite sur les deux écrans Néanmoins. L'image ci-dessous montre comment l'API VirtualKeyboard pourrait être utilisée pour optimiser la mise en page. du document de manière dynamique pour compenser la présence du clavier virtuel.

L'API VirtualKeyboard entre en jeu dans de telles situations. Elle se compose de trois parties :

• L'interface VirtualKeyboard sur l'objet navigator pour l'accès programmatique à l'instance clavier à partir de JavaScript.
• Un ensemble de variables d'environnement CSS qui fournissent des informations sur les apparence.
• 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éterminer 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 activer d'abord le nouveau comportement du clavier virtuel en définissant la propriété booléenne overlaysContent à 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 (un élément textarea, par exemple) ou un hôte de modification (par exemple, en utilisant 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 se déclenche un événement geometrychange si le clavier virtuel était affiché précédemment.

navigator.virtualKeyboard.hide();

Obtenir la géométrie actuelle

Vous pouvez obtenir la géométrie actuelle du clavier virtuel en consultant la propriété boundingRect. Il expose les dimensions actuelles du clavier virtuel 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 modifications de géométrie

Chaque fois que le clavier virtuel apparaît ou disparaît, l'événement geometrychange est déclenché. La La propriété target de l'événement contient l'objet virtualKeyboard qui (comme mentionné ci-dessus) contient la nouvelle géométrie de l'encart du clavier virtuel sous forme de 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. Leur modélisation est semblable à celle de la propriété CSS inset, c'est-à-dire correspondant aux propriétés "top", "right", "bottom" 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 sa barre supérieure, droite, des encarts bas et gauche à partir du bord de la fenêtre d'affichage. Les encarts de largeur et de hauteur sont calculés des autres encarts pour des raisons d'ergonomie. 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 concernant le clavier virtuel

Parfois, le clavier virtuel ne devrait pas s'afficher lorsqu'un élément modifiable est sélectionné. Par exemple, application de feuille de calcul dans laquelle l’utilisateur peut taper sur une cellule pour que sa valeur soit incluse dans une formule de 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 entraîne la élément modifiable correspondant pour afficher automatiquement le clavier virtuel lorsqu'il est sélectionné ou appuyé, et manual dissocie le focus et l'appui sur l'élément modifiable des modifications dans l'environnement l'état actuel du clavier.

<!-- 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 un demo sur Glitch. N'oubliez pas de consulter les code source pour voir comment il est implémenté. Bien que les événements geometrychange puissent être observés dans l'intégration iFrame, le clavier virtuel réel 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
• Récapitulatif du TAG 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 les contributions de l'ancienne rédactrice en chef Grisha Lyukshin, qui travaille également chez Microsoft. Image héros de @freestocks sur Unsplash.