KeyboardEvent

KeyboardEvent オブジェクトは、キーボードによるユーザーの操作を示します。個々のイベントがユーザーとキーとの間の単一の操作（または修飾キーとの組み合わせ）を表します。イベントの種類 (keydown, keypress, keyup) はキーボード操作が発生した種類を識別します。

メモ: KeyboardEvent は、単にユーザーがキーボードのキーで行った操作が何であるかを低水準で示すものであり、その操作のその場面における意味は持ちません。テキストの入力を処理したい場合は、代わりに input イベントを使用してください。ユーザーが他の種類のテキスト入力、例えば、タブレット端末やタブレット機器による手書き入力システムなどを使用している場合、キーボードイベントが発生することはありません。

Event UIEvent KeyboardEvent

コンストラクター

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 キーはこのグループには該当せず、常に位置を DOM_KEY_LOCATION_STANDARD として符号化されます。

例としては、テンキーの数字、テンキー側の Enter キー、テンキー側の小数点などがあります。

インスタンスプロパティ

このインターフェイスには、親である UIEvent および Event から継承したプロパティもあります。

KeyboardEvent.altKey 読取専用

論理値で、このキーイベントが発生した際に Alt （macOS の場合は Option または ⌥）キーが押されていれば true を返します。

KeyboardEvent.code 読取専用

文字列で、このイベントが表す物理キーのコード値を返します。

警告: これはユーザーのキーボードレイアウトを無視します。つまり、ユーザーが QWERTY キーボードレイアウトの "Y" の位置（ホーム行の上の行の中央付近）でキーを押した場合、ユーザーが QWERTZ キーボード（これはユーザーが "Z" を期待し、他のすべてのプロパティが "Z" を示すことになる）または Dvorak キーボードレイアウト（これはユーザーが "F" を期待する）であっても、常に "KeyY" を返します。ユーザーに正しいキーストロークを表示したい場合は、 Keyboard.getLayoutMap() (en-US) を使用してください。

KeyboardEvent.ctrlKey 読取専用

論理値で、そのキーイベントが発生した際に Ctrl キーが押されていれば true を返します。

KeyboardEvent.isComposing 読取専用

論理値で、このイベントが compositionstart と compositionend の間に発生したものであれば true を返します。

KeyboardEvent.key 読取専用

文字列で、このイベントが表すキーのキー値を表します。

KeyboardEvent.locale 読取専用

文字列で、キーボードに設定されているロケールを示すロケール文字列を返します。ブラウザーや端末がキーボードのロケールを知らない場合は空文字列となります。

メモ: このプロパティは入力データのロケールを表すわけではありません。例えば、ユーザーが使用するキーボードレイアウトと入力テキストとで言語が異なる場合があります。

KeyboardEvent.location 読取専用

数値で、キーボードなどの入力機器上のキーの位置を表す値を返します。位置を特定する定数の一覧は、上記のキーボード上の位置にあります。

KeyboardEvent.metaKey 読取専用

論理値で、このキーイベントが発生した際に Meta キー（Mac キーボードでは ⌘ Command キー、 Windows キーボードでは Windows キー (⊞)）が押されていれば true を返します。

KeyboardEvent.repeat 読取専用

論理値で、このキーが押し続けられて自動リピートしている場合に true を返します。

KeyboardEvent.shiftKey 読取専用

論理値で、このキーイベントが発生した際に Shift キーが押されていれば true を返します。

インスタンスメソッド

このインターフェイスには、親である UIEvent および Event から継承したメソッドもあります。

KeyboardEvent.getModifierState()

そのイベントが発生した際に修飾キー (Alt / Shift / Ctrl / Meta) が押されていたかどうかを表す論理値を返します。

廃止されたメソッド

KeyboardEvent.initKeyEvent()

KeyboardEvent オブジェクトを初期化します。これは Firefox でのみ実装されていたものですが、もう Firefox でも対応していません。代わりに KeyboardEvent() コンストラクターを使用してください。

