KeyboardEvent
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
KeyboardEvent
オブジェクトは、キーボードによるユーザーの操作を示します。個々のイベントがユーザーとキーとの間の単一の操作(または修飾キーとの組み合わせ)を表します。イベントの種類 (keydown
, keypress
, keyup
) はキーボード操作が発生した種類を識別します。
メモ: KeyboardEvent
は、単にユーザーがキーボードのキーで行った操作が何であるかを低水準で示すものであり、その操作のその場面における意味は持ちません。テキストの入力を処理したい場合は、代わりに input
イベントを使用してください。ユーザーが他の種類のテキスト入力、例えば、タブレット端末やタブレット機器による手書き入力システムなどを使用している場合、キーボードイベントが発生することはありません。
コンストラクター
KeyboardEvent()
-
KeyboardEvent
オブジェクトを生成します。
定数
KeyboardEvent
インターフェイスは、以下の定数を定義しています。
キーボード上の位置
以下の定数は、キーイベントがキーボードのどの部分から発生したかを識別します。これらは、 KeyboardEvent.DOM_KEY_LOCATION_STANDARD
などとしてアクセスされます。
定数 | 値 | 説明 |
---|---|---|
DOM_KEY_LOCATION_STANDARD |
0x00 |
このイベントによって記述されたキーは、キーボードの特定の範囲にあるものではないことを表します。テンキー上にあるわけでもなく(NumLock キーでない限り)、キーボードの左右で重複しているキーについては、何らかの理由でその位置と関連付けないことになっています。 例としては、標準的な PC 101 US キーボードの英数字キー、 NumLock キー、スペースバーなどがあります。 |
DOM_KEY_LOCATION_LEFT |
0x01 |
このキーは、キーボード上の複数の位置に存在する可能性があるものであり、この場合は、キーボードの左側にあるものです。 例としては、左の Ctrl キー、 Macintosh キーボードの左の Command キー、左の Shift キーなどがあります。 |
DOM_KEY_LOCATION_RIGHT |
0x02 |
このキーは、キーボード上の複数の位置に存在する可能性があるものであり、この場合は、キーボードの右側にあるものです。 例としては、右の Shift キーや右の Alt キー(Mac キーボードの Option キー)などがあります。 |
DOM_KEY_LOCATION_NUMPAD |
0x03 |
このキーは、テンキー上に配置されているか、キーが複数の場所から発信される場合は、テンキーに関連付けられた仮想キーとなります。 NumLock キーはこのグループには該当せず、常に位置を 例としては、テンキーの数字、テンキー側の Enter キー、テンキー側の小数点などがあります。 |
インスタンスプロパティ
このインターフェイスには、親である UIEvent
および Event
から継承したプロパティもあります。
KeyboardEvent.altKey
読取専用-
論理値で、このキーイベントが発生した際に Alt (macOS の場合は Option または ⌥)キーが押されていれば
true
を返します。 KeyboardEvent.code
読取専用-
文字列で、このイベントが表す物理キーのコード値を返します。
警告: これはユーザーのキーボードレイアウトを無視します。つまり、ユーザーが QWERTY キーボードレイアウトの "Y" の位置(ホーム行の上の行の中央付近)でキーを押した場合、ユーザーが QWERTZ キーボード(これはユーザーが "Z" を期待し、他のすべてのプロパティが "Z" を示すことになる)または Dvorak キーボードレイアウト(これはユーザーが "F" を期待する)であっても、常に "KeyY" を返します。ユーザーに正しいキーストロークを表示したい場合は、
Keyboard.getLayoutMap()
を使用してください。 KeyboardEvent.ctrlKey
読取専用-
論理値で、そのキーイベントが発生した際に Ctrl キーが押されていれば
true
を返します。 KeyboardEvent.isComposing
読取専用-
論理値で、このイベントが
compositionstart
とcompositionend
の間に発生したものであればtrue
を返します。 KeyboardEvent.key
読取専用-
文字列で、このイベントが表すキーのキー値を表します。
KeyboardEvent.location
読取専用-
数値で、キーボードなどの入力機器上のキーの位置を表す値を返します。位置を特定する定数の一覧は、上記のキーボード上の位置にあります。
KeyboardEvent.metaKey
読取専用-
論理値で、このキーイベントが発生した際に Meta キー(Mac キーボードでは ⌘ Command キー、 Windows キーボードでは Windows キー (⊞))が押されていれば
true
を返します。 KeyboardEvent.repeat
読取専用-
論理値で、このキーが押し続けられて自動リピートしている場合に
true
を返します。 KeyboardEvent.shiftKey
読取専用-
論理値で、このキーイベントが発生した際に Shift キーが押されていれば
true
を返します。
古いプロパティ
KeyboardEvent.charCode
非推奨; 読取専用-
キーの Unicode 参照番号を表す数値を返します。このプロパティは
keypress
イベントでのみ使用されます。char
プロパティが複数の文字を含むキーの場合、これはそのプロパティの最初の文字の Unicode 値です。Firefox 26 では、表示可能な文字のコードが返されます。 KeyboardEvent.keyCode
非推奨; 読取専用-
押されたキーの修飾されていない値を識別する、システムおよび実装に依存する数値コードを表す数値を返します。
KeyboardEvent.keyIdentifier
非標準 非推奨; 読取専用-
このプロパティは標準外であり、
KeyboardEvent.key
に置き換えられて非推奨とされています。これは、DOM Level 3 Events の古い版に含まれていました。
インスタンスメソッド
このインターフェイスには、親である UIEvent
および Event
から継承したメソッドもあります。
KeyboardEvent.getModifierState()
-
そのイベントが発生した際に修飾キー (Alt / Shift / Ctrl / Meta) が押されていたかどうかを表す論理値を返します。
古いメソッド
KeyboardEvent.initKeyEvent()
非推奨;-
KeyboardEvent
オブジェクトを初期化します。これは Firefox でのみ実装されていたものですが、もう Firefox でも対応していません。代わりにKeyboardEvent()
コンストラクターを使用してください。 KeyboardEvent.initKeyboardEvent()
非推奨;-
KeyboardEvent
オブジェクトを初期化します。これは非推奨になりました。代わりにKeyboardEvent()
コンストラクターを使用してください。
イベント
古いイベント
keypress
非推奨;-
通常は文字値を生成するキーが押されました。このイベントは端末への依存度が高いため、廃止されました。使用すべきではありません。
使用上の注意
特殊な場合
Caps Lock や Num Lock、 Scroll Lock などのキーは LED 表示も切り替わります。 Windows と Linux では、このようなキーは keydown
と keyup
イベントのみが発生します。
メモ:
Linux の Firefox 12 以前では keypress
イベントも発生していました。
しかし Mac OS X のイベントモデルに関する制約から、Mac OS X の Caps Lock は keydown
イベントのみが発生します。(2007 年モデル以前の)ノート型では Num Lock にも対応していましたが、今日の Mac OS X では外部キーボードにおいても Num Lock に対応していません。 Num Lock キーがある古い MacBook 上では、Num Lock キーによってイベントは何も発生しません。また、 F14 キーが接続されている外部キーボードであれば、 Gecko は Scroll Lock に対応しています。古い特定のバージョンの Firefox では、このキーによって keypress
イベントが発生していました。この矛盾する挙動は Firefox バグ 602812 で修正されました。
自動リピートの扱い
キーが押されたままになると自動リピートが始まります。これによって以下のようにイベントが連続して発生します。
keydown
keypress
keydown
keypress
- <<ユーザーがキーから指を離すまで繰り返し>>
keyup
この流れは DOM Level 3 仕様書に定義されているものです。しかし、これには以下のような注意点があります。
Ubuntu 9.4 など一部の GTK 環境における自動リピート
GTK を用いた環境の中には、自動リピート時にネイティブの key-up イベントが発生するものがあります。このため、キーが連続して押されているのか自動リピートなのかを Gecko 側から認識することはできません。そのようなプラットフォームでの自動リピート時では、以下のようにキーイベントが連続して発生します。
keydown
keypress
keyup
keydown
keypress
keyup
- <<ユーザーがキーから指を離すまで繰り返し>>
keyup
こういった環境では残念ながら、自動リピートなのか連打されただけなのかをウェブコンテンツ側から区別することはできません。
例
document.addEventListener(
"keydown",
(event) => {
const keyName = event.key;
if (keyName === "Control") {
// do not alert when only Control key is pressed.
return;
}
if (event.ctrlKey) {
// Even though event.key is not 'Control' (e.g., 'a' is pressed),
// event.ctrlKey may be true if Ctrl key is pressed at the same time.
alert(`Combination of ctrlKey + ${keyName}`);
} else {
alert(`Key pressed ${keyName}`);
}
},
false,
);
document.addEventListener(
"keyup",
(event) => {
const keyName = event.key;
// As the user releases the Ctrl key, the key is no longer active,
// so event.ctrlKey is false.
if (keyName === "Control") {
alert("Control key was released");
}
},
false,
);
仕様書
Specification |
---|
UI Events # interface-keyboardevent |
KeyboardEvent
インターフェイスの草案は数多く提案されてきました。まず最初は DOM Events Level 2 でしたが意見がまとまらず破棄され、続いて DOM Events Level 3 が提案されました。これにより、標準外な初期化メソッドが実装されてしまいました (Gecko では DOM Events Level 2 の初期に定義されていた KeyboardEvent.initKeyEvent()
が、他のブラウザーでは DOM Events Level 3 の初期に定義されていた KeyboardEvent.initKeyboardEvent()
です)。しかし両者のメソッドは、現代的なコンストラクターである KeyboardEvent()
で置き換えられてました。
ブラウザーの互換性
BCD tables only load in the browser
互換性のメモ
- Firefox 65 では、
keypress
イベントは表示可能でないキーでは発生しなくなりました(Firefox バグ 968056)が、 Enter キー、 Shift + Enter キー、 Ctrl + Enter キーの組み合わせでは発生します (これらはブラウザー間の互換性の目的のために維持されています)。