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

CKTIS / JavaScript

KeyboardEvent.key — o significado de uma tecla

KeyboardEvent.key é uma propriedade de cadeia de caracteres, só de leitura, que descreve o significado de uma tecla. Tem em conta a disposição do teclado e os modificadores; ao contrário de code, não descreve a posição física da tecla.

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.key

KeyboardEvent.key, lido como event.key, devolve uma cadeia de caracteres que descreve o significado de uma tecla. Para caracteres imprimíveis, tem em conta a disposição do teclado e os modificadores, por exemplo "a" ou "A". A propriedade é só de leitura.

UI Events agrupa os valores com nome das teclas em várias categorias: "Enter" figura entre as teclas associadas a caracteres de espaço em branco, "Escape" entre as teclas da interface de utilizador e "ArrowDown" entre as teclas de navegação. A barra de espaços tem o valor " ", não "Space". "Dead" identifica uma tecla morta usada para compor caracteres, enquanto "Unidentified" significa que não foi possível identificar a tecla. As comparações de cadeias distinguem maiúsculas de minúsculas.

Use key quando o significado da tecla for importante e code quando for importante a sua posição física. Não considere os eventos de teclado um registo completo da introdução de texto; para a edição, considere os eventos beforeinput e input.

Esta é uma API Web do navegador definida em UI Events, não uma funcionalidade de uma edição específica do ECMAScript. A presença do Node 24 não comprova a sua compatibilidade. O exemplo define explicitamente key e code: o construtor não calcula key a partir de code ou shiftKey. Testa o acesso aos valores, não um teclado real; a compatibilidade nos navegadores de destino deve ser verificada separadamente.

Exemplos

const events = [
  new KeyboardEvent("keydown", { key: "a", code: "KeyA" }),
  new KeyboardEvent("keydown", { key: "A", code: "KeyA", shiftKey: true }),
  new KeyboardEvent("keydown", { key: "Enter", code: "Enter" })
];

console.log(events.map(event => `${event.key}:${event.code}`).join("\n"));

Resultado

a:KeyA
A:KeyA
Enter:Enter

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