KeyboardEvent

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

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

コンストラクター

KeyboardEvent()
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 キー、キーパッドの小数点などがあります。

プロパティ

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

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 読取専用
そのイベントが compositionstartcompositionend の間に発生したものであれば 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 を返します。

メソッド

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

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 型に基づいています。これらのイベントは、ElementDocument、および 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 では keydownkeyup イベントのみが発生します。

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

自動リピートの扱い

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

  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>

仕様書

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

ブラウザーの対応

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
KeyboardEventChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1.5IE 完全対応 9Opera 完全対応 12.1Safari 完全対応 3.1WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 12.1Safari iOS 完全対応 2Samsung Internet Android 完全対応 1.0
DOM_KEY_LOCATION_LEFTChrome 完全対応 ありEdge 完全対応 ≤18Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
DOM_KEY_LOCATION_NUMPADChrome 完全対応 ありEdge 完全対応 ≤18Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
DOM_KEY_LOCATION_RIGHTChrome 完全対応 ありEdge 完全対応 ≤18Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
DOM_KEY_LOCATION_STANDARDChrome 完全対応 ありEdge 完全対応 ≤18Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
KeyboardEvent() constructorChrome 完全対応 ありEdge 完全対応 ≤79Firefox 完全対応 31IE 未対応 なしOpera 完全対応 ありSafari ? WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 31Opera Android 完全対応 ありSafari iOS ? Samsung Internet Android 完全対応 あり
altKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
charCode
非推奨非標準
Chrome 完全対応 26Edge 完全対応 12Firefox 完全対応 3IE 完全対応 9Opera 完全対応 12.1Safari 完全対応 5.1WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 5.1Samsung Internet Android 完全対応 あり
codeChrome 完全対応 48Edge 完全対応 79Firefox 完全対応 38IE 未対応 なしOpera 完全対応 35Safari 完全対応 10WebView Android 完全対応 48Chrome Android 完全対応 48Firefox Android 完全対応 38Opera Android 完全対応 35Safari iOS 完全対応 10Samsung Internet Android 完全対応 5.0
ctrlKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
getModifierStateChrome 完全対応 31Edge 完全対応 12Firefox 完全対応 15IE 完全対応 9Opera 完全対応 17Safari 完全対応 10.1WebView Android 完全対応 4.4.3Chrome Android 完全対応 31Firefox Android 完全対応 15Opera Android 完全対応 18Safari iOS 完全対応 10.3Samsung Internet Android 完全対応 2.0
isComposingChrome 完全対応 56Edge 完全対応 ≤79Firefox 完全対応 31IE 未対応 なしOpera 完全対応 43Safari 完全対応 10.1WebView Android 完全対応 56Chrome Android 完全対応 56Firefox Android 完全対応 31Opera Android 完全対応 43Safari iOS 完全対応 10.3Samsung Internet Android 完全対応 6.0
keyChrome 完全対応 51Edge 完全対応 12Firefox 完全対応 23IE 完全対応 9
補足
完全対応 9
補足
補足 IE's implementation does not completely match the current spec because it is based on an older version of the spec.
Opera 完全対応 38Safari 完全対応 10WebView Android 完全対応 51Chrome Android 完全対応 51Firefox Android 完全対応 23Opera Android 完全対応 41Safari iOS 完全対応 10Samsung Internet Android 完全対応 5.0
keyCode
非推奨非標準
Chrome 完全対応 26Edge 完全対応 12Firefox 完全対応 3IE 完全対応 9Opera 完全対応 12.1Safari 完全対応 5WebView Android 完全対応 ≤37Chrome Android 完全対応 26Firefox Android 完全対応 4Opera Android 完全対応 12.1Safari iOS 完全対応 5.1Samsung Internet Android 完全対応 1.5
keyIdentifier
非推奨非標準
Chrome 未対応 26 — 54Edge ? Firefox 未対応 なしIE 未対応 なしOpera 未対応 15 — 41Safari 完全対応 5.1WebView Android 未対応 ? — 54Chrome Android 未対応 26 — 54Firefox Android 未対応 なしOpera Android 未対応 ? — 41Safari iOS 完全対応 5.1Samsung Internet Android 未対応 1.5 — 6.0
locationChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 15IE 完全対応 9Opera 完全対応 ありSafari 完全対応 6.1WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 15Opera Android 完全対応 ありSafari iOS 完全対応 8Samsung Internet Android 完全対応 あり
metaKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
repeatChrome 完全対応 ありEdge 完全対応 79Firefox 完全対応 28IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10.1WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 28Opera Android 完全対応 ありSafari iOS 完全対応 10.3Samsung Internet Android 完全対応 あり
shiftKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
which
非推奨非標準
Chrome 完全対応 4Edge 完全対応 12Firefox 完全対応 2
補足
完全対応 2
補足
補足 Firefox also implements this property on the UIEvent interface.
IE 完全対応 9Opera 完全対応 12.1Safari 完全対応 5.1WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 あり
補足
完全対応 あり
補足
補足 Firefox also implements this property on the UIEvent interface.
Opera Android 完全対応 12.1Safari iOS 完全対応 5.1Samsung Internet Android 完全対応 あり

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
非標準。ブラウザー間の互換性が低い可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
非推奨。新しいウェブサイトでは使用しないでください。
非推奨。新しいウェブサイトでは使用しないでください。
実装ノートを参照してください。
実装ノートを参照してください。

互換性のメモ

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

関連情報