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