Element: keydown イベント

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

keydown イベントは、キーが押されたときに発生します。

非推奨の keypress イベントとは異なり、 keydown イベントは生成する文字値に関係なくすべてのキーで発生します。

keydownkeyup イベントは、どのキーが押されたかを示すコードを提供し、 keypress はどの文字が入力されたかを示します。例えば、小文字の "a" は keydownkeyup では 65 と報告され、 keypress では 97 と報告されます。大文字の "A" は、どのイベントでも 65 と報告されます。

キーボード操作の対象となるイベントのターゲットは、現在フォーカスされている、キーボード操作を処理している要素です。これには、<input><textarea>contentEditable がついた何らかの要素、および、<a><button><summary> など、キーボードで操作できる何らかの要素が含まれます。適切な要素にフォーカスが当たっていなければ、イベントのターゲットは <body> またはルートになります。イベントが捕捉されなければ、イベントは DOM ツリーDocument に達するまでバブリングします。

イベントのターゲットは、異なるキーイベント間で変更されることがあります。例えば、 Tab キーを押したときの keydown のターゲットは、 keyup のターゲットとは異なるものになるでしょう。フォーカスが変更されるからです。

構文

イベント名を addEventListener() などのメソッドで使用したり、イベントハンドラープロパティを設定したりします。

js
addEventListener("keydown", (event) => {});

onkeydown = (event) => {};

イベント型

KeyboardEvent です。 Event から継承しています。

Event UIEvent KeyboardEvent

イベントプロパティ

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

KeyboardEvent.altKey 読取専用

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

KeyboardEvent.code 読取専用

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

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

KeyboardEvent.ctrlKey 読取専用

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

KeyboardEvent.isComposing 読取専用

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

KeyboardEvent.key 読取専用

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

KeyboardEvent.location 読取専用

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

KeyboardEvent.metaKey 読取専用

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

KeyboardEvent.repeat 読取専用

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

KeyboardEvent.shiftKey 読取専用

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

addEventListener による keydown の例

この例では、 <input> 要素内でキーを押すたびに、 KeyboardEvent.code 値を記録します。

html
<input placeholder="ここをクリックして、キーを押してください。" size="40" />
<p id="log"></p>
js
const input = document.querySelector("input");
const log = document.getElementById("log");

input.addEventListener("keydown", logKey);

function logKey(e) {
  log.textContent += ` ${e.code}`;
}

keydown イベントと IME

Firefox 65 以降では、CJKT ユーザーのブラウザー間の互換性を高めるために、 keydown および keyup イベントが IME 変換中に発行されるようになりました(Firefox バグ 354358)。変換操作中の keydown イベントをすべて無視するには、次のようにしてください (229 は、IME によって処理されたイベントに関連する keyCode に設定される特別な値です)。

js
eventTarget.addEventListener("keydown", (event) => {
  if (event.isComposing || event.keyCode === 229) {
    return;
  }
  // 何かを行う
});

メモ: IME を開くための最初の文字を入力したときに、 compositionstartkeydown の後に発行されることがあります。また、 IME を閉じられり最後の文字を入力したときに、 compositionendkeydown の前に発行されることがあります。これらの場合、イベントが変換の一部であっても、isComposing は false となります。しかし、これらの場合でも KeyboardEvent.keyCode229 のままなので、非推奨ではあるものの、やはり keyCode も調べることをお勧めします。

仕様書

Specification
UI Events
# event-type-keydown
HTML
# handler-onkeydown

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
keydown event

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報