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 オブジェクトを生成します。

メソッド

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

KeyboardEvent.getModifierState()

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

KeyboardEvent.initKeyEvent()

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

KeyboardEvent.initKeyboardEvent()

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

プロパティ

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

KeyboardEvent.altKey 読取専用

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

KeyboardEvent.char 読取専用

そのキーに該当する文字を表した DOMString を返します。そのキーに該当する文字が印字可能なものであれば、この値はその文字を含んだ空でない Unicode 文字列になります。逆に印字可能ではなかった場合、空文字列となります。

メモ: そのキーが複数の文字を挿入するマクロの働きをする場合、属性値は最初の 1 文字目だけではなく、文字列全体となります。

KeyboardEvent.charCode 読取専用

そのキーに該当する Unicode 参照番号を Number で返します。このプロパティは keypress イベントでのみ用いられます。 char プロパティが複数の文字を含むキーについては、最初の 1 文字目にあたる Unicode 値が charCode プロパティで取得できます。 Firefox 26 からは、印字可能な文字に対してコード値を返すようになっています。

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

KeyboardEvent.code 読取専用

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

KeyboardEvent.ctrlKey 読取専用

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

KeyboardEvent.isComposing 読取専用

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

KeyboardEvent.key 読取専用

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

KeyboardEvent.keyCode 読取専用

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

警告: このプロパティは廃止されたため、可能であれば KeyboardEvent.key を代わりに使用してください。

KeyboardEvent.keyIdentifier 読取専用

このプロパティは非標準であり、KeyboardEvent.key へ移行するため廃止されました。なお、このプロパティは DOM Level 3 Events の古い仕様に含まれていました。

KeyboardEvent.keyLocation 読取専用

このプロパティは KeyboardEvent.location の非標準なエイリアスでしたが、すでに廃止されました。なお、このプロパティは DOM Level 3 Events の古い仕様に含まれていました。

KeyboardEvent.locale 読取専用

DOMString を返し、キーボードに設定されているロケールを表します。ブラウザかデバイスがキーボードのロケールを知らなかった場合、この戻り値は空文字列となることがあります。

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

KeyboardEvent.location読取専用

Number を返し、キーボードや他の入力デバイス上におけるキーの位置を表します。

KeyboardEvent.metaKey 読取専用

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

KeyboardEvent.repeat 読取専用

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

KeyboardEvent.shiftKey 読取専用

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

KeyboardEvent.which 読取専用

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

メモ: このプロパティは非推奨です。可能であれば KeyboardEvent.key を代わりに使用してください。

使用上の注意

イベントには 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()