MDN will be in maintenance mode on Thursday September 21st, starting at 10 AM Pacific / 5 PM UTC, for about 1 hour.

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这样派出事件:

  1. 当按键被按下时, 发送 keydown 事件。
  2. 如果该按键不是修饰键, 发送 keypress 事件。
  3. 当按键被释放时, 发送 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

自动重复处理

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

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<repeating until the user releases the key>>
  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. <<repeating until the user releases the key>>
  8. 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().

浏览器支持

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

功能 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下, 这很重要, 因为它可以防止脚本模拟与浏览器本身交互的用户操作。

See also

文档标签和贡献者

 此页面的贡献者: Ende93, aaq112225, teoli, ziyunfei
 最后编辑者: Ende93,