KeyboardEvent.initKeyboardEvent()

KeyboardEvent オブジェクトを初期化します。これは非推奨になりました。代わりに KeyboardEvent() コンストラクターを使用してください。

廃止されたプロパティ

KeyboardEvent.char 読取専用

このキーの文字値を表す文字列を返します。キーが表示可能な文字に対応している場合、この値はその文字を含む空でない Unicode 文字列となります。キーが表示可能な表現を持たない場合は、これは空文字列です。

Note: If the key is used as a macro that inserts multiple characters, this property's value is the entire string, not just the first character.

KeyboardEvent.charCode 読取専用

このキーの Unicode 参照番号を表す数値を返します。この属性は、keypress イベントでのみ使用されます。 char 属性が複数の文字を含むキーの場合、これはその属性の最初の文字の Unicode 値となります。Firefox 26 では、これは表示可能な文字のコードを返します。

警告: この属性は非推奨です。可能であれば、代わりに KeyboardEvent.key を使用してください。

KeyboardEvent.keyCode 読取専用

押されたキーの修飾されていない値を示す、 システムや実装に依存した数値コードを数値で返します。

警告: この属性は非推奨です。可能であれば、代わりに KeyboardEvent.key を使用してください。

KeyboardEvent.keyIdentifier 読取専用

このプロパティは標準外であり、KeyboardEvent.key に置き換えられ非推奨になりました。これは DOM Level 3 Events の古い版に含まれていました。

KeyboardEvent.keyLocation 読取専用

これは KeyboardEvent.location の標準外で非推奨の別名です。これは DOM Level 3 Events の古い版に含まれていました。

KeyboardEvent.which (en-US) 読取専用

押されたキーの修飾されていない値を示す、 システムや実装に依存した数値コードを数値で返します。これは通常 keyCode と同じです。

警告: この属性は非推奨です。可能であれば、代わりに KeyboardEvent.key を使用してください。

イベント

以下のイベントは KeyboardEvent 型に基づいています。以下のリストでは、各イベントは、そのイベントの Element のハンドラーのドキュメントにリンクしおり、これは一般的にすべての宛先、例えば Element、Document、Window に適用されます。

keydown

キーが押されました。

keyup

キーが離されました。

廃止されたイベント

keypress

通常は文字値を生成するキーが押されました。このイベントは端末への依存度が高いため、廃止されました。使用すべきではありません。

使用上の注意

イベントには keydown, keypress, keyup の 3 種類があります。 Gecko ではほとんどのキーにおいて、以下のようにキーイベントが連続して発生します。

  1. そのキーが最初に押された時点で keydown イベントが発生します。
  2. そのキーが修飾キーでなかった場合、 keypress イベントが発生します。
  3. ユーザーがキーから指を離した時点で 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 イベントが発生していました。この矛盾する挙動は Firefox バグ 602812 で修正されました。

自動リピートの扱い

キーが押されたままになると自動リピートが始まります。これによって以下のようにイベントが連続して発生します。

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<ユーザーがキーから指を離すまで繰り返し>>
  6. keyup

この流れは DOM Level 3 仕様書に定義されているものです。しかし、これには以下のような注意点があります。

Ubuntu 9.4 など一部の GTK 環境における自動リピート

GTK を用いた環境の中には、自動リピート時にネイティブの key-up イベントが発生するものがあります。このため、キーが連続して押されているのか自動リピートなのかを Gecko 側から認識することはできません。そのようなプラットフォームでの自動リピート時では、以下のようにキーイベントが連続して発生します。

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. <<ユーザーがキーから指を離すまで繰り返し>>
  8. keyup

こういった環境では残念ながら、自動リピートなのか連打されただけなのかをウェブコンテンツ側から区別することはできません。

例

js

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 キーの組み合わせでは発生します (これらはブラウザー間の互換性の目的のために維持されています)。

関連情報