JavaScript KeyCode: Como Capturar Teclas Corretamente

O termo javascript keycode ainda é muito pesquisado por desenvolvedores que precisam identificar teclas pressionadas em formulários, jogos, atalhos e interfaces web. Durante anos, a propriedade keyCode foi a solução mais conhecida para essa tarefa. Contudo, ela foi descontinuada nos padrões modernos da plataforma web e deve ser substituída por recursos mais claros e confiáveis, como event.key, event.code e a interface KeyboardEvent. Neste guia, você entenderá como os eventos de teclado funcionam, por que o uso de keyCode pode criar problemas e como implementar uma captura de teclas acessível, compatível e fácil de manter.

O que significa JavaScript KeyCode e por que mudou

Em JavaScript, um evento de teclado ocorre quando a pessoa usuária interage com uma tecla física ou virtual. Os eventos mais utilizados são keydown, disparado quando a tecla é pressionada, e keyup, executado quando ela é liberada. Historicamente, o objeto do evento disponibilizava a propriedade event.keyCode, um número associado à tecla detectada. Por exemplo, o valor 13 era normalmente utilizado para Enter, 27 para Escape e 32 para a barra de espaço.

O problema é que essa abordagem numérica não comunica bem a intenção do código, apresenta diferenças históricas entre navegadores e não descreve adequadamente todos os layouts de teclado e métodos de entrada. Por esse motivo, keyCode, assim como which e charCode, é considerado obsoleto. A documentação da MDN Web Docs sobre KeyboardEvent.keyCode recomenda não usar essa propriedade em novas aplicações.

O caminho atual é consultar event.key quando a aplicação precisa saber qual caractere ou ação foi produzida, e consultar event.code quando é necessário identificar a posição física da tecla. Ambos pertencem à interface KeyboardEvent, padronizada para fornecer informações mais semânticas e portáveis sobre a entrada do teclado.

Diferença entre event.key e event.code

A propriedade event.key representa o valor lógico da tecla. Ao pressionar Enter, por exemplo, ela geralmente retorna Enter; ao pressionar Escape, retorna Escape; e, ao digitar a letra A, pode retornar a ou A, conforme o estado de Shift e Caps Lock. Isso a torna especialmente adequada para comandos que dependem do resultado percebido pela pessoa usuária.

Já event.code identifica a posição física do controle no teclado. Uma tecla na posição alfabética correspondente a A costuma fornecer KeyA, ainda que o layout ativo gere outro caractere. Da mesma forma, a seta para cima retorna ArrowUp. Essa distinção é valiosa em jogos, simuladores e aplicativos em que a posição da tecla deve permanecer estável entre layouts internacionais.

Veja um exemplo moderno para fechar uma janela modal com Escape:

document.addEventListener('keydown', function (event) {
  if (event.key === 'Escape') {
    fecharModal();
  }
});

Nesse caso, a comparação é explícita e legível. Não é necessário memorizar que o antigo javascript keycode de Escape era 27. Além disso, a intenção do recurso fica mais fácil de revisar por outras pessoas da equipe.

Como usar KeyboardEvent na prática

O objeto recebido pelo ouvinte de eventos contém mais informações do que a tecla principal. Ele informa se modificadores estão ativos por meio de ctrlKey, shiftKey, altKey e metaKey. A propriedade repeat indica se o sistema está repetindo o evento porque a tecla foi mantida pressionada. Também é possível usar preventDefault() para impedir uma ação padrão, porém isso deve ser feito somente quando houver uma justificativa clara de experiência e acessibilidade.

