Controle total com a API VirtualKeyboard

Thomas Steiner

Dispositivos como tablets ou smartphones geralmente têm um teclado virtual para digitar texto. Ao contrário 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 tem o preço de que 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. Por isso, o navegador precisa rolar para exibir o campo.

Tradicionalmente, os navegadores lidavam 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 multitela em que a abordagem tradicional resultaria em espaço de tela "desperdiçado" se o teclado virtual fosse mostrado em apenas um segmento de tela, mas em que a viewport disponível fosse reduzida em ambas as telas. A imagem abaixo mostra como a API VirtualKeyboard pode ser usada para otimizar o layout do documento de forma dinâmica para compensar a presença do teclado virtual.

Em situações como essa, a API VirtualKeyboard é útil. Ela é composta por três partes:

• A interface VirtualKeyboard no objeto navigator para acesso programático ao teclado virtual do JavaScript.
• Um conjunto de variáveis de ambiente do CSS que fornecem informações sobre a aparência do teclado virtual.
• Uma política de teclado virtual que determina se o teclado virtual precisa ser mostrado.

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 o snippet a seguir:

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.

Ativar o novo comportamento do teclado virtual

Para informar ao navegador que você está cuidando das obstruções do teclado virtual, primeiro ative o novo comportamento do teclado virtual definindo a propriedade booleana overlaysContent como true.

navigator.virtualKeyboard.overlaysContent = true;

Mostrar e ocultar o teclado virtual

É possível mostrar o teclado virtual programaticamente chamando o método show() dele. Para que isso funcione, o elemento em foco precisa ser um controle de formulário (como 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 acessar a geometria atual

É possível conferir a geometria atual do teclado virtual na propriedade boundingRect. Ele expõe as dimensões atuais do teclado virtual como um objeto DOMRect. O inseto corresponde às propriedades de cima, direita, baixo 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 (conforme discutido acima) contém a nova geometria do teclado virtual inserido como um 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 do 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 forma semelhante à propriedade CSS inset, ou seja, correspondem à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 insetos do teclado virtual são seis variáveis de ambiente que definem um retângulo pelos insetos de cima, direita, inferior e esquerda da borda da janela de visualização. Os insetos de largura e altura são calculados a partir dos outros insetos para ergonomia do desenvolvedor. O valor padrão de cada elemento de teclado é 0px se um valor substituto não for fornecido.

Normalmente, você usa as variáveis de ambiente 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);
}

A política de 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 o valor dela seja incluído em uma fórmula de outra célula. O virtualkeyboardpolicy é um atributo com as palavras-chave 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 é focado ou tocado. Além disso, manual desepara o foco e o toque no elemento editável de 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

Confira a API VirtualKeyboard em ação em uma demonstração no Glitch. Confira o código-fonte para saber como ele é implementado. Embora os eventos geometrychange possam ser observados na incorporação de iframe, o comportamento do teclado virtual requer a abertura da demonstração na própria guia do navegador.

Links úteis

• Especificação
• Repositório
• Entrada do ChromeStatus
• Bug do Chromium
• Revisão da TAG do W3C
• Solicitação de posição de padrões do Mozilla
• Solicitação de posição de padrões do WebKit

Agradecimentos

A API VirtualKeyboard foi especificada por Anupam Snigdha, da Microsoft, com contribuições do ex-editor Grisha Lyukshin, também da Microsoft.