Se usó la API de Cloud Translation para traducir esta página.

Control total con la API de VirtualKeyboard

Thomas Steiner

Navegadores compatibles

Los dispositivos como las tablets o los teléfonos celulares suelen tener un teclado virtual para escribir texto. A diferencia de un teclado físico que siempre está presente y es siempre el mismo, un teclado virtual aparece y desaparece, según las acciones del usuario, a las que también se puede adaptar de forma dinámica, por ejemplo, según el atributo inputmode.

Esta flexibilidad tiene el inconveniente de que el motor de diseño del navegador debe informarse de la presencia del teclado virtual y, posiblemente, debe ajustar el diseño del documento para compensarlo. Por ejemplo, el teclado virtual podría ocultar un campo de entrada en el que el usuario está a punto de escribir, por lo que el navegador debe desplazarse para que se vea.

Tradicionalmente, los navegadores han abordado este desafío por su cuenta, pero las aplicaciones más complejas pueden requerir más control sobre el comportamiento del navegador. Entre los ejemplos, se incluyen los dispositivos móviles con varias pantallas, en los que el enfoque tradicional generaría un espacio en pantalla "desperdiciado" si el teclado virtual se muestra en un solo segmento de pantalla, pero en el que el viewport disponible se reduce en ambas pantallas. En la siguiente imagen, se muestra cómo se podría usar la API de VirtualKeyboard para optimizar el diseño del documento de forma dinámica y compensar la presencia del teclado virtual.

El enfoque tradicional genera lo siguiente:

En situaciones como esta, es donde entra en juego la API de VirtualKeyboard. Consta de tres partes:

La interfaz VirtualKeyboard en el objeto navigator para el acceso programático al teclado virtual desde JavaScript
Es un conjunto de variables de entorno de CSS que proporcionan información sobre la apariencia del teclado virtual.
Una política de teclado virtual que determina si se debe mostrar el teclado virtual.

Estado actual

La API de VirtualKeyboard está disponible a partir de Chromium 94 en computadoras y dispositivos móviles.

Detección de funciones y compatibilidad con navegadores

Para detectar si la API de VirtualKeyboard es compatible con el navegador actual, usa el siguiente fragmento:

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

Cómo usar la API de VirtualTeclado

La API de VirtualKeyboard agrega una nueva interfaz VirtualKeyboard al objeto navigator.

Habilita el nuevo comportamiento del teclado virtual

Para indicarle al navegador que tú te encargas de las oclusiones del teclado virtual, primero debes habilitar el nuevo comportamiento del teclado virtual configurando la propiedad booleana overlaysContent en true.

navigator.virtualKeyboard.overlaysContent = true;

Cómo mostrar y ocultar el teclado virtual

Puedes mostrar el teclado virtual de manera programática llamando a su método show(). Para que esto funcione, el elemento enfocado debe ser un control de formulario (como un elemento textarea) o un host de edición (por ejemplo, con el atributo contenteditable). El método siempre muestra undefined, pero activa un evento geometrychange si no se mostró el teclado virtual anteriormente.

navigator.virtualKeyboard.show();

Para ocultar el teclado virtual, llama al método hide(). El método siempre muestra undefined, pero activa un evento geometrychange si se mostró el teclado virtual anteriormente.

navigator.virtualKeyboard.hide();

Cómo obtener la geometría actual

Para obtener la geometría actual del teclado virtual, consulta la propiedad boundingRect. Expone las dimensiones actuales del teclado virtual como un objeto DOMRect. El inserto corresponde a las propiedades superior, derecha, inferior o izquierda.

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

Recibir información sobre los cambios de geometría

Cada vez que el teclado virtual aparece o desaparece, se despacha el evento geometrychange. La propiedad target del evento contiene el objeto virtualKeyboard que (como se mencionó anteriormente) contiene la nueva geometría de la inserción del teclado virtual como un DOMRect.

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

Las variables de entorno de CSS

La API de VirtualKeyboard expone un conjunto de variables de entorno de CSS que proporcionan información sobre el aspecto del teclado virtual. Se modelan de manera similar a la propiedad de CSS inset, es decir, correspondientes a las propiedades superior, derecha, inferior o izquierda.

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

Las inserciones del teclado virtual son seis variables de entorno que definen un rectángulo por sus inserciones superior, derecha, inferior e izquierda desde el borde del viewport. Las inserciones de ancho y altura se calculan a partir de las otras inserciones para la ergonomía de los desarrolladores. El valor predeterminado de cada elemento insertado del teclado es 0px si no se proporciona un valor de resguardo.

Por lo general, debes usar las variables de entorno como en el siguiente ejemplo:

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

La política de teclado virtual

A veces, el teclado virtual no debe aparecer cuando se enfoca un elemento editable. Un ejemplo es una aplicación de hoja de cálculo en la que el usuario puede presionar una celda para que su valor se incluya en una fórmula de otra celda. virtualkeyboardpolicy es un atributo cuyas palabras clave son las cadenas auto y manual. Cuando se especifica en un elemento que es un host contenteditable, auto hace que el elemento editable correspondiente muestre automáticamente el teclado en pantalla cuando se enfoque o se presione, y manual desconecta el enfoque y la presión sobre el elemento editable de los cambios en el estado actual del teclado en pantalla.

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

Demostración

Puedes ver la API de VirtualKeyboard en acción en una demo en Glitch. Asegúrate de explorar el código fuente para ver cómo se implementa. Si bien se pueden observar eventos geometrychange en la incorporación de iframe, el comportamiento real del teclado virtual requiere que se abra la demostración en su propia pestaña del navegador.

Vínculos útiles

Agradecimientos

Anupam Snigdha de Microsoft especificó la API de VirtualKeyboard, con contribuciones del exeditor Grisha Lyukshin, también de Microsoft.