Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

KeyboardEvent.code — tecla física em vez de carácter

KeyboardEvent.code identifica a posição física de uma tecla independentemente da disposição do teclado e dos modificadores. Saiba em que diferem code e key e quando a introdução de texto e os teclados virtuais exigem outra abordagem.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

event.code

KeyboardEvent.code é uma propriedade só de leitura que devolve um identificador de tecla física sob a forma de uma cadeia de caracteres. Leia-a através de event.code, por exemplo, num processador keydown ou keyup. Faz parte da Web API UI Events, não do próprio ECMAScript.

Nomes como KeyQ, Digit2 e ShiftLeft descrevem posições das teclas, não os caracteres escritos. KeyQ identifica a posição da tecla Q na disposição dos EUA, mesmo que outra disposição associe uma letra diferente a essa posição. ShiftLeft e ShiftRight distinguem os lados do teclado.

Ao contrário de code, key descreve o significado da tecla tendo em conta a disposição e os modificadores. Escolha code para controlos baseados na posição e key para o significado da tecla. Para observar a edição de texto, use input em vez de reconstruir texto a partir de códigos de teclas.

O valor predefinido de code é "". Os teclados virtuais nem sempre têm um equivalente inequívoco a uma posição física. Teste os navegadores e dispositivos pretendidos; a presença do Node 24 não comprova o suporte desta API do navegador.

O exemplo define explicitamente code e key em eventos sintéticos. Mostra dois significados diferentes com o mesmo code; não testa o mapeamento de um teclado real nem simula o premir de uma tecla física.

Exemplos

const events = [
  new KeyboardEvent("keydown", { code: "KeyQ", key: "q" }),
  new KeyboardEvent("keydown", { code: "KeyQ", key: "Q", shiftKey: true })
];

for (const event of events) {
  console.log(`${event.code} | ${event.key} | ${event.shiftKey}`);
}

Resultado

KeyQ | q | false
KeyQ | Q | true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes