Localizador de código-chave JavaScript

Como funciona

1. Pressione uma tecla : clique na área de entrada e pressione qualquer tecla, letras, números, teclas de função, setas, modificadores ou teclas especiais.
2. Leia os códigos de tecla : a ferramenta exibe instantaneamente os valores event.key, event.code, event.keyCode (legado) e charCode da tecla.
3. Use no seu código : copie os valores exatos necessários para seus listeners de eventos de teclado ou para suas implementações de atalhos.

Por que usar o detector de keycode ?

Os eventos de teclado JavaScript expõem várias propriedades diferentes (key, code, keyCode, charCode e which) e saber qual usar e com qual valor comparar é sistematicamente complicado. O detector de KeyCode elimina as adivinhações ao permitir que você pressione uma tecla e veja imediatamente todas as suas propriedades de evento. Valioso para construir atalhos de teclado, gerenciar teclas especiais, implementar hotkeys e depurar listeners de eventos de teclado.

Funcionalidades

• Todas as propriedades de evento : exibe event.key, event.code, event.keyCode, event.which e event.charCode para cada pressionamento.
• Detecção de teclas modificadoras : indica se Shift, Ctrl, Alt e Meta estavam mantidas no momento do pressionamento.
• Suporte a teclas especiais : funciona com teclas de função (F1–F12), setas, Enter, Esc, Tab, Backspace e todas as outras teclas especiais.
• Histórico de teclas : mantém um registro dos pressionamentos recentes para comparar várias teclas.
• Copiar os valores : clique em qualquer valor para copiá-lo diretamente para a área de transferência.

Perguntas frequentes

Qual a diferença entre event.key e event.keyCode ?

event.key é o padrão moderno, retorna uma string legível como « ArrowLeft » ou « Enter ». event.keyCode é um código numérico legado (depreciado, mas ainda suportado). Use event.key para código novo ; event.keyCode para manter a compatibilidade com navegadores antigos.

Como detectar Ctrl+S ou outras combinações de teclas ?

As combinações de teclas usam event.key combinado a verificações de modificadores : if (event.ctrlKey && event.key === "s"). Pressione Ctrl+S nesta ferramenta para ver todos os valores, depois reproduza a mesma condição no seu listener de evento.

Por que algumas teclas exibem o mesmo keyCode ?

Os valores keyCode não foram normalizados e algumas teclas compartilham códigos conforme o contexto. event.code é mais confiável, identifica a posição física da tecla (por ex. « KeyA ») independentemente do layout do teclado, enquanto event.key reflete o caractere produzido por essa tecla.

30 anos de história dos eventos de teclado em JavaScript

Os eventos de teclado têm uma história notoriamente confusa no DOM. Netscape Navigator 2 (1995) introduziu os handlers originais onkeydown, onkeypress e onkeyup com uma propriedade numérica keyCode, que não tinha especificação; os navegadores inventaram cada um seus próprios valores. Internet Explorer 4 (1997) implementou sua própria variante com event.keyCode como única propriedade, enquanto o Netscape ficou com event.which. DOM Level 2 Events (W3C, novembro de 2000) padronizou o fluxo de eventos (captura/borbulha) mas explicitamente deixou de lado os eventos de teclado porque os fornecedores não conseguiam concordar. O resultado: desenvolvedores escreveram código como e.keyCode || e.which por mais de uma década. DOM Level 3 Events (W3C Working Draft 2003, Recomendação 2018) finalmente introduziu o moderno event.key (caractere Unicode ou tecla nomeada como «ArrowLeft») e event.code (posição física da tecla como «KeyA», independente de layout), junto com a depreciação de keyCode, charCode e which. A especificação UI Events (W3C, em andamento) é o lar moderno deste trabalho. Os navegadores acompanharam gradualmente: Chrome 51 (maio de 2016), Firefox 47 (junho de 2016), Safari 10.1 (março de 2017) todos enviaram suporte a event.code. O evento legado keypress está depreciado em favor dos eventos beforeinput e input.

As 5 propriedades, decodificadas

