Compatibilidade com navegadores
- 94
- 94
- x
- x
Dispositivos como tablets ou celulares geralmente têm um teclado virtual para digitação de texto.
Diferente de um teclado físico que está sempre presente e sempre o mesmo, um teclado virtual aparece
e desaparece, dependendo das ações do usuário, às quais ele também pode se adaptar dinamicamente, por
exemplo, com base no
atributo
inputmode
.
Essa flexibilidade ocorre porque o mecanismo de layout do navegador precisa ser informado sobre a presença do teclado virtual e possivelmente precisa ajustar o layout do documento para compensar. Por exemplo, um campo de entrada em que o usuário está prestes a digitar pode ser obscurecido pelo teclado virtual, fazendo com que o navegador precise rolar a tela para a visualização.
Tradicionalmente, os navegadores lidam com esse desafio por conta própria, mas aplicativos mais complexos podem exigir mais controle sobre o comportamento do navegador. Exemplos incluem dispositivos móveis com várias telas, em que a abordagem tradicional resultaria em espaço "desperdiçado" na tela se o teclado virtual for exibido em apenas um segmento da tela, mas em que a janela de visualização disponível é reduzida nas duas telas. A imagem abaixo mostra como a API VirtualKeyboard pode ser usada para otimizar dinamicamente o layout do documento para compensar a presença do teclado virtual.
Situações como essa são a função da API VirtualKeyboard. Ela é composta por três partes:
- A interface
VirtualKeyboard
no objetonavigator
para acesso programático ao teclado virtual no JavaScript. - Um conjunto de variáveis de ambiente CSS que fornecem informações sobre a aparência do teclado virtual.
- Uma política de teclado virtual que determina se o teclado virtual deve ser exibido.
Status atual
A API VirtualKeyboard está disponível no Chromium 94 para computadores e dispositivos móveis.
Detecção de recursos e suporte a navegadores
Para detectar se a API VirtualKeyboard tem suporte no navegador atual, use este snippet:
if ('virtualKeyboard' in navigator) {
// The VirtualKeyboard API is supported!
}
Como usar a API VirtualKeyboard
A API VirtualKeyboard adiciona uma nova interface VirtualKeyboard
ao objeto navigator
.
Como ativar o novo comportamento do teclado virtual
Para informar ao navegador que você está cuidando das oclusões do teclado virtual, primeiro ative o novo comportamento do teclado virtual definindo a propriedade booleana overlaysContent
como true
.
navigator.virtualKeyboard.overlaysContent = true;
Como mostrar e ocultar o teclado virtual
É possível mostrar o teclado virtual de forma programática chamando o método show()
dele. Para que isso funcione,
o elemento em foco precisa ser um controle de formulário (por exemplo, um elemento textarea
) ou um host de edição
(por exemplo, usando o
atributo
contenteditable
). O método sempre retorna undefined
, mas aciona um evento geometrychange
se o teclado virtual não foi mostrado anteriormente.
navigator.virtualKeyboard.show();
Para ocultar o teclado virtual, chame o método hide()
. O método sempre retorna undefined
, mas aciona
um evento geometrychange
se o teclado virtual foi mostrado anteriormente.
navigator.virtualKeyboard.hide();
Como encontrar a geometria atual
É possível ver a geometria atual do teclado virtual na propriedade boundingRect
.
Ele expõe as dimensões atuais do teclado virtual como um
objeto DOMRect
.
O encarte corresponde às propriedades superior, direita, inferior e/ou esquerda.
const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);
Receber informações sobre mudanças na geometria
Sempre que o teclado virtual aparece ou desaparece, o evento geometrychange
é enviado. A
propriedade target
do evento contém o objeto virtualKeyboard
que, como discutido acima, tem a nova geometria do encarte do teclado virtual como uma
DOMRect
.
navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.target.boundingRect;
console.log('Virtual keyboard geometry changed:', x, y, width, height);
});
As variáveis de ambiente CSS
A API VirtualKeyboard expõe um conjunto de variáveis de ambiente CSS que fornecem informações sobre
a aparência do teclado virtual.
Elas são modeladas de maneira semelhante à propriedade CSS inset
,
ou seja, correspondente às propriedades superior, direita, inferior e/ou esquerda.
keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height
Os encartes do teclado virtual são seis variáveis de ambiente que definem um retângulo pelos encartes superior, direito,
inferior e esquerdo da borda da janela de visualização. Os encartes de largura e altura são calculados
com base nos outros encartes para aumentar a ergonomia do desenvolvedor. O valor padrão de cada encarte de teclado será
0px
se um valor substituto não for fornecido.
Normalmente, as variáveis de ambiente são usadas como no exemplo abaixo:
.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);
}
Política do teclado virtual
Às vezes, o teclado virtual não aparece quando um elemento editável está em foco. Um exemplo é um aplicativo de planilha em que o usuário pode tocar em uma célula para que seu valor seja incluído na fórmula de outra célula. O virtualkeyboardpolicy
é um atributo com palavras-chave que são as strings auto
e
manual
. Quando especificado em um elemento que é um host contenteditable
, auto
faz com que o
elemento editável correspondente mostre automaticamente o teclado virtual quando ele está focado ou
tocado, e manual
separa o foco e o toque no elemento editável das mudanças no estado
atual do 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>
Demonstração
Veja a API VirtualKeyboard em ação em uma
demonstração no Glitch. Não deixe de explorar o
código-fonte para ver como ele é implementado.
Embora os eventos geometrychange
possam ser observados na incorporação do iframe, o comportamento real do teclado virtual
exige que a demonstração seja aberta em uma guia do navegador própria.
Links úteis
- Especificação
- Repositório
- Entrada ChromeStatus
- Bug do Chromium
- Análise da TAG W3C
- Solicitação de posição padrão do Mozilla
- Solicitação de posição para padrões do WebKit
Agradecimentos
A API VirtualKeyboard foi especificada por Anupam Snigdha, da Microsoft, com contribuições da antiga editora Grisha Lyukshin, da mesma forma que a Microsoft. Imagem principal de @freestocks no Unsplash (links em inglês).