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

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

Fontes