CKTIS / JavaScript
Pola KeyboardEvent: znaczenie klawisza, pozycja i stan
Rozróżniaj wartość klawisza od jego fizycznej pozycji oraz odczytuj powtarzanie, stan Shift i kompozycję tekstu. Te pola KeyboardEvent pomagają obsługiwać skróty bez mylenia układu klawiatury z wprowadzanym tekstem.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
event.key; event.code; event.repeat; event.shiftKey; event.isComposingKeyboardEvent opisuje zdarzenia klawiatury, takie jak keydown i keyup. Pięć omawianych tu właściwości (key, code, repeat, shiftKey i isComposing) jest tylko do odczytu, ale niektóre właściwości dziedziczone z Event, np. cancelBubble, można zapisywać. KeyboardEvent.key jest ciągiem określającym znaczenie klawisza z uwzględnieniem układu i modyfikatorów, np. "z", "Z" lub "Enter". KeyboardEvent.code jest ciągiem identyfikującym fizyczną pozycję klawisza, niezależnie od układu: "KeyY" może towarzyszyć key: "Z" na klawiaturze QWERTZ. Do znaczenia klawisza używaj key, a do sterowania zależnego od pozycji — code.
KeyboardEvent.repeat jest wartością logiczną: true oznacza automatyczne powtarzanie przytrzymanego klawisza, a nie licznik powtórzeń. W obsłudze keydown warunek if (event.repeat) return; może pomijać powtórzenia akcji. KeyboardEvent.shiftKey wskazuje, czy Shift był aktywny w chwili zdarzenia; nie oznacza, że samo zdarzenie dotyczy Shift. Przy naciśnięciu klawisza Shift (keydown) wartość wynosi true; przy zwolnieniu tego klawisza (keyup) może nadal wynosić true, jeśli drugi klawisz Shift jest wciąż wciśnięty.
KeyboardEvent.isComposing jest wartością logiczną wskazującą zdarzenie między compositionstart a compositionend, np. podczas kompozycji tekstu przez IME. Pomijanie skrótów, gdy ma wartość true, ogranicza zakłócanie kompozycji, ale nie wykrywa wszystkich przypadków granicznych IME: na początku lub końcu kompozycji może wynosić false. Zdarzenia klawiatury nie zastępują zdarzenia input do śledzenia zmian tekstu.
To przeglądarkowe Web APIs, a nie funkcje określonej edycji ECMAScript; Node 24 w repozytorium nie potwierdza ich dostępności. Sprawdzaj zgodność każdej właściwości z docelowymi przeglądarkami; MDN oznacza repeat jako Baseline 2025, co nie gwarantuje obsługi w starszych wersjach. Przykład tworzy zdarzenie syntetyczne z jawnymi wartościami: sprawdza odczyt pól, nie rzeczywiste naciskanie klawiszy ani zachowanie IME.
Przykłady
(() => {
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 }));
})();Wynik
{"key":"Z","code":"KeyY","repeat":true,"shiftKey":true,"isComposing":false}Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.