KeyboardEvent

在本文章中

构造器
方法
属性
注意事项
1. 特殊情况
2. 自动重复处理
  1. Ubuntu 9.4 等 GTK 环境下的自动重复
  2. Gecko 5.0之前的自动重复处理
示例
标准
浏览器支持
See also

KeyboardEvent 对象描述了键盘的交互方式。每个事件都描述了一个按键（Each event describes a key）；事件类型keydown， keypress 与 keyup 可以确定是哪种事件在活动。

KeyboardEvent 表示刚刚发生在按键上的事情。当你需要处理文本输入的时候，使用 HTML5 input 事件代替。例如，用户使用手持系统如平板电脑输入时，按键事件可能不会触发。

构造器

KeyboardEvent(): 创建一个 KeyboardEvent 对象。

方法

本接口同样会继承对象父代的方法， UIEvent 和 Event。

KeyboardEvent.getModifierState(): 返回一个 Boolean，表示在事件创建时，修改键如Alt ， Shift， Ctrl， Meta等是否按下。
KeyboardEvent.initKeyEvent(): 初始化一个 KeyboardEvent 对象。Gecko 浏览器从来没有实现过本方法，其曾经使用过 KeyboardEvent.initKeyboardEvent() 方法，但是以后大概都不会再使用。现在的标准方式是使用 KeyboardEvent() 构造器。
KeyboardEvent.initKeyboardEvent(): 初始化一个 KeyboardEvent 对象。Gecko 浏览器从来没有实现过本方法，其曾经使用过 KeyboardEvent.initKeyEvent() 方法，但是以后大概都不会再使用。现在的标准方式是使用 KeyboardEvent() 构造器。

属性

本接口同样会继承对象父代的属性， UIEvent 和 Event。

KeyboardEvent.altKey 只读: 如果在生成按键事件时Alt ( Option 或 OS X 的 ⌥ ) 处于活动状态，则返回一个 Boolean 。
KeyboardEvent.char 只读: 返回一个表示按键的字符值的DOMString 。如果该按键对应于可打印字符, 则此值是一个包含该字符的非空 Unicode 字符串。如果该按键没有可打印的表示形式, 则为空字符串。
如果该按键用作插入多个字符的宏, 则此属性的值是整个字符串, 而不仅仅是第一个字符。

注意: DOM Level 3 中已丢弃. 仅支持 IE9+.
KeyboardEvent.charCode 只读: 返回一个表示按键的 Unicode 编码的 Number；此属性仅由 keypress 事件使用。对于其 char 属性包含多个字符的按键是该属性中第一个字符的 Unicode 值。在火狐26中, 将返回可打印字符的代码。
注意: 此属性已被弃用 ; 用 KeyboardEvent.key 代替（如果可用）。
KeyboardEvent.code 只读: 返回一个用事件表示值的 DOMString 。
KeyboardEvent.ctrlKey 只读: 如果在生成按键事件时 Ctrl 键处于活动状态，则返回一个Boolean。
KeyboardEvent.isComposing 只读: 如果事件在compositionstart之后或 compositionend之前被触发，则返回一个Boolean 。
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 只读: 如果 Meta key (Mac上是⌘ Command 键; Windows上是 ⊞ 键) 在生成按键事件时是活动的，则返回一个 Boolean。
KeyboardEvent.repeat 只读: 返回一个Boolean ，如果该按键被保持为自动重复, 则该值为 true。
KeyboardEvent.shiftKey 只读: 返回一个 Boolean ，如果在生成按键事件时 shift 键处于活动状态, 则为 true。
KeyboardEvent.which 只读: 返回一个表示系统和实现相关的数字代码Number 用于标识按键的未修改值，通常与 keyCode 相同。
注意: 此属性已弃用；请用 KeyboardEvent.key 代替（如果可用）。

注意事项

它有 keydown事件, keypress事件和 keyup事件可用。通常Gecko这样派出事件:

当按键被按下时, 发送 keydown 事件。
如果该按键不是修饰键, 发送 keypress 事件。
当按键被释放时, 发送 keyup 事件。

特殊情况

一些按键能切换指示灯的状态，如Caps Lock键，Num Lock键和Scroll Lock键。在Windows和Linux上，这些按键仅发送 keydown 事件和 keyup 事件。

在 Linux上，Firefox 12 及其更早的版本也为这些按键发送了 keypress 事件。

但是，由于 MAC OS X 事件模型限制，Caps Lock键仅发送 keydown 事件。Num Lock键已支持旧的MacBook (2007和更旧的) ，但Mac至今都不支持Num Lock功能及外接键盘。在有Num Lock键的旧Macbook上 Num Lock 键不会触发任何事件。如果外接键盘有F14连接的话 Gecko 就支持 Scroll Lock键。在某个旧版本的 Firefox 里，这个键仅会触发 keypress 事件。详见 bug 602812。

