Visualizador de código de tecla

O que é um visualizador de código de tecla?#

Quando uma tecla é premida, o navegador dispara um KeyboardEvent que transporta duas respostas paralelas à pergunta “qual tecla?”. O campo key diz que caráter a pressão produziu — a, A, Enter, ?. O campo code diz que tecla física foi premida — KeyA, Enter, Slash — independentemente do layout. Essas duas respostas afastam-se no momento em que se envolve um teclado internacional, um modificador, ou um teclado numérico, e a diferença é exatamente o que se precisa de ver quando se está montando um atalho, um controlo de jogo, ou uma funcionalidade de acessibilidade.

Esta página captura cada keydown num instantâneo e expõe todos os campos: key, code, os números legados keyCode e which (mantidos para depurar código antigo), a localização (padrão / esquerda / direita / teclado numérico), os modificadores ativos, e se a pressão foi uma auto-repetição. Um histórico rolante das últimas pressões mantém-se visível para que se consiga rastrear um acorde ou uma sequência.

Nada é global: a captura só acontece enquanto o foco está dentro da zona de captura, pelo que o resto da página continua a obedecer ao teclado normalmente.

Como usar#

1. Clique em qualquer sítio na zona de captura tracejada no topo (ou faça Tab até ela). Ela realça-se para mostrar que está ouvindo.
2. Prima uma tecla, ou um acorde. A tabela de instantâneo por baixo atualiza-se em cada keydown.
3. Leia as linhas:
   • key — o valor lógico da tecla (o caráter ou tecla nomeada que o navegador resolveu).
   • code — a tecla física, independente do layout. É o que se faz corresponder para atalhos.
   • keyCode e which — os códigos numéricos obsoletos, sinalizados com um emblema obsoleto. Correspondam-se apenas ao portar código antigo que ainda os lê.
   • localização — Padrão, Esquerda, Direita, ou Teclado num.. É assim que se diz left-Shift de right-Shift, ou o 5 do teclado numérico do 5 da linha de topo.
   • repetição — sim enquanto uma tecla está sendo mantida e se auto-repetindo.
   • modificadores — emblemas para quais de Ctrl, Alt, Shift, Meta estavam premidos.
4. Marque Bloquear a ação padrão das teclas na barra de opções se quer que a página impeça o navegador de atuar sobre a tecla (por exemplo, para impedir Tab de mover o foco enquanto testa).
5. Use Copiar atual para recolher o instantâneo atual, e Limpar histórico no painel de histórico para reiniciar a lista rolante.

Principais recursos#

• Tanto key como code, lado a lado. A distinção mais útil no manuseamento de teclado, tornado visível em cada pressão — para que se veja imediatamente porque é que key === "@" pode vir de Shift+Digit2 num layout e de uma tecla física inteiramente diferente noutro.
• Sensibilidade à localização. Modificadores esquerdo e direito são reportados separadamente, e as teclas do teclado numérico transportam location: numpad. Essencial para layouts de gaming em que o mesmo dígito significa coisas diferentes na linha principal versus o teclado numérico.
• Emblemas de modificadores. Ctrl, Alt, Shift e Meta (Command no macOS, Super/Windows noutros lados) são mostrados por ordem convencional, para que se consiga ler um acorde num relance.
• Campos legados, claramente marcados. keyCode e which estão obsoletos e removidos das specs modernas, mas muito código existente ainda os lê. São apresentados com uma etiqueta obsoleto visível e uma nota de rodapé, nunca como a resposta principal.
• Histórico rolante de 20. Mantenha uma tecla e veja repetição passar a sim em cada auto-disparo; prima uma sequência e percorra-a. Cada entrada é um instantâneo isolado.
• Captura limitada. O listener está vinculado à zona de captura, não à janela. O resto da página — tabs, scroll — continua a funcionar até que se volte a focar a zona.

Exemplo detalhado#

Uma fonte clássica de confusão é a diferença entre o 1 da linha de topo e o 1 do teclado numérico. Produzem o mesmo caráter, mas não são a mesma tecla.

Prima o 1 da linha de topo e o instantâneo mostra:

key        1
code       Digit1
keyCode    49      (obsoleto)
which      49      (obsoleto)
location   Padrão
repeat     não
modifiers  nenhum

Agora prima o 1 do teclado numérico (com Num Lock ligado) e o instantâneo mostra:

key        1
code       Numpad1
keyCode    97      (obsoleto)
which      97      (obsoleto)
location   Teclado num.
repeat     não
modifiers  nenhum

Mesmo key, code diferente, location diferente, código legado diferente. Se está vinculando um atalho, faz corresponder em code === "Digit1" para significar “a linha por cima das letras”, e code === "Numpad1" para significar “o teclado numérico” — e evita a armadilha de corresponder em key === "1", que dispara para ambos.

Perguntas frequentes#

Devo fazer corresponder em key ou em code?#

Depende do que está construindo. Faça corresponder em code para atalhos e controlos de jogo, onde a posição física da tecla importa e não se quer que o vínculo mude quando o usuário muda para um layout Dvorak ou não-latino. Faça corresponder em key para entrada de texto, onde o caráter produzido é o que importa (? versus /, ou carateres compostos por dead-key). Para acordes de modificadores, verifique as flags de modificador (ctrlKey, metaKey, …) em vez do próprio valor key do modificador.

Porque é que keyCode e which estão marcados como “obsoleto”?#

Estão obsoletos e removidos da spec de UI Events. Os navegadores ainda os preenchem por compatibilidade, mas os seus valores nunca foram consistentes entre navegadores ou layouts (a mesma tecla física podia reportar números diferentes). Código moderno deve ler key e code. São mostrados aqui apenas para que se consiga depurar ou portar código mais antigo que ainda depende dos números — nunca os use para novos vínculos.

A página não capta as minhas teclas. Porque?#

A captura está limitada à zona tracejada. Se o foco foi para outro sítio — porque se fez Tab para fora, ou se clicou noutro controlo — a zona para de ouvir. Clique de volta dentro da zona (ela realça-se) e as pressões voltam a registrar-se. Este limitar é intencional: mantém o resto da página acessível por teclado.

A tecla Meta significa Command ou Windows?#

Ambos — Meta é a tecla “super” da plataforma: Command no macOS, a tecla Windows / Super em Linux e Windows. O emblema lê-se Meta em vez de adivinhar o sistema operativo, porque o campo metaKey subjacente é o que o seu código efetivamente precisa de testar.