• event.key (moderno, use isto). O caractere ou tecla nomeada produzido. Letras e dígitos dão o caractere Unicode respeitando modificadores e layout (Shift+a = «A», AZERTY posição-Q = «a»). Teclas nomeadas são strings como «Enter», «Escape», «ArrowLeft», «F5», «Control». Definido em UI Events.
• event.code (moderno, use para jogos). Identifica a tecla física no teclado, independente de layout ou modificadores. Exemplos: «KeyA», «Digit1», «ArrowUp», «ShiftLeft», «MetaLeft». Use isto para movimento WASD, navegação estilo vim, e atalhos que devem ignorar o layout do teclado.
• event.keyCode (depreciado). Código numérico. 13 = Enter, 27 = Escape, 32 = Espaço, 37-40 = Seta Esquerda/Cima/Direita/Baixo, 65-90 = A-Z, 112-123 = F1-F12. Os valores nunca foram padronizados, só se tornaram consistentes entre navegadores por convergência. Evite em código novo.
• event.which (depreciado). Equivalente Netscape de keyCode. Para a maioria dos caracteres imprimíveis e teclas não-imprimíveis, idêntico a keyCode. O velho polyfill e.keyCode || e.which tratava casos onde um era 0.
• event.charCode (depreciado, apenas em keypress). O ponto de código Unicode do caractere. 97 para «a», 65 para «A». Dispara apenas em keypress (que é em si depreciado). Os eventos input e beforeinput são as substituições modernas.
• Booleanos de modificadores. event.shiftKey, event.ctrlKey, event.altKey, event.metaKey (Command no macOS, tecla Windows no Windows). Sempre verifique modificadores explicitamente: e.metaKey || e.ctrlKey para «salvar» multiplataforma (Cmd+S no Mac, Ctrl+S no Windows/Linux).
• event.location. Distingue modificadores esquerdo vs direito e o teclado numérico. 0=padrão, 1=modificador esquerdo, 2=modificador direito, 3=numérico. Útil para distinguir Shift-esquerdo vs Shift-direito para layouts de jogo.

Onde a busca de keycode realmente importa

• Atalhos de teclado de aplicação. Cmd/Ctrl+S para salvar, Cmd/Ctrl+Z para desfazer, Cmd/Ctrl+K para abrir paleta de comandos (Slack, Linear, GitHub, Notion todos usam isso desde por volta de 2020). Sempre use event.key para a tecla imprimível e um booleano de modificador para a meta-tecla.
• Paleta de comandos e fuzzy finder. O padrão Cmd+K popularizado pelo Slack (2014) e Linear (2019). Escute o atalho de abertura globalmente, depois trate navegação ArrowUp/ArrowDown, Enter para selecionar, Escape para fechar.
• Jogos de navegador e desenvolvimento de jogos HTML5. Phaser, Babylon.js, Three.js. Sempre use event.code para teclas de movimento para que WASD funcione em teclados AZERTY (onde «W» está na posição «Z»). Sebastian Lague, Notch (protótipo Minecraft inicial), e jogos itch.io todos caíram nessa armadilha AZERTY.
• Padrões de acessibilidade. Diálogos modais precisam de Escape para fechar. Widgets Combobox precisam de ArrowDown/ArrowUp/Enter/Escape. Tooltips precisam fechar com Escape. O WAI-ARIA Authoring Practices Guide define padrões de interação de teclado para cada widget comum; event.key é o padrão para essas verificações.
• Implementação de editor de texto e código. Monaco (o editor do VS Code no navegador), CodeMirror, ProseMirror, Lexical todos mapeiam eventos de teclado para comandos. Usam event.code para atalhos estilo vim/emacs que não dependem do layout.
• Melhorias de UX de formulário. Enviar com Enter, blur com Escape, avançar foco com Tab. Comum em fluxos de checkout, barras de busca, campos de autocompletar.
• Atalhos de extensão de navegador. Vimium, SurfingKeys, Tridactyl fornecem navegação por teclado para toda a web. Escutam no nível de documento e tratam sequências modais de teclas complexas (gg = ir ao topo, como vim).

Erros comuns no tratamento de eventos de teclado

