Esta página foi traduzida pela API Cloud Translation.

Controle total com a API VirtualKeyboard

Thomas Steiner

Twitter GitHub Glitch Mastodon Página inicial

Compatibilidade com navegadores

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.

A abordagem tradicional resulta em

Situações como essa são a função da API VirtualKeyboard. Ela é composta por três partes:

A interface VirtualKeyboard no objeto navigator 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

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