KeyboardEvent

KeyboardEvent objects describe a user interaction with the keyboard. Each event describes a key; the event type (keydown, keypress, or keyup) identifies what kind of activity was performed.

Method overview

Attributes

Constants

Virtual key codes

These constants represent virtual key codes as reported by the deprecated keyCode attribute; that is, keys that do not correspond to printable characters. The diagram below represents a standard ANSI US keyboard; Mac and most PC keyboards have the same layout for the printable characters, and a similar layout for the remaining keys.

Starting in Gecko 15 (Firefox 15.0 / Thunderbird 15.0 / SeaMonkey 2.12), Gecko decides keycode by following rules for printable keys:

1. If the system is Windows and native keycode of pressed key indicates that the key is a-z or 0-9, uses a keycode for it.
2. If the system is Mac and native keycode of pressed key indicates that the key is 0-9, uses a keycode for it.
3. If pressed key inputs an ASCII alphabet or numeric with no modifier key, uses a keycode for it.
4. If pressed key inputs an ASCII alphabet or numeric with Shift key, uses a keycode for it.
5. If pressed key inputs another ASCII character with no modifier key, uses a keycode for it.
6. If pressed key inputs another ASCII character with Shift key, users a keycode for it.
7. Otherwise, i.e., pressed key inputs a Unicode character:
   1. If the keyboard layout is ASCII capable keyboard layout (i.e., can input ASCII alphabets), uses 0.
   2. Otherwise, i.e., the keyboard layout isn't ASCII capable, using ASCII capable keyboard layout which is installed on the environment and has highest priority:
      1. If pressed key on the alternative keyboard layout inputs an ASCII alphabet or numeric, uses a keycode for it.
      2. Otherwise, uses 0.

Key location constants

These constants describe the location on the keyboard of key events. DOM level 3

Methods

getModifierState()

返回指定的修饰键的当前状态.  DOM level 3

boolean getModifierState(
  in DOMString keyArg
);

参数

keyArg

A string identifying the modifier key whose value you wish to determine. This may be an implementation-defined value or one of: "Alt", "AltGraph", "CapsLock", "Control", "Fn", "Meta", "NumLock", "ScrollLock", "Shift", "SymbolLock", or "OS". Note that IE9 uses "Scroll" for "ScrollLock" and "Win" for "OS". If you use these older draft's name, Gecko's getModifierState() always returns false.

返回值

如果指定的修饰键处于按下状态,则返回true,否则返回false.

initKeyboardEvent()

Initializes the attributes of a keyboard event object. This method was introduced in draft of DOM Level 3 Events, but deprecated in newer draft. Gecko doesn't implement this method but there is similar one, see 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
);

参数

typeArg

The type of keyboard event; this will be one of keydown, keypress, or keyup.

canBubbleArg

Whether or not the event can bubble.

cancelableArg

Whether or not the event can be canceled.

viewArg

?

charArg

The value of the char attribute.

keyArg

The value of the key attribute.

locationArg

The value of the location attribute.

modifiersListArg

A whitespace-delineated list of modifier keys that should be considered to be active on the event's key. For example, specifying "Control Shift" indicates that the user was holding down the Control and Shift keys when pressing the key described by the event.

repeatArg

The value of the repeat attribute.

localeArg

The value of the locale attribute.

Processing of key events

There are keydown, keypress, and keyup events. For most keys, Gecko dispatches a sequence of key events like this:

1. When the key is first depressed, the keydown event is sent.
2. If the key is not a modifier key, the keypress event is sent.
3. When the user releases the key, the keyup event is sent.

Special cases

Certain keys toggle the state of an LED indicator, such as Caps Lock, Num Lock, and Scroll Lock. On Windows and Linux, these keys dispatch only the keydown and keyup events. Note that on Linux, Firefox 12 and earlier also dispatched the keypress event for these keys.

On Mac, however, Caps Lock dispatches only the keydown event due to a platform event model limitation. Num Lock on an external keyboard (that is, without needing to press the Fn key to generate the Num Lock key code) dispatches keydown, keypress, and keyup, but Num Lock and Scroll Lock generated using the Fn key doesn't dispatch any events at all. This inconsistent behavior is a bug; see bug 602812.

Auto-repeat handling

When a key is pressed and held down, it begins to auto-repeat. This results in a sequence of events similar to the following being dispatched:

1. keydown
2. keypress
3. keydown
4. keypress
5. <<repeating until the user releases the key>>
6. keyup

This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.

Auto-repeat on some GTK environments such as Ubuntu 9.4

In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:

1. keydown
2. keypress
3. keyup
4. keydown
5. keypress
6. keyup
7. <<repeating until the user releases the key>>
8. keyup

In these environments, unfortunately, there's no way for web content to tell the difference between auto-repeating keys and keys that are just being pressed repeatedly.

Auto-repeat handling prior to Gecko 4.0

Before Gecko 4.0 , keyboard handling was less consistent across platforms.

Windows

Auto-repeat behavior is the same as in Gecko 4.0 and later.

Mac

After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.

Linux

The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.

Key names and Char values

规范

DOM 3 Events: KeyboardEvent

例子

<!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>