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, éventuellement, doit ajuster la mise en page du document en conséquence. 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'objetnavigator
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 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 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 de manière programmatique 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é 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 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 consultant 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 déclenché. 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 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. Les marges intérieures de largeur et de hauteur sont calculées à partir des autres marges intérieures pour l'ergonomie 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ègle concernant le 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 contenteditable
hôte, auto
l'élément modifiable correspondant affiche 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 changements d'é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
- Entrée ChromeStatus
- Bug Chromium
- Examen du TAG du W3C
- Demande de position selon les normes Mozilla
- Demande de position des normes 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.