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 キーはこのグループには該当せず、常に `DOM_KEY_LOCATION_STANDARD` の位置でエンコードされています。例としては、テンキーパッドの数字、キーパッドの 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): KeyboardEvent オブジェクトを初期化します。これは Firefox でのみ実装されていたもので、Firefox でもサポートされていないため、代わりに KeyboardEvent() (en-US) コンストラクタを使用する必要があります。
KeyboardEvent.initKeyboardEvent() (en-US): KeyboardEvent オブジェクトを初期化します。これは現在では非推奨です。代わりに KeyboardEvent() (en-US) コンストラクタを使用する必要があります。

廃止されたプロパティ

KeyboardEvent.char 読取専用: キーの文字値を表す DOMString を返します。キーが印刷可能な文字に対応している場合、この値はその文字を含む空でない Unicode 文字列となります。キーが印刷可能な表現を持たない場合は、これは空の文字列です。
注意: キーが複数の文字を挿入するマクロとして使用されている場合、この属性の値は最初の文字だけでなく文字列全体となります。
KeyboardEvent.charCode (en-US) 読取専用: キーの Unicode 参照番号を表す Number を返します。この属性は、keypress イベントでのみ使用されます。char 属性が複数の文字を含むキーの場合、これはその属性の最初の文字の Unicode 値となります。Firefox 26 では、これは印刷可能な文字のコードを返します。
警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。
KeyboardEvent.keyCode 読取専用: 押されたキーの変更されていない値を示す、システムや実装に依存した数値コードを表す Number を返します。
警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。
KeyboardEvent.keyIdentifier (en-US) 読取専用: このプロパティは非標準であり、KeyboardEvent.key を支持して非推奨とされています。これは古いバージョンの DOM Level 3 Events の一部でした。
KeyboardEvent.keyLocation 読取専用: これは KeyboardEvent.location (en-US) の非標準の非推奨エイリアスです。これは古いバージョンの DOM Level 3 Events の一部でした。
KeyboardEvent.which (en-US) 読取専用: 押されたキーの変更されていない値を識別するシステムおよび実装依存の数値コードを表す Number を返します。これは通常 keyCode と同じです。
警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。

イベント

以下のイベントは、KeyboardEvent 型に基づいています。これらのイベントは、Element、Document、および Window を含む GlobalEventHandlers を実装している任意のオブジェクトに配信することができます。以下のリストでは、各イベントは、そのイベントの Document ハンドラのドキュメントにリンクしています。

keydown: キーが押されました。
keyup: キーが離されました。

廃止されたイベント

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>

仕様書

仕様書	状態	備考
Document Object Model (DOM) Level 3 Events Specification KeyboardEvent の定義	廃止	初回定義

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

互換性のメモ

Firefox 65 では、 keypress イベントは印字可能キー以外では発生しなくなりました (バグ 968056)が、 Enter キー、 Shift + Enter キー、 Ctrl + Enter キーの組み合わせでは発生します (これらはブラウザー間の互換性の目的のために維持されています)。