KeyboardEvent

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

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 11.666666666666666%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 70" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/Event" target="_top"><rect x="1" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="38.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Event</text></a><polyline points="76,25  86,20  86,30  76,25" stroke="#D4DDE4" fill="none"/><line x1="86" y1="25" x2="116" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/UIEvent" target="_top"><rect x="116" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="153.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">UIEvent</text></a><polyline points="191,25  201,20  201,30  191,25" stroke="#D4DDE4" fill="none"/><line x1="201" y1="25" x2="231" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/KeyboardEvent" target="_top"><rect x="231" y="1" width="130" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="296" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">KeyboardEvent</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

コンストラクター

KeyboardEvent()

KeyboardEvent オブジェクトを生成します。

定数

KeyboardEvent インターフェースは、以下の定数を定義しています。

Keyboard locations

以下の定数は、キーイベントがキーボードのどの部分から発信されるかを識別します。これらは、KeyboardEvent.DOM_KEY_LOCATION_STANDARD などとしてアクセスされます。

プロパティ

このインターフェイスでは、親に相当する UIEvent と Event の両者からもプロパティを継承しています。

KeyboardEvent.altKey 読取専用

そのキーイベントが発生した際に Alt (OS X の場合は Option または ⌥) キーが押されていれば Boolean true を返します。

KeyboardEvent.code 読取専用

そのイベントが表すキーについて、キーのコード値を DOMString で返します。

警告: これはユーザーのキーボード配列を無視しますので、ユーザーが QWERTY キーボード配列の "Y" の位置のキー (ホーム行の上の行の中ほど) を押すと、ユーザーが QWERTZ キーボード (ユーザーが "Z" だと思っており、その他のプロパティも "Z" を示している) や Dvorak キーボード配列 (ユーザーは "F" だと思っている) を使用していても、常に "KeyY" を返します。

KeyboardEvent.ctrlKey 読取専用

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

KeyboardEvent.isComposing 読取専用

そのイベントが compositionstart と compositionend の間に発生したものであれば Boolean true を返します。

KeyboardEvent.key 読取専用

イベントが表すキーのキー値を表す DOMString を返します。

KeyboardEvent.locale 読取専用

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

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

KeyboardEvent.location読取専用

キーボードなどの入力デバイス上のキーの位置を表す Number を返します。位置を特定する定数の一覧は、上記の Keyboard locations の中にあります。

KeyboardEvent.metaKey 読取専用

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

KeyboardEvent.repeat 読取専用

Boolean を返し、そのキーが自動的に繰り返し押下されていた場合に true を返します。

KeyboardEvent.shiftKey 読取専用

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

メソッド

このインターフェイスでは、親に相当する UIEvent と Event の両者からもメソッドを継承しています。

KeyboardEvent.getModifierState()

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

廃止されたメソッド

KeyboardEvent.initKeyEvent()

KeyboardEvent オブジェクトを初期化します。これは Firefox でのみ実装されていたもので、Firefox でもサポートされていないため、代わりに KeyboardEvent() コンストラクタを使用する必要があります。

KeyboardEvent.initKeyboardEvent()

KeyboardEvent オブジェクトを初期化します。これは現在では非推奨です。代わりに KeyboardEvent() コンストラクタを使用する必要があります。

廃止されたプロパティ

KeyboardEvent.char 読取専用

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

注意: キーが複数の文字を挿入するマクロとして使用されている場合、この属性の値は最初の文字だけでなく文字列全体となります。

KeyboardEvent.charCode 読取専用

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

警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。

KeyboardEvent.keyCode 読取専用

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

警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。

KeyboardEvent.keyIdentifier 読取専用

このプロパティは非標準であり、KeyboardEvent.key を支持して非推奨とされています。これは古いバージョンの DOM Level 3 Events の一部でした。

KeyboardEvent.keyLocation 読取専用

これは KeyboardEvent.location の非標準の非推奨エイリアスです。これは古いバージョンの DOM Level 3 Events の一部でした。

KeyboardEvent.which 読取専用

押されたキーの変更されていない値を識別するシステムおよび実装依存の数値コードを表す Number を返します。これは通常 keyCode と同じです。

警告: この属性は非推奨です。利用可能な場合は、代わりに KeyboardEvent.key を使用する必要があります。

イベント

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

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 イベントのみが発生します。

しかし 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 で修正されました。

自動リピートの扱い

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

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

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

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() が、他のブラウザでは DOM Events Level 3 の初期に定義されていた KeyboardEvent.initKeyboardEvent() です)。しかし両者のメソッドは、モダンなコンストラクターである KeyboardEvent() で置き換えられています。

ブラウザーの対応

互換性のメモ

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

関連情報

• KeyboardEvent.code.
• KeyboardEvent.key.
• KeyboardEvent.getModifierState()