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

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

コンストラクター

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

メソッド

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

KeyboardEvent.getModifierState()
Boolean を返し、そのイベントが発生した際に修飾キー (Alt / Shift / Ctrl / Meta) が押されていたかどうかを表します。
KeyboardEvent.initKeyEvent()
KeyboardEvent オブジェクトを初期化します。このメソッドを実装していたのは Firefox のみであり、こちらでももう対応していません。代わりに、 KeyboardEvent() コンストラクターを使用してください。
KeyboardEvent.initKeyboardEvent()
KeyboardEvent オブジェクトを初期化します。これは非推奨になりました。代わりに KeyboardEvent() コンストラクターを使用してください。

プロパティ

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

警告: これはユーザーのキーボード配列を無視しますので、ユーザーが QWERTY キーボード配列の "Y" の位置のキー (ホーム行の上の行の中ほど) を押すと、ユーザーが QWERTZ キーボード (ユーザーが "Z" だと思っており、その他のプロパティも "Z" を示している) や Dvorak キーボード配列 (ユーザーは "F" だと思っている) を使用していても、常に "KeyY" を返します。
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 を返し、そのイベントが compositionstartcompositionend の間に発生したものであれば 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 では 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 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
KeyboardEventChrome 完全対応 ありEdge 完全対応 ありFirefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android ?
KeyboardEventChrome 完全対応 ありEdge ? Firefox 完全対応 31IE 未対応 なしOpera 完全対応 ありSafari ? WebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile ? Firefox Android 完全対応 31Opera Android 完全対応 ありSafari iOS ? Samsung Internet Android ?
altKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
charCode
非推奨非標準
Chrome 完全対応 26Edge 完全対応 12Firefox 完全対応 3IE 完全対応 9Opera 完全対応 12.1Safari 完全対応 5.1WebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android 完全対応 ありOpera Android ? Safari iOS 完全対応 5.1Samsung Internet Android ?
codeChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
ctrlKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
isComposingChrome 完全対応 56Edge ? Firefox 完全対応 31IE 未対応 なしOpera 完全対応 43Safari 完全対応 10.1WebView Android 完全対応 56Chrome Android 完全対応 56Edge Mobile ? Firefox Android 完全対応 31Opera Android 完全対応 43Safari iOS 完全対応 10.1Samsung Internet Android ?
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 完全対応 ありWebView Android 完全対応 51Chrome Android 完全対応 51Edge Mobile 完全対応 ありFirefox Android 完全対応 23Opera Android 完全対応 38Safari iOS 完全対応 ありSamsung Internet Android ?
keyCode
非推奨非標準
Chrome 完全対応 26Edge 完全対応 12Firefox 完全対応 3IE 完全対応 6Opera 完全対応 11.6Safari 完全対応 5WebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android ? Opera Android ? Safari iOS 完全対応 5.1Samsung Internet Android ?
keyIdentifier
非推奨非標準
Chrome 未対応 26 — 54Edge ? Firefox 未対応 なしIE 未対応 なしOpera 未対応 15 — 41Safari 完全対応 5.1WebView Android 未対応 ? — 54Chrome Android 未対応 26 — 54Edge Mobile ? Firefox Android 未対応 なしOpera Android 未対応 ? — 41Safari iOS 完全対応 5.1Samsung Internet Android ?
locationChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 15IE 完全対応 9Opera 完全対応 ありSafari 完全対応 6.1WebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android 完全対応 15Opera Android ? Safari iOS 完全対応 8Samsung Internet Android ?
metaKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android ? Chrome Android ? Edge Mobile 完全対応 ありFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
repeatChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 28IE 未対応 なしOpera ? Safari 完全対応 10.1WebView Android ? Chrome Android ? Edge Mobile 未対応 なしFirefox Android 完全対応 28Opera Android ? Safari iOS 完全対応 10.1Samsung Internet Android ?
shiftKeyChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android ? Chrome Android ? Edge Mobile 完全対応 あり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 完全対応 10.1Safari 完全対応 5.1WebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile 完全対応 ありFirefox Android 完全対応 あり
補足
完全対応 あり
補足
補足 Firefox also implements this property on the UIEvent interface.
Opera Android ? Safari iOS 完全対応 5.1Samsung Internet Android ?
getModifierStateChrome 完全対応 31Edge 完全対応 12Firefox 完全対応 15IE 完全対応 9Opera 完全対応 17Safari 完全対応 10.1WebView Android 完全対応 4.4.3Chrome Android 完全対応 31Edge Mobile 完全対応 ありFirefox Android 完全対応 15Opera Android 未対応 なしSafari iOS 完全対応 10.3Samsung Internet Android 完全対応 あり
DOM_KEY_LOCATION_LEFTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_NUMPADChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_RIGHTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_STANDARDChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?

凡例

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

互換性のメモ

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

関連情報

ドキュメントのタグと貢献者

このページの貢献者: mdnwebdocs-bot, mfuji09, wbamberg, hashedhyphen, fscholz, Masayuki
最終更新者: mdnwebdocs-bot,