KeyboardEvent オブジェクトは、キーボードによるユーザーの操作を示します。個々のイベントがユーザーとキーとの間の単一の操作 (または修飾キーとの組み合わせ) を表します。イベントの種類 ({{event('keydown')}}, {{event('keypress')}}, {{event('keyup')}}) はキーボード操作が発生した種類を識別します。
KeyboardEvent は、単にユーザーがキーボードのキーで行った操作が何であるかを低水準で示すものであり、その操作のその場面における意味は持ちません。テキストの入力を処理したい場合は、代わりに {{event("input")}} イベントを使用してください。ユーザーが他の種類のテキスト入力、例えば、タブレット端末やタブレット機器による手書き入力システムなどを使用している場合は、キーボードイベントが発生することはありません。{{InheritanceDiagram}}
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 キー、キーパッドの小数点などがあります。 |
このインターフェイスでは、親に相当する {{domxref("UIEvent")}} と {{domxref("Event")}} の両者からもプロパティを継承しています。
true を返します。true を返します。compositionstart と compositionend の間に発生したものであれば {{jsxref("Boolean")}} true を返します。true を返します。true を返します。true を返します。このインターフェイスでは、親に相当する {{domxref("UIEvent")}} と {{domxref("Event")}} の両者からもメソッドを継承しています。
KeyboardEvent オブジェクトを初期化します。これは Firefox でのみ実装されていたもので、Firefox でもサポートされていないため、代わりに {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} コンストラクタを使用する必要があります。KeyboardEvent オブジェクトを初期化します。これは現在では非推奨です。代わりに {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} コンストラクタを使用する必要があります。keypress イベントでのみ使用されます。char 属性が複数の文字を含むキーの場合、これはその属性の最初の文字の Unicode 値となります。Firefox 26 では、これは印刷可能な文字のコードを返します。
keyCode と同じです。
以下のイベントは、KeyboardEvent 型に基づいています。これらのイベントは、{{domxref("Element")}}、{{domxref("Document")}}、および {{domxref("Window")}} を含む {{domxref("GlobalEventHandlers")}} を実装している任意のオブジェクトに配信することができます。以下のリストでは、各イベントは、そのイベントの Document ハンドラのドキュメントにリンクしています。
イベントには 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 イベントが発生していました。この矛盾する挙動は {{bug(602812)}} で修正されました。
キーが押されたままになると自動リピートが始まります。これによって以下のようにイベントが連続して発生します。
keydownkeypresskeydownkeypresskeyupこの流れは DOM Level 3 仕様書に定義されているものです。しかし、これには以下のような注意点があります。
GTK を用いた環境の中には、自動リピート時にネイティブの key-up イベントが発生するものがあります。このため、キーが連続して押されているのか自動リピートなのかを Gecko 側から認識することはできません。そのようなプラットフォームでの自動リピート時では、以下のようにキーイベントが連続して発生します。
keydownkeypresskeyupkeydownkeypresskeyupkeyupこういった環境では残念ながら、自動リピートなのか連続して押されているのかをウェブコンテンツ側から区別することはできません。
Gecko 5.0 {{geckoRelease('5.0')}} 以前では、プラットフォーム間でキーボードのイベントハンドリングに差異が生じていました。
メモ: 手動でイベントを発生させても、関連する既定のアクションは生じません。例えば、手動でキーイベントを発生させても、その文字がテキストとして入力されることはありません。このような 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>
| 仕様書 | 状態 | 備考 |
|---|---|---|
| {{SpecName('DOM3 Events', '#interface-keyboardevent', 'KeyboardEvent')}} | {{Spec2('DOM3 Events')}} | 初回定義 |
KeyboardEvent インターフェイスの草案は数多く提案されてきました。まず最初は DOM Events Level 2 でしたが意見がまとまらず破棄され、続いて DOM Events Level 3 が提案されました。これにより、非標準な初期化メソッドが実装されてしまいました (Gecko では DOM Events Level 2 の初期に定義されていた {{domxref("KeyboardEvent.initKeyEvent()")}} が、他のブラウザでは DOM Events Level 3 の初期に定義されていた {{domxref("KeyboardEvent.initKeyboardEvent()")}} です)。しかし両者のメソッドは、モダンなコンストラクターである {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} で置き換えられています。
{{Compat("api.KeyboardEvent")}}
keypress イベントは印字可能キー以外では発生しなくなりました ({{bug(968056)}})が、 Enter キー、 Shift + Enter キー、 Ctrl + Enter キーの組み合わせでは発生します (これらはブラウザー間の互換性の目的のために維持されています)。