自动重复处理

当按键被按下并被按住时开始自动重复。这将导致一系列事件被发送：

keydown
keypress
keydown
keypress
<<repeating until the user releases the key>>
keyup

这是DOM Level 3标准所说的应该发生的事情。但是需要注意一下，如下所述。

Ubuntu 9.4 等 GTK 环境下的自动重复

在一些基于GTK的环境中，自动重复在此期间自动发送一个本地的key-up事件，并且无法让 Gecko 知道重复的按键和自动重复的区别。在这些平台上，自动重复键将生成以下事件序列：

keydown
keypress
keyup
keydown
keypress
keyup
<<repeating until the user releases the key>>
keyup

不幸的是, 在这些环境中 web 内容无法区分自动重复键和正被反复按下的键之间的区别。

Gecko 5.0之前的自动重复处理

在Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2)之前，键盘处理在平台之间的一致性较差。

Windows: 自动重复行为与Gecko 4.0和更高版本相同。
Mac: 在初始keydown事件之后，只发送keypress事件直到发生keyup事件；不发送 inter-spaced 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' (i.e. 'a' is pressed),
    // event.ctrlKey may be true if Ctrl key is pressed at the time.
    alert(`Combination of ctrlKey + ${keyName}`);
  } else {
    alert(`Key pressed ${keyName}`);
  }
}, false);
document.addEventListener('keyup', (event) => {
  const keyName = event.key;
  // As the user release 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	Obsolete	初始定义。

KeyboardEvent 接口标准经历了许多草稿版本 , 首先在 DOM Events Level 2 下由于没有协商一致，它被丢弃； DOM Events Level 3重新加入.。这导致了在早期的DOM Events Level 2 版本中非标准初始化方法的实现，KeyboardEvent.initKeyEvent() 实现在 Gecko 浏览器和早期 DOM Events Level 3 版本, KeyboardEvent.initKeyboardEvent()则实现在其他上。这两者都被现代使用构造函数所取代: KeyboardEvent().

浏览器支持

其他页面上提供了更多兼容性数据:

.code - 参阅浏览器兼容性 KeyboardEvent.code.
.key - 参阅浏览器兼容性 KeyboardEvent.key.
.getModifierState() - 参阅浏览器兼容性 KeyboardEvent.getModifierState

Desktop
Mobile

功能	Chrome	Firefox (Gecko)	Internet Explorer	Opera	Safari (WebKit)
Basic support	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)
constructor	(Yes)	31.0 (31.0)	未实现	(Yes)	?
`.char`	未实现	未实现	9	未实现	未实现
`.charCode`	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)
`.isComposing`	未实现	31.0 (31.0)	未实现	未实现	未实现
`.keyCode`	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)
`.locale`	未实现	未实现	(Yes)	未实现	未实现
`.location`	(Yes)	15.0 (15.0)	(Yes)	未实现	未实现
`.repeat`	(Yes)	28.0 (28.0)	(Yes)	未实现	未实现
`.which`	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)
`.initKeyboardEvent()`	(Yes)^[1]	未实现^[2]	9.0^[3]	?	(Yes)^[1]

功能	Android	Firefox Mobile (Gecko)	IE Phone	Opera Mobile	Safari Mobile
Basic support	?	(Yes)	?	?	?
constructor	?	31.0 (31.0)	?	?	?
`.char`	?	未实现	?	?	?
`.charCode`	?	(Yes)	?	?	?
`.isComposing`	未实现	31.0 (31.0)	未实现	未实现	未实现
`.keyCode`	?	(Yes)	?	?	?
`.locale`	?	未实现	?	?	?
`.location`	?	15.0 (15.0)	?	?	?
`.repeat`	?	28.0 (28.0)	?	?	?
`.which`	?	(Yes)	?	?	?
`.initKeyboardEvent()`	?	未实现	?	?	?

[1] WebKit 和 Blink的initKeyboardEvent()的参数与 DOM Level 3 Events中的定义不同： initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIdentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)

[2] Gecko 不支持 initKeyboardEvent() ，因为支持它完全中断了 web 应用程序的功能检测。详见 bug 999645.

[3] IE的initKeyboardEvent() 的参数也与DOM Level 3 Events中的定义不同：initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in number locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg). See document of initKeyboardEvent() in MSDN.

[4] 注意, 手动触发事件不会生成与该事件关联的默认操作。例如, 手动触发键事件不会导致该字母出现在焦点文本输入中。在UI events下, 这很重要, 因为它可以防止脚本模拟与浏览器本身交互的用户操作。