KeyboardEvent
KeyboardEvent
オブジェクトは、キーボードによるユーザーの操作を示します。個々のイベントがユーザーとキーとの間の単一の操作 (または修飾キーとの組み合わせ) を表します。イベントの種類 (keydown (en-US)
, keypress (en-US)
, keyup (en-US)
) はキーボード操作が発生した種類を識別します。
KeyboardEvent
は、単にユーザーがキーボードのキーで行った操作が何であるかを低水準で示すものであり、その操作のその場面における意味は持ちません。テキストの入力を処理したい場合は、代わりに input
イベントを使用してください。ユーザーが他の種類のテキスト入力、例えば、タブレット端末やタブレット機器による手書き入力システムなどを使用している場合は、キーボードイベントが発生することはありません。コンストラクター
KeyboardEvent()
(en-US)KeyboardEvent
オブジェクトを生成します。
定数
KeyboardEvent
インターフェースは、以下の定数を定義しています。
Keyboard locations
以下の定数は、キーイベントがキーボードのどの部分から発信されるかを識別します。これらは、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
(en-US) 読取専用- そのキーイベントが発生した際に Alt (OS X の場合は Option または ⌥) キーが押されていれば
Boolean
true
を返します。
KeyboardEvent.code
読取専用- そのイベントが表すキーについて、キーのコード値を
DOMString
で返します。警告: これはユーザーのキーボード配列を無視しますので、ユーザーが QWERTY キーボード配列の "Y" の位置のキー (ホーム行の上の行の中ほど) を押すと、ユーザーが QWERTZ キーボード (ユーザーが "Z" だと思っており、その他のプロパティも "Z" を示している) や Dvorak キーボード配列 (ユーザーは "F" だと思っている) を使用していても、常に "KeyY" を返します。
KeyboardEvent.ctrlKey
(en-US) 読取専用- そのキーイベントが発生した際に Ctrl キーが押されていれば
Boolean
true
を返します。 KeyboardEvent.isComposing
読取専用- そのイベントが
compositionstart
とcompositionend
の間に発生したものであればBoolean
true
を返します。 KeyboardEvent.key
読取専用- イベントが表すキーのキー値を表す
DOMString
を返します。 KeyboardEvent.locale
読取専用- キーボードが設定されているロケールを示すロケール文字列を
DOMString
で返します。ブラウザやデバイスがキーボードのロケールを知らない場合は空文字列となります。メモ: このプロパティは入力データのロケールを表すことはありません。例えば、ユーザーが使用するキーボードレイアウトと入力テキストとで言語が異なる場合があります。 KeyboardEvent.location
(en-US)読取専用- キーボードなどの入力デバイス上のキーの位置を表す
Number
を返します。位置を特定する定数の一覧は、上記の Keyboard locations の中にあります。 KeyboardEvent.metaKey
(en-US) 読取専用Boolean
を返し、そのキーイベントが発生した際に Meta キー(Mac キーボードは ⌘ Command キー、 Windows キーボードは Windows キー ⊞ )が押されていればtrue
を返します。KeyboardEvent.repeat
(en-US) 読取専用Boolean
を返し、そのキーが自動的に繰り返し押下されていた場合にtrue
を返します。KeyboardEvent.shiftKey
(en-US) 読取専用Boolean
を返し、そのキーイベントが発生した際に Shift キーが押されていればtrue
を返します。
メソッド
このインターフェイスでは、親に相当する UIEvent
と Event
の両者からもメソッドを継承しています。
KeyboardEvent.getModifierState()
(en-US)- そのイベントが発生した際に修飾キー (Alt / Shift / Ctrl / Meta) が押されていたかどうかを表す
Boolean
を返します。
廃止されたメソッド
KeyboardEvent.initKeyEvent()
(en-US) DeprecatedKeyboardEvent
オブジェクトを初期化します。これは Firefox でのみ実装されていたもので、Firefox でもサポートされていないため、代わりにKeyboardEvent()
(en-US) コンストラクタを使用する必要があります。KeyboardEvent.initKeyboardEvent()
(en-US) DeprecatedKeyboardEvent
オブジェクトを初期化します。これは現在では非推奨です。代わりにKeyboardEvent()
(en-US) コンストラクタを使用する必要があります。
廃止されたプロパティ
KeyboardEvent.char
Non-Standard Deprecated 読取専用- キーの文字値を表す
DOMString
を返します。キーが印刷可能な文字に対応している場合、この値はその文字を含む空でない Unicode 文字列となります。キーが印刷可能な表現を持たない場合は、これは空の文字列です。注意: キーが複数の文字を挿入するマクロとして使用されている場合、この属性の値は最初の文字だけでなく文字列全体となります。 KeyboardEvent.charCode
(en-US) Deprecated 読取専用- キーの Unicode 参照番号を表す
Number
を返します。この属性は、keypress
イベントでのみ使用されます。char
属性が複数の文字を含むキーの場合、これはその属性の最初の文字の Unicode 値となります。Firefox 26 では、これは印刷可能な文字のコードを返します。警告: この属性は非推奨です。利用可能な場合は、代わりにKeyboardEvent.key
を使用する必要があります。 KeyboardEvent.keyCode
Deprecated 読取専用- 押されたキーの変更されていない値を示す、システムや実装に依存した数値コードを表す
Number
を返します。警告: この属性は非推奨です。利用可能な場合は、代わりにKeyboardEvent.key
を使用する必要があります。 KeyboardEvent.keyIdentifier
(en-US) Non-Standard Deprecated 読取専用- このプロパティは非標準であり、
KeyboardEvent.key
を支持して非推奨とされています。これは古いバージョンの DOM Level 3 Events の一部でした。 KeyboardEvent.keyLocation
Non-Standard Deprecated 読取専用- これは
KeyboardEvent.location
(en-US) の非標準の非推奨エイリアスです。これは古いバージョンの DOM Level 3 Events の一部でした。 KeyboardEvent.which
(en-US) Deprecated 読取専用- 押されたキーの変更されていない値を識別するシステムおよび実装依存の数値コードを表す
Number
を返します。これは通常keyCode
と同じです。警告: この属性は非推奨です。利用可能な場合は、代わりにKeyboardEvent.key
を使用する必要があります。
イベント
廃止されたイベント
keypress
(en-US)- 通常は文字値を生成するキーが押されました。このイベントはデバイス依存度が高く、時代遅れのものです。使用すべきではありません。
使用上の注意
イベントには keydown
/ keypress
/ keyup
の 3 種類があります。 Gecko ではほとんどのキーにおいて、以下のようにキーイベントが連続して発生します。
- そのキーが最初に押された時点で
keydown
イベントが発生します。 - そのキーが修飾キーでなかった場合、
keypress
イベントが発生します。 - ユーザがキーから指を離した時点で
keyup
イベントが発生します。
特殊な場合
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
イベントが発生していました。この矛盾する挙動は バグ 602812 で修正されました。
自動リピートの扱い
キーが押されたままになると自動リピートが始まります。これによって以下のようにイベントが連続して発生します。
keydown
keypress
keydown
keypress
- <<ユーザがキーから指を離すまで繰り返し>>
keyup
この流れは DOM Level 3 仕様書に定義されているものです。しかし、これには以下のような注意点があります。
Ubuntu 9.4 など一部の GTK 環境における自動リピート
GTK を用いた環境の中には、自動リピート時にネイティブの key-up イベントが発生するものがあります。このため、キーが連続して押されているのか自動リピートなのかを Gecko 側から認識することはできません。そのようなプラットフォームでの自動リピート時では、以下のようにキーイベントが連続して発生します。
keydown
keypress
keyup
keydown
keypress
keyup
- <<ユーザがキーから指を離すまで繰り返し>>
keyup
こういった環境では残念ながら、自動リピートなのか連続して押されているのかをウェブコンテンツ側から区別することはできません。
Gecko 5.0 以前の自動リピートの扱い
Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) 以前では、プラットフォーム間でキーボードのイベントハンドリングに差異が生じていました。
- Windows
- 自動リピートの挙動に関して Gecko 4.0 とそれ以降で変化はありません。
- Mac
- 最初に keydown イベントが発生した後、 keyup イベントが発生するまでは keypress イベントのみが発生します。断続的に keydown イベントが発生することはありません。
- Linux
- イベントの挙動はプラットフォームによって異なります。ネイティブのイベントモデルによって、 Windows のような挙動を示したり、 Mac のような挙動を示すものがあります。
メモ: 手動でイベントを発生させても、関連する既定のアクションは生じません。例えば、手動でキーイベントを発生させても、その文字がテキストとして入力されることはありません。このような UI イベントの挙動は、セキュリティを意識して設計されています。この設計により、ブラウザーとやり取りするユーザー操作をスクリプトが模倣できないようにしています。
例
<!DOCTYPE html>
<html>
<head>
<script>
'use strict';
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);
</script>
</head>
<body>
</body>
</html>
仕様書
KeyboardEvent
インターフェイスの草案は数多く提案されてきました。まず最初は DOM Events Level 2 でしたが意見がまとまらず破棄され、続いて DOM Events Level 3 が提案されました。これにより、非標準な初期化メソッドが実装されてしまいました (Gecko では DOM Events Level 2 の初期に定義されていた KeyboardEvent.initKeyEvent()
(en-US) が、他のブラウザでは DOM Events Level 3 の初期に定義されていた KeyboardEvent.initKeyboardEvent()
(en-US) です)。しかし両者のメソッドは、モダンなコンストラクターである KeyboardEvent()
(en-US) で置き換えられています。
ブラウザーの対応
BCD tables only load in the browser