• Usar keyCode em código novo. Depreciado desde DOM Level 3 (2018), historicamente inconsistente entre navegadores, e quebra em layouts não-US (a vírgula tem keyCode 188 no US, 191 em alguns teclados alemães). Use event.key no lugar.
• Codificar e.key === "w" para movimento de jogo. Em teclados AZERTY (francês), a tecla W física digita «z». Jogadores buscam o que lembram como o cluster WASD mas obtêm a entrada errada. Use event.code === "KeyW" no lugar, que identifica a posição física.
• Verificar apenas ctrlKey para «salvar». No macOS, Cmd+S é a convenção; ctrlKey é falso mas metaKey é verdadeiro. Sempre verifique ambos: (e.metaKey || e.ctrlKey) && e.key === "s".
• Esquecer preventDefault em atalhos reservados do navegador. Sequestrar Cmd+S sem preventDefault ainda dispara Save Page As. Mesmo para Cmd+P (imprimir), Ctrl+F (busca do navegador), Ctrl+N (nova janela, não pode ser bloqueado de qualquer forma), Ctrl+Tab (Chrome não deixa). Chame e.preventDefault() no handler.
• Ignorar composição IME. Métodos de entrada japonês, chinês, coreano (IME) disparam eventos keydown enquanto o usuário compõe caracteres. Verifique e.isComposing ou use o evento compositionend antes de disparar seu handler de atalho. Slack famosamente bagunçou isso para usuários japoneses em 2017.
• Usar o evento depreciado keypress. Dispara apenas para teclas produtoras de caracteres (não teclas de seta, função, etc.). Depreciado; use keydown para atalhos e input/beforeinput para mudanças de texto.
• Disparar atalhos em cada repetição. Manter uma tecla dispara eventos keydown repetidamente. Para ações de toggle (abrir paleta, trocar aba), verifique e.repeat e saia cedo para evitar registrar 30 comandos «abrir» quando o usuário acidentalmente manteve a tecla.

Mais perguntas frequentes

Por que meu handler de tecla não dispara quando o usuário tem teclado não-US?

Quase sempre porque você está verificando event.key para um caractere que só existe com Shift naquele layout. Em um teclado alemão QWERTZ, «/» é Shift+7 (não sua própria tecla); em AZERTY francês, dígitos 0-9 são digitados com Shift+a-linha-acima. Use event.code (tecla física) para atalhos baseados em posição, ou event.key para atalhos baseados em conteúdo (onde você realmente quer o caractere que o usuário acabou de digitar).

Como lido com Cmd+K / Ctrl+K consistentemente entre plataformas?

O idioma padrão: if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") { e.preventDefault(); openPalette(); }. No macOS, e.metaKey é a tecla Cmd; no Windows/Linux, e.ctrlKey é o que usuários esperam. Aceite ambos. Sempre preventDefault porque o navegador liga Cmd+K a «focar barra de endereço» em alguns navegadores. Adicione !e.repeat para evitar disparar em manutenção de tecla.

JavaScript pode detectar teclas globais fora da página?

Não, e isso é por design por segurança. O navegador só dispara eventos de teclado para a página ou elemento focado. Extensões de navegador podem escutar com escopo mais amplo usando a API chrome.commands. Apps nativos em Electron, Tauri, etc., podem usar hooks globais a nível de OS. Apps bancários e 2FA dependem dessa isolação: uma aba maliciosa não pode keylogger seu gerenciador de senhas.

Qual a forma certa de detectar «acabou de pressionar» vs «sendo mantido»?

Para toggles, verifique !e.repeat no handler keydown: o primeiro evento tem repeat: false, eventos subsequentes de auto-repetição têm repeat: true. Para ações contínuas (movimento de jogo), rastreie estado de teclas em um Set: adicione em keydown, remova em keyup, depois no seu loop de renderização verifique keysHeld.has("KeyW"). Isso desacopla a entrada do framerate e lida com múltiplas teclas simultâneas (mover + pular).

Algo é enviado para um servidor quando pressiono teclas aqui?

Não. Eventos de tecla são capturados localmente por JavaScript e exibidos nesta página sem nenhuma requisição de rede. Abra a aba Network no DevTools, digite; verá zero tráfego saindo. Seguro para testar em qualquer contexto, incluindo descobrir o que senhas ou atalhos sensíveis produzem no seu teclado.