Um utilizador pressiona Escape e o modal não fecha. Prime Enter no campo de pesquisa e nada acontece. Parece-lhe familiar? O tratamento de teclado em JavaScript parece simples até começarmos a lidar com três eventos, uma dúzia de propriedades e um zoológico de diferenças entre navegadores.

Cada keydown ou keyup gera um objeto KeyboardEvent com duas dezenas de campos. Alguns estão obsoletos desde a era do IE, outros comportam-se de forma diferente no Firefox e no Chrome. E a documentação da MDN está repleta de notas «não utilizar». Os programadores não precisam de outra especificação, precisam de uma folha de consulta que funcione.

Segue-se uma referência completa sobre eventos de teclado: da anatomia do KeyboardEvent a trechos de código prontos para atalhos de teclado. Guarde a tabela de códigos nos favoritos, vai precisar dela em quase todos os projetos.

💡 Visão geral rápida:

• Use keydown em vez de keypress: funciona para qualquer tecla.
• event.key devolve o símbolo da tecla, event.code devolve o seu código físico.
• event.keyCode e event.which estão obsoletos, não os utilize em código novo.
• A tabela abaixo reúne os códigos de todas as teclas padrão nos navegadores modernos.

O que contém o KeyboardEvent

Quando um utilizador pressiona uma tecla, o navegador cria um objeto KeyboardEvent, descendente de UIEvent, que por sua vez estende o Event base. No seu interior estão as propriedades da tecla, o estado dos modificadores e a informação de layout.

A especificação UI Events está em evolução: surgem novas propriedades e as antigas tornam-se obsoletas. A principal mudança nos últimos anos é o abandono dos códigos numéricos (keyCode / charCode / which) a favor de event.key e event.code. Todos os navegadores modernos suportam este par e deve construir a sua lógica com base neles.

O suporte dos navegadores é praticamente total: Chrome 51+, Firefox 29+, Safari 10.1+, Edge 79+. Se o seu projeto não estiver preso ao IE11, pode esquecer o event.which.

Três eventos: keydown, keypress e keyup

O navegador distingue três eventos de teclado. A ordem de disparo é fixa:

• keydown, a tecla é pressionada (momento do contacto);
• keypress, a tecla é mantida e gera um caractere (apenas para teclas de caractere);
• keyup, a tecla é libertada.

Subscrever o keydown via addEventListener:

1
const input = document.getElementById('type-here');
2
 
3
input.addEventListener('keydown', function (event) {
4
  console.log('Нажата:', event.key, '| Код:', event.code);
5
});

Para handlers inline, utilize um atributo do elemento:

1
<input type="text" id="type-here" onkeyup="handleKey(event)">

Se enviar o objeto de evento para a consola, verá a estrutura completa com todos os campos herdados de UIEvent e Event:

Porque é que o keydown é a escolha principal

O keypress está oficialmente reconhecido como obsoleto. Só é disparado para teclas que produzem um valor de caractere e não capta modificadores: nem Alt, nem Ctrl, nem Shift, nem Meta. Não é possível tratar Ctrl+Z ou Shift+Tab através do keypress.

A diferença entre keydown e keyup: o keydown é disparado antes de o navegador processar a tecla; o keyup é disparado depois. Daí decorre uma consequência importante: event.preventDefault() dentro de keydown cancela a ação do navegador (por exemplo, inserir um caractere num campo), mas dentro de keyup não. Para atalhos, validação de input e controlos de jogo, precisa do keydown.

Tabela de propriedades do KeyboardEvent

As três últimas linhas estão obsoletas. Sempre que possível, mude para event.key. Se tiver de suportar um navegador antigo, crie um fallback:

1
window.addEventListener('keydown', function (event) {
2
  const key = event.key !== undefined ? event.key : event.which;
3
  if (key !== undefined) {
4
    console.log('Клавиша:', key);
5
  }
6
});

Mas em 2026, esse código é apenas para projetos legados. O event.key funciona em todo o lado.

Teclas modificadoras e combinações

As teclas Control, Shift, Alt e Meta não executam ações por si mesmas, mas alteram o comportamento de outras teclas. Pressionar Z produz a letra «z», enquanto Ctrl+Z executa o comando desfazer.

As propriedades booleanas do evento ajudam a rastrear um modificador:

1
document.getElementById('editor').addEventListener('keydown', function (event) {
2
  if (event.ctrlKey && event.key === 'z') {
3
    event.preventDefault();
4
    undoAction();
5
  }
6
 
7
  if (event.ctrlKey && event.shiftKey && event.key === 'z') {
8
    event.preventDefault();
9
    redoAction();
10
  }
11
});

