Control total con la API de VirtualKeyboard

Thomas Steiner

Twitter GitHub Glitch Mastodon Página principal

Navegadores compatibles

• 94
• 94
• x
• x

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 siempre igual, un teclado virtual aparece y desaparece, según las acciones del usuario, al que también se puede adaptar dinámicamente, por ejemplo, según el atributo inputmode.

Esta flexibilidad se relaciona con el precio de que el motor de diseño del navegador deba estar informado sobre la presencia del teclado virtual y posiblemente deba ajustar el diseño del documento para compensarlo. Por ejemplo, un campo de entrada que el usuario está a punto de escribir puede estar oculto debido al teclado virtual, por lo que el navegador debe desplazarlo para que sea visible.

Tradicionalmente, los navegadores enfrentan este desafío por sí solos, pero las aplicaciones más complejas pueden requerir más control sobre el comportamiento del navegador. Algunos ejemplos son los dispositivos móviles multipantalla, en los que el enfoque tradicional generaría un "desperdicio" de espacio en pantalla si el teclado virtual se muestra en un solo segmento de pantalla, pero cuando el viewport disponible se reduce en ambas pantallas. En la siguiente imagen, se muestra cómo se puede usar la API de VirtualKeyboard para optimizar el diseño del documento de forma dinámica y, así, compensar la presencia del teclado virtual.

En este tipo de situaciones, 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 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 de escritorio 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 VirtualKeyboard

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

Cómo habilitar el nuevo comportamiento del teclado virtual

Para indicarle al navegador que estás cuidando las oclusiones del teclado virtual, primero debes habilitar el nuevo comportamiento del teclado virtual. Para ello, establece 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, mediante 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 ocultarlo, llama al método hide(). El método siempre muestra undefined, pero activa un evento geometrychange si se mostró anteriormente el teclado virtual.

navigator.virtualKeyboard.hide();

Cómo obtener la geometría actual

Puedes obtener la geometría actual del teclado virtual en la propiedad boundingRect. Expone las dimensiones actuales del teclado virtual como un objeto DOMRect. La inserción 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 cambios geométricos

Cuando el teclado virtual aparece o desaparece, se envía el evento geometrychange. La propiedad target del evento contiene el objeto virtualKeyboard que (como se explicó anteriormente) incluye 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 la apariencia del teclado virtual. Se modelan de forma similar a la propiedad inset de CSS, es decir, que corresponde 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 izquierda, derecha, superior y derecha desde el borde del viewport. Las inserciones de ancho y altura se calculan a partir de las otras inserciones para mejorar la ergonomía de los desarrolladores. Si no se proporciona un valor de resguardo, el valor predeterminado de cada inserción del teclado es 0px.

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 del teclado virtual

A veces, el teclado virtual no debería aparecer cuando se enfoque 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 se incluya su valor en una fórmula de otra celda. El 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 virtual cuando se enfoca o presiona, y manual separa el enfoque y presiona el elemento editable de los cambios en el estado actual del teclado virtual.

<!-- 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 demostración en Glitch. Asegúrate de explorar el código fuente para ver cómo se implementa. Si bien se pueden observar los eventos geometrychange en la incorporación del iframe, el comportamiento real del teclado virtual requiere abrir la demostración en su propia pestaña del navegador.

Vínculos útiles

• Especificación
• Repositorio
• Entrada de ChromeStatus
• Error de Chromium
• Opinión de la TAG de W3C
• Solicitud de posición de los estándares de Mozilla
• Solicitud de posición de estándares de WebKit

Agradecimientos

Anupam Snigdha de Microsoft especificó la API de VirtualKeyboard, con contribuciones de la editora anterior Grisha Lyukshin, del mismo modo que Microsoft. Hero image de @freestocks en Unsplash.