Esta página foi traduzida pela API Cloud Translation.

Controle total com a API VirtualKeyboard

Thomas Steiner

Compatibilidade com navegadores

Dispositivos como tablets ou celulares geralmente têm um teclado virtual para digitar texto. Ao contrário de um teclado físico que está sempre presente e igual, um teclado virtual é exibido e desaparece, dependendo das ações do usuário, às quais também pode se adaptar dinamicamente, para exemplo, com base inputmode .

Essa flexibilidade depende do preço que o mecanismo de layout do navegador precisa informar sobre o 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 oculto pelo teclado virtual, de modo que o navegador precisa rolar a tela para vê-lo.

Tradicionalmente, os navegadores lidam com esse desafio por conta própria, mas aplicativos mais complexos pode exigir mais controle sobre o comportamento do navegador. Por exemplo, dispositivos móveis multitelas em que a abordagem tradicional resultaria em "desperdício" espaço da tela se o teclado virtual é exibido em apenas um segmento da tela, mas onde a janela de visualização disponível está reduzida nas duas telas mesmo assim. A imagem abaixo mostra como a API VirtualKeyboard pode ser usada para otimizar o layout. do documento dinamicamente para compensar a presença do teclado virtual.

A abordagem tradicional resulta

Situações como essa são usadas em situações como essa. Ela é composta por três partes:

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

Status atual

A API VirtualTeclado está disponível no Chromium 94 para computadores e dispositivos móveis.

Detecção de recursos e compatibilidade com navegadores

Para detectar se a API VirtualKeyboard é compatível com o navegador atual, use o seguinte 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 por conta própria, você precisa primeiro ative o novo comportamento do teclado virtual definindo a propriedade booleana overlaysContent para true.

navigator.virtualKeyboard.overlaysContent = true;

Como mostrar e ocultar o teclado virtual

Você pode 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 (como um elemento textarea) ou ser um host de edição (por exemplo, ao usar o método contenteditable ). O método sempre retorna undefined, mas aciona um evento geometrychange. se o teclado virtual anteriormente não aparecia.

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 tiver sido exibido anteriormente.

navigator.virtualKeyboard.hide();

Como obter a geometria atual

Você pode ver a geometria atual do teclado virtual consultando a propriedade boundingRect. Ele expõe as dimensões atuais do teclado virtual como uma 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);

Ser informado sobre alterações 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) contém a nova geometria do encarte do teclado virtual 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);
});

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. Eles são modelados de forma semelhante à propriedade CSS inset, ou seja, corresponde à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 pela parte superior, direita encartes inferior e esquerdo a partir da borda da janela de visualização. As inserções de largura e altura são calculadas dos outros encartes para ergonomia do desenvolvedor. O valor padrão de cada encarte de teclado é 0px se um valor substituto não for fornecido.

Você normalmente usaria 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);
}

Política de teclado virtual

Às vezes, o teclado virtual não deve aparecer quando um elemento editável estiver em foco. Um exemplo é uma aplicativo de planilha em que o usuário pode tocar em uma célula para que seu valor seja incluído em uma fórmula de em outra célula. O virtualkeyboardpolicy é um atributo cujas palavras-chave 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 para mostrar automaticamente o teclado virtual quando ele estiver em foco ou e o manual separa o foco e toca no elemento editável das mudanças estado atual do teclado.

<!-- 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

É possível conferir a API VirtualKeyboard em ação em um demo no Glitch. Não deixe de conferir código-fonte para ver como ele é implementado. Embora os eventos geometrychange possam ser observados na incorporação do iframe, o teclado virtual real comportamento exige abrir a demonstração na própria guia do navegador.

Links úteis

Agradecimentos

A API VirtualKeyboard foi especificada por Anupam Snigdha, da Microsoft, com contribuições de ex-editora Grisha Lyukshin, da Microsoft também. Imagem principal de @freestocks em Abrir a página.