A mesma abordagem aplica-se a quaisquer combinações: Ctrl+S (guardar), Ctrl+Shift+N (nova janela), Alt+Tab (alternar). Verifique a ordem: primeiro os modificadores através de flags booleanas, depois event.key para a tecla específica. Isto torna a lógica legível, em vez de a afogar em códigos numéricos.

Tabela completa de códigos de teclas

Segue-se a tabela atual para todas as teclas padrão. Os valores event.key e event.code são apresentados tal como os navegadores modernos (Chrome, Firefox, Edge, Safari) os devolvem.

Navegação e ações

Linha numérica (teclado principal)

Letras A-Z

event.key devolve o valor em minúsculas para as letras. event.code não depende de maiúsculas/minúsculas nem do layout: KeyA significa a tecla física A, mesmo que o layout seja russo e o input seja «Ф».

Teclas especiais

Teclado numérico (Numpad)

Teclas de função

Sistema e multimédia

Pontuação e símbolos

Notas importantes da tabela

• event.which é uma propriedade obsoleta, utilize event.key.
• event.code é idêntico para letras minúsculas (a) e maiúsculas (A), é a tecla física. event.key devolve o caractere real considerando a capitalização.
• No Firefox, os valores de event.which para as teclas Equal, Semicolon e Minus diferem do Chrome/Edge/Safari (anotado na tabela). Outra razão para não usar event.which.
• Os navegadores baseados em Chromium e o Firefox devolvem event.key e event.code idênticos para todas as teclas listadas.
• Teclados virtuais: a especificação UI Events exige que um teclado virtual (móvel, no ecrã) que reproduza um layout padrão devolva o event.code correto. Na prática, os navegadores móveis (Chrome Android, Safari iOS) tratam corretamente keydown/keyup para as teclas principais, mas event.code pode estar vazio para layouts não padrão.

Treinador interativo

Para uma verificação rápida de qualquer código do artigo, utilize o treinador de teclado: keyevents.netlify.app. Mova o cursor para a área, pressione teclas e veja os valores de event.key, event.code e event.which, bem como o estado das flags dos modificadores em tempo real. O código-fonte está disponível no GitHub.

Vídeo: eventos de teclado na prática

Uma análise prática e breve do keydown e keyup, trabalho com modificadores e atalhos com exemplos ao vivo:

⁉️🤔 Perguntas frequentes

Qual é a diferença entre event.key e event.code?

event.key devolve o valor do caractere considerando o layout e a capitalização: para a tecla A é "a" (ou "A" com Shift), para o layout russo, "ф". event.code devolve o código físico da tecla, idêntico para todos os layouts: "KeyA". Para atalhos, event.code é mais fiável, não depende do idioma de entrada. Para entrada de texto, utilize event.key.

Porque é que o keypress já não é utilizado?

A especificação W3C marcou o keypress como obsoleto: só é disparado para teclas de caractere e não capta modificadores. Não é possível tratar Ctrl+C, Shift+Tab e outras combinações através do keypress. O keydown cobre todas as teclas e é suportado de forma idêntica em todos os navegadores modernos.

É possível abandonar completamente o event.which e o event.keyCode?

Sim, em 2026 é possível. O event.key é suportado no Chrome 51+, Firefox 29+, Safari 10.1+, Edge 79+. Se o seu projeto não tiver como alvo o IE11 ou o Firefox 28, utilize apenas event.key e event.code.

Como se trata uma pressão longa de tecla?

Combine keydown e keyup. No keydown inicie um temporizador ou requestAnimationFrame, no keyup reinicie-o. Para input de jogo, este é o padrão: tecla pressionada, personagem move-se; libertada, para.

Os eventos de teclado funcionam em dispositivos móveis?

O keydown e o keyup funcionam nos navegadores móveis quando se utiliza um teclado Bluetooth externo. O teclado no ecrã gera eventos input, não keydown/keyup para todas as teclas, pelo que para campos de texto em mobile é melhor usar o evento input.

Como se distingue o Shift esquerdo do direito?

Através de event.code: "ShiftLeft" ou "ShiftRight". event.key devolve "Shift" para ambos. O mesmo para Control, Alt e Meta.

O que usar no seu projeto

Se está a escrever código novo, adote o keydown como evento principal e, para identificação da tecla, event.key (símbolo) e event.code (tecla física). Esta combinação cobre todos os cenários: atalhos de teclado, navegação, input de jogo, validação de formulários.

Se mantém um produto com código legado em event.which ou event.keyCode, planeie uma refatoração. O volume de trabalho é pequeno: substituição nos handlers, mas o benefício é um código limpo e previsível, sem um zoológico de diferenças entre navegadores.

Guarde a tabela acima nos favoritos. Quando precisar novamente do código de uma tecla específica, abra-a e copie o valor event.code necessário, sem ter de recordar códigos numéricos da era do IE6.