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 objetonavigator
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.