KeyboardEvent

KeyboardEvent オブジェクトは、ユーザのキー入力情報を提供します。 イベントタイプ、 (keydown、keypress、keyup) は、どういった操作が行われたのかを表します。

Method overview

Attributes

Constants

Virtual key codes

以下の定数は、Geckoで、非推奨の keyCode 属性で仮想キーコードとして利用されているものです。下の図は標準的な、ANSI US keyboard です。Mac や、多くの PC のキーボードは、文字入力可能なキーについては同じレイアウトとなっています。他のキーについても、似たレイアウトでしょう。

Gecko 15 (Firefox 15.0 / Thunderbird 15.0 / SeaMonkey 2.12) 以降では、以下のルールに基づいて、文字入力可能なキーのキーコード値を決定しています。

1. Windows で、押されたキーのネイティブキーコードが、a から z か、0 から 9 の場合、これにあったキーコードを用います。
2. Mac で、押されたキーのネイティブキーコードが、0 から 9 の場合、これにあったキーコードを用います。
3. 押されたキーが、モディファイアキーが押されていない場合に、ASCII アルファベットか、数字を一文字入力する場合、それにあったキーコードを用います。
4. 押されたキーが、Shift キーが押されている場合に、ASCII アルファベットか、数字を一文字入力する場合、それにあったキーコードを用います。
5. 押されたキーが、モディファイアキーが押されていない場合に、それ以外の ASCII 文字 (記号等) を入力する場合、それにあったキーコードを用います。
6. 押されたキーが、Shift キーが押されている場合に、ASCII の記号文字を入力する場合、それにあったキーコードを用います。
7. それ以外の場合、つまり、ASCII の範囲にない、Unicode 文字を入力する場合、
   1. そのキーボードレイアウトが、ASCII 文字を入力するレイアウトの場合 (ASCII capable keyboard layout と呼びます)、0 を用います。
   2. それ以外のキーボードレイアウトの場合、そのシステムにインストールされた、最も優先順位の高い、ASCII 文字を入力するレイアウト (代替キーボードレイアウト) を探し、利用します。
      1. 押されたキーが、その代替キーボードレイアウトで、ASCII のアルファベットか、数字を入力する場合、それにあったキーコードを用います。
      2. それ以外の場合、0 を用います。

Key location constants

以下の定数は、キーイベントの、location 属性で利用されます。 DOM level 3

Methods

getModifierState()

指定したモディファイアキーの状態を返します。 DOM level 3

boolean getModifierState(
  in DOMString keyArg
);

Parameters

keyArg

確認したいモディファイアキーの名前を指定します。この値は、ブラウザ独自の値か、"Alt"、"AltGraph"、"CapsLock"、"Control"、"Fn"、"Meta"、"NumLock"、"ScrollLock", "Shift"、"SymbolLock"、"OS" のいずれかひとつです。IE9 は、"ScrollLock"の代わりに、"Scroll" を、"OS" の代わりに、"Win" を利用しています。これらの、古い仕様書草案にあった名前を Gecko で利用した場合は、getModifierState() は常に、false を返します。

Return value

指定したモディファイアキーがアクティブだった場合、true が、それ以外の場合は、false が返ります。

initKeyboardEvent()

キーボードイベントオブジェクトの属性を初期化します。このメソッドは、古い、DOM Level 3 Events の草案で提案されていましたが、後に非推奨となりました。Gecko ではこのメソッドを実装しませんが、似たメソッドが存在しています。initKeyEvent() を参照してください。.

void initKeyboardEvent(
  in DOMString typeArg,
  in boolean canBubbleArg,
  in boolean cancelableArg,
  in views::AbstractView viewArg,
  in DOMString charArg,
  in DOMString keyArg,
  in unsigned long locationArg,
  in DOMString modifiersListArg,
  in boolean repeat,
  in DOMString localeArg
);

Parameters

typeArg

キーボードイベントのタイプを指定します。keydown、keypress、keyup のいずれかひとつを指定します。

canBubbleArg

イベントがバブルフェーズを持つかどうかを指定します。

cancelableArg

イベントがキャンセル可能かどうかを指定します。

viewArg

?

charArg

char 属性の値を指定します。

keyArg

key 属性の値を指定します。

locationArg