document.addEventListener('keydown', (event) => {
  const salvarComAtalho = (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 's';

  if (salvarComAtalho) {
    event.preventDefault();
    salvarDocumento();
  }
});

O exemplo reconhece Ctrl+S em sistemas Windows e Linux, bem como Command+S em macOS. O uso de toLowerCase() evita que o atalho falhe quando Shift estiver pressionado. Ainda assim, a aplicação deve comunicar o atalho de maneira visível e oferecer um botão convencional para salvar, pois nem todas as pessoas utilizam teclado.

Boas práticas para eventos de teclado JavaScript

• Prefira event.key: utilize valores como Enter, Escape, Tab e ArrowDown em vez de códigos numéricos antigos.
• Use event.code em jogos: quando a posição física importa, KeyW, KeyA, KeyS e KeyD são escolhas mais previsíveis.
• Escolha o evento correto: keydown serve para atalhos e movimento; keyup é útil para detectar a liberação; input é mais indicado para acompanhar alterações de conteúdo em campos.
• Não bloqueie Tab sem necessidade: impedir o comportamento padrão de Tab pode quebrar a navegação por teclado e prejudicar a acessibilidade.
• Respeite campos editáveis: antes de ativar um atalho global, verifique se o foco está em input, textarea ou elemento com contenteditable.
• Considere teclados internacionais: caracteres e símbolos podem variar conforme idioma, layout e teclas modificadoras. Evite supor que toda pessoa possui o mesmo teclado.
• Teste em dispositivos reais: valide o comportamento em navegadores modernos, sistemas operacionais distintos e, quando aplicável, com leitores de tela.

Um erro comum no desenvolvimento de interfaces é escutar keypress para qualquer necessidade. Esse evento também é legado e seu comportamento pode ser inconsistente. Para comandos baseados em teclas, use normalmente keydown. Para acompanhar texto digitado, utilize o evento input, pois ele reflete alterações causadas por colagem, reconhecimento de voz, teclado virtual e outros mecanismos além da pressão direta de teclas.

Comparativo entre keyCode, event.key e event.code

Embora o valor de Enter seja intuitivo tanto em key quanto em code, a diferença se torna evidente com letras e símbolos. Em um teclado com layout alternativo, event.code === 'KeyQ' identifica a posição física da tecla Q, enquanto event.key pode retornar o caractere produzido naquele layout. A especificação UI Events KeyboardEvent key Values, publicada pelo W3C, lista os valores padronizados para teclas de navegação, edição, mídia e funções especiais.

Perguntas frequentes sobre captura de teclas

O que é JavaScript keycode?

JavaScript keycode é a expressão usada para descrever a identificação numérica de teclas pelo antigo atributo event.keyCode. Embora ainda apareça em códigos antigos e tutoriais, esse atributo foi descontinuado. Em projetos atuais, a alternativa recomendada é event.key ou event.code.

Qual é o keyCode da tecla Enter?

O valor histórico de Enter em keyCode é 13. Contudo, a implementação moderna deve verificar event.key === 'Enter'. Essa forma é mais clara, não depende da memorização de números e acompanha os padrões atuais dos navegadores.

Quando devo usar event.key em vez de event.code?

Use event.key quando a lógica depende da ação ou do caractere gerado, como Enter, Escape ou uma letra digitada. Use event.code quando a posição física deve definir o comando, caso clássico dos controles de jogos com WASD.

Por que meu atalho de teclado não funciona dentro de um input?

O foco pode estar em um campo de edição, onde a pessoa usuária espera digitar livremente. Um listener global pode capturar a combinação, mas a aplicação deve verificar o elemento ativo antes de executar ações invasivas. Isso reduz conflitos e preserva uma experiência previsível.

É seguro usar preventDefault em keydown?

É seguro apenas quando a ação padrão precisa realmente ser substituída e a interface oferece uma alternativa equivalente. Evite bloquear Tab, atalhos do navegador e comandos do sistema sem análise cuidadosa, pois isso pode comprometer acessibilidade, usabilidade e expectativas da pessoa usuária.

Conclusão: modernize seu código de teclado

Dominar javascript keycode hoje significa compreender sua evolução e evitar dependência de APIs obsoletas. O antigo keyCode pode ser necessário durante uma migração de código legado, mas não deve orientar novas funcionalidades. Para comandos semânticos, escolha event.key; para controles associados à posição física, escolha event.code; e use os modificadores de KeyboardEvent para criar atalhos consistentes. Ao testar layouts, preservar a navegação por teclado e respeitar campos de texto, sua aplicação se torna mais robusta, inclusiva e preparada para o ecossistema web moderno.

Referências e documentação consultada

• MDN Web Docs — KeyboardEvent.
• MDN Web Docs — propriedade KeyboardEvent.key.
• MDN Web Docs — propriedade KeyboardEvent.code.
• W3C — UI Events KeyboardEvent key Values.

Isenção de responsabilidade

Este conteúdo tem finalidade educacional e informativa. APIs, padrões de navegadores e recomendações de segurança podem mudar ao longo do tempo. Antes de aplicar trechos de código em ambientes de produção, consulte a documentação oficial atualizada, teste em seu contexto técnico e avalie requisitos de acessibilidade, privacidade e compatibilidade do seu projeto.