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

CKTIS / JavaScript

Campos de KeyboardEvent: significado, posição e estado das teclas

Distingue o valor de uma tecla da sua posição física e consulta a repetição, o estado de Shift e a composição de texto. Estes campos de KeyboardEvent ajudam a tratar atalhos sem confundir a disposição do teclado com o texto introduzido.

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; event.code; event.repeat; event.shiftKey; event.isComposing

KeyboardEvent descreve eventos do teclado, como keydown e keyup. As cinco propriedades aqui descritas (key, code, repeat, shiftKey e isComposing) são só de leitura, mas algumas propriedades herdadas de Event, como cancelBubble, permitem escrita. KeyboardEvent.key é uma cadeia que indica o significado da tecla, tendo em conta a disposição e os modificadores, como "z", "Z" ou "Enter". KeyboardEvent.code é uma cadeia que identifica a posição física da tecla, independentemente da disposição: num teclado QWERTZ, "KeyY" pode acompanhar key: "Z". Utiliza key para o significado da tecla e code para controlos baseados na posição.

KeyboardEvent.repeat é um valor booleano: true indica a repetição automática de uma tecla mantida premida, não uma contagem de repetições. Num controlador keydown, if (event.repeat) return; pode ignorar ações repetidas. KeyboardEvent.shiftKey indica se Shift estava ativo quando ocorreu o evento; não significa que o próprio evento diga respeito a Shift. Ao premir uma tecla Shift (keydown), o valor é true; ao soltá-la (keyup), pode continuar a ser true se a outra tecla Shift ainda estiver premida.

KeyboardEvent.isComposing é um valor booleano que indica um evento entre compositionstart e compositionend, por exemplo, durante a composição de texto através de uma IME. Ignorar atalhos quando o valor é true reduz a interferência na composição, mas não deteta todos os casos-limite das IME: pode ser false no início ou no fim da composição. Os eventos do teclado não substituem o evento input para acompanhar alterações ao texto.

Estas são Web APIs do browser, não funcionalidades de uma edição específica de ECMAScript; o Node 24 no repositório não comprova a sua disponibilidade. Verifica a compatibilidade de cada propriedade nos browsers de destino; a MDN identifica repeat como Baseline 2025, o que não garante suporte em versões mais antigas. O exemplo cria um evento sintético com valores explícitos: verifica o acesso aos campos, não premir teclas reais nem o comportamento de uma IME.

Exemplos

(() => {
  const event = new KeyboardEvent("keydown", {
    key: "Z",
    code: "KeyY",
    repeat: true,
    shiftKey: true,
    isComposing: false
  });

  const { key, code, repeat, shiftKey, isComposing } = event;
  console.log(JSON.stringify({ key, code, repeat, shiftKey, isComposing }));
})();

Resultado

{"key":"Z","code":"KeyY","repeat":true,"shiftKey":true,"isComposing":false}

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