location 属性の値を指定します。

modifiersListArg

アクティブなモディファイアキーの名前を、空白区切りのリストで指定します。例えば、"Control Shift" であれば、ユーザが、Control キーと、Shift キーを押した状態でそのキーイベントが生成されたことになります。

repeatArg

repeat 属性の値を指定します。

localeArg

locale 属性の値を指定します。

Processing of key events

キーイベントには、keydown、keypress、keyup の三種類があります。大半のキーにおいて、Gecko は以下の手順でキーイベントを生成します。

1. キーが押された時、keydown イベントが発生します。
2. そのキーがモディファイアキーでは無い場合、keypress イベントが発生します。
3. キーが解放された時、keyup イベントが発生します。

Special cases

CapsLock、NumLock、ScrollLock キーのように、キーボードの LED の状態を切り替えるキーの場合、Windows と Linux では、keydown と keyup イベントのみが発生します。ただし、Linux では、Firefox 12 以前は、keypress イベントも発生していたことに注意してください。

一方、Mac では、Caps Lock キーが押された時に、keydown イベントのみが発生します。これは、プラットフォーム固有のイベントモデルによる制限が原因です。 NumLock は、(2007 年モデルか、それ以前の) MacBook ではサポートされていました。しかし、最近では、外付けキーボードを接続したとしても、サポートしていません。NumLock キーをもつ、古い MacBook では、NumLock キーの操作は、いかなるキーイベントも発生しません。加えて、Gecko は、F14 キーをもつ、外付けキーボードを接続した場合に、ScrollLock キーとしてそのキーを扱いますが、このキーのイベントでは、keypress イベントが発生します。これらの、他のプラットフォームと違った挙動はバグです。 バグ 602812 を参照してください。

Auto-repeat handling

キーを押し続けた場合、オートリピート機能による連続入力になります。この状況では、以下のような順序でイベントが発生します。

1. keydown
2. keypress
3. keydown
4. keypress
5. <<ユーザがキーを離すまで、以下、繰り返し>>
6. keyup

これは、DOM Level 3 Events 仕様書で定義されている動作です。しかし、以下のような例外があることに注意してください。

Auto-repeat on some GTK environments such as Ubuntu 9.4

いくつかの GTK ベースの環境では、オートリピート時にも、ネイティブのキーリリースイベントが生成されます。残念ながら、Gecko はこのような環境では、オートリピートによる入力であるかどうかを判断することができません。このような環境では以下の順序でイベントが発生します。

1. keydown
2. keypress
3. keyup
4. keydown
5. keypress
6. keyup
7. <<ユーザがキーを離すまで、以下、繰り返し>>
8. keyup

このため、このような環境では、残念ながら、Web コンテンツも、オートリピートによる入力なのかどうかを判断することはできません。

Auto-repeat handling prior to Gecko 4.0

Gecko 4.0 より古いバージョンでは、キーイベントの生成方法は、プラットフォーム間で統一感のないものでした。

Windows

オートリピートによる入力時の動作は、Gecko 4.0 以降と同じです。

Mac

最初の keydown イベントの後、keypress イベントのみが、keyup イベントが発生するまで繰り返されていました。つまり、二回目以降の keydown イベントは繰り返し、生成されていませんでした。

Linux

その挙動は、プラットフォーム側の動作に依存していました。そのため、Windows のようにも、 Mac のようにもイベントが発生していた可能性があります。

Key names and Char values

Specification

DOM 3 Events: KeyboardEvent

Example

<!DOCTYPE html>
<html>
<head>
<script>
var metaChar = false;
var exampleKey = 16;

function keyEvent(event) {
  var key = event.keyCode || event.which;
  var keychar = String.fromCharCode(key);
  if (key == exampleKey) {
    metaChar = true;
  }
  if (key != exampleKey) {
    if (metaChar) {
      alert("Combination of metaKey + " + keychar);
      metaChar = false;
    } else {
      alert("Key pressed " + key);
    }
  }
}

function metaKeyUp (event) {
  var key = event.keyCode || event.which;

  if (key == exampleKey) {
    metaChar = false;
  }
}
</script>
</head>

<body onkeydown="keyEvent(event)" onkeyup="metaKeyUp(event)">
</body>
</html>