CKTIS / JavaScript
KeyboardEvent: valor da tecla e estado da composição
Usa `key` para reconhecer o valor da tecla e `isComposing` para evitar ativar um atalho enquanto um método de introdução ainda está a compor texto.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
event.key // string, read-only
event.isComposing // boolean, read-only
// event is a KeyboardEvent instance.
// To construct a synthetic event:
new KeyboardEvent("keydown", { key: "Enter", isComposing: true })event.key e event.isComposing são propriedades só de leitura de uma instância de KeyboardEvent. Fazem parte da plataforma Web, não do ECMAScript 2024, e o seu suporte depende do ambiente de execução.
key é uma cadeia de caracteres que tem em conta a disposição do teclado e as teclas modificadoras, por exemplo "a" ou "A" com Shift numa disposição comum. As teclas especiais têm valores predefinidos, como "Enter" e "Escape". Se o navegador não identificar a tecla, devolve "Unidentified". Ao contrário de code, key não descreve a posição física da tecla. Para detetar alterações ao texto, escuta o evento input em vez de reconstruíres o texto a partir das teclas premidas.
isComposing é um valor booleano associado a cada evento. Num evento gerado pelo navegador, é true se o evento ocorrer depois de compositionstart e antes de compositionend. Um editor de método de introdução (IME) pode usar Enter para aceitar uma sugestão de texto. Por isso, na função que trata keydown, não atives o atalho se isComposing for true.
No início ou no fim da composição, a ordem dos eventos pode fazer com que isComposing seja false, mesmo que o IME processe a tecla. Testa as combinações de navegador e IME que pretendes suportar. Se necessário, considera event.keyCode === 229 como solução de compatibilidade obsoleta, não como garantia universal.
Exemplos
{
const shouldRunShortcut = (event) =>
event.key === "Enter" && !event.isComposing;
for (const options of [
{ key: "Enter", isComposing: true },
{ key: "Enter", isComposing: false },
{ key: "Escape", isComposing: false },
]) {
// Without KeyboardEvent, test the predicate with a plain object.
const event = typeof KeyboardEvent === "function"
? new KeyboardEvent("keydown", options)
: options;
console.log(shouldRunShortcut(event) ? "run" : "skip");
}
}Resultado
skip run skip
Executa o exemplo com Node.js ou na consola de um navegador compatível. Se `KeyboardEvent` não estiver disponível, o exemplo usa objetos simples com os mesmos valores de teste. Só Enter fora da composição escreve `run` na consola. O exemplo não despacha eventos nem ativa um IME real.
Lições relacionadas
- JavaScript · Lição 41 · Intermédio · Versão: 3