KeyboardEvent - 描述了用户与键盘的交互

KeyboardEvent 对象描述了用户与键盘的交互；每个事件描述用户与键盘上的键（或键与修饰键的组合）之间的单个交互。事件类型（keydown，keypress 或 keyup）标识发生了哪种类型的键盘活动。

注意： KeyboardEvent 事件只是指示用户与键盘上的键处于较低级别的交互，不为该交互提供上下文含义。当您需要处理文本输入时，请改为使用 input 事件。如果用户使用其他方式输入文本（例如平板电脑或图形输入板上的手写系统），则可能不会触发键盘事件。

构造函数

KeyboardEvent()

创建一个新的 KeyboardEvent 对象。

方法

此接口还继承其父接口 UIEvent 和 Event 的方法。

KeyboardEvent.getModifierState()

返回一个 Boolean，指示该事件创建时，修饰键是否为 Alt，Shift，Ctrl 或 Meta。

KeyboardEvent.initKeyEvent()

初始化一个 KeyboardEvent 对象。该方法仅由 Firefox 实现的，而且也不再支持了；相反，您应该使用 KeyboardEvent() 构造函数。

KeyboardEvent.initKeyboardEvent()

初始化一个 KeyboardEvent 对象。现在已弃用。您应该使用 KeyboardEvent() 构造函数。

属性

此接口还继承其父接口 UIEvent 和 Event 的属性。

KeyboardEvent.altKey 只读

返回一个 Boolean，如果在生成键盘事件时，Alt（OS X 上的 Option 或 ⌥）为激活状态时，则为 true。

KeyboardEvent.char 只读

返回一个 DOMString，表示键的字符值。如果键对应于可打印字符，则此值是包含该字符的非空 Unicode 字符串。如果键没有可打印的表示，则为空字符串。

注意： 如果键用作插入多个字符的宏，则此属性的值是整个字符串，而不仅仅是第一个字符。

KeyboardEvent.charCode 只读

返回一个 Number，表示键的 Unicode 参考数值；此属性仅由 keypress 事件使用。对于 char 属性包含多个字符的键，这是该属性中第一个字符的 Unicode 值。在 Firefox 26 中，它返回可打印字符的代码。

警告： 不推荐使用此属性；如果可以的话，你应该使用 KeyboardEvent.key。

KeyboardEvent.code 只读

返回 DOMString，其中包含事件所代表的物理键的代码值。

警告： 该属性忽略了用户的键盘布局，因此如果用户在 QWERTY 键盘布局中的 “Y” 位置按下键（在主行的上面一行的中间附近），它将始终返回 "KeyY"。如果用户用的是 QWERTZ 键盘（用户按的是 Z）或 Dvorak 键盘布局（用户按的是 F），也是返回 "KeyY"。

KeyboardEvent.ctrlKey 只读

返回一个 Boolean，如果 Ctrl 键处于活动状态，则该值为 true。

KeyboardEvent.isComposing 只读

返回一个 Boolean，如果是在 compositionstart 之后和 compositionend 之前触发事件，则该值为 true。

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 只读

返回一个 Boolean，如果在生成键盘事件时，Meta（在 Mac 键盘上，为 ⌘ Command 键；在 Windows 键盘上为 Windows 键 ⊞）为激活状态时，则为 true。

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 事件。

但是，macOS 事件模型的限制导致 Caps Lock 仅调度 keydown 事件。Num Lock 在一些较旧的笔记本电脑型号（2007 型号和旧型号）上是有事件的，但从那之后，即使在外部键盘上，macOS 也不支持 Num Lock 的事件。在具有 Num Lock 键的旧 MacBook 上，该键不会生成任何按键事件。如果连接了具有 F14 键的外部键盘，Gecko 会支持 Scroll Lock 键的事件。在某些旧版本的 Firefox 中，此按键会生成一个 keypress 事件；这种不一致的行为记录在 Mozilla bug 602812。

自动重复处理

按下并按住某个键时，它开始自动重复。这导致发送类似于以下事件的一系列事件：

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<重复直到用户松开按键>>
  6. keyup

这是 DOM Level 3 规范所说的应该发生的事情。但是，如下所述，有一些注意事项。

在某些 GTK 环境（如 Ubuntu 9.4）上的自动重复

在某些基于 GTK 的环境中，自动重复会在自动重复期间自动调度原生的键盘事件，因此 Gecko 无法知道重复的一系列按键和自动重复之间的区别。在这些平台上，自动重复键将生成以下事件序列：

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. <<重复直到用户松开按键>>
  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 事件才停止。不发送间隔开的 keydown 事件。

Linux

事件行为取决于特定平台。它将表现得像 Windows 或 Mac，具体取决于本机事件模型的作用。

注意： 自动触发事件不生成与该事件关联的默认操作。例如，自动触发键事件不会使事件对应的字母出现在获得焦点的文本输入中。对于 UI 事件，这样做是出于安全原因，因为它可以防止脚本模拟用户与浏览器本身的交互操作。

实例

<!DOCTYPE html>
<html>
<head>
<script>
'use strict';

document.addEventListener('keydown', (event) => {
  const keyName = event.key;

  if (keyName === 'Control') {
    // 仅按下 Control 键时不发出 alert。
    return;
  }

  if (event.ctrlKey) {
    // 如果 event.key 不是 'Control'（例如，按下'a'），
    // 同时按下 Ctrl 键，则 event.ctrlKey 为 true。
    alert(`组合键 ctrl + ${keyName}`);
  } else {
    alert(`按下了 ${keyName} 键`);
  }
}, false);

document.addEventListener('keyup', (event) => {
  const keyName = event.key;

  // 当用户释放 Ctrl 键时，该键不再处于活动状态，
  // 因此 event.ctrlKey 为 false。
  if (keyName === 'Control') {
    alert('松开了控制键');
  }
}, false);

</script>
</head>

<body>
</body>
</html>

规范

规范 状态 备注
UI Events
KeyboardEvent 的定义		 工作草案 -

KeyboardEvent 接口规范经历了许多草案版本，首先在 DOM Events Level 2 下，因为没有达成共识而被删除，然后在 DOM Events Level 3 下。这导致了各浏览器实现了非标准的初始化方法，Gecko 浏览器实现了早期 DOM Events Level 2 版本的 KeyboardEvent.initKeyEvent() 方法，而其他浏览器实现了 DOM Events Level 3 版本的 KeyboardEvent.initKeyboardEvent() 方法。现在，两者都被构造函数这样的现代用法所取代：KeyboardEvent()。

桌面浏览器兼容性

特性ChromeEdgeFirefoxInternet ExplorerOperaSafari
基础支持 支持 支持 支持 支持 支持 支持
KeyboardEvent 支持 未知31 不支持 支持 未知
altKey 支持 支持 支持 支持 支持 支持
charCode26 支持3912.15.1
code 未知 未知 未知 未知 未知 未知
ctrlKey 支持 支持 支持 支持 支持 支持
isComposing56 未知31 不支持43 不支持
key51 支持239138 支持
keyCode26 支持3611.65
keyIdentifier26 — 54 未知 不支持 不支持15 — 415.1
location 支持 支持159 支持6.1
metaKey 支持 支持 支持 支持 支持 支持
repeat 支持 不支持28 不支持 未知10.1
shiftKey 支持 支持 支持 支持 支持 支持
which4 支持22910.15.1
getModifierState31 支持159 不支持 不支持
DOM_KEY_LOCATION_LEFT 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_NUMPAD 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_RIGHT 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_STANDARD 未知 未知 未知 未知 未知 未知

移动浏览器兼容性

特性AndroidChrome for AndroidEdge mobileFirefox for AndroidIE mobileOpera AndroidiOS Safari
基础支持 支持 支持 支持 支持 未知 支持 支持
KeyboardEvent 支持 支持 未知31 未知 支持 未知
altKey 未知 未知 支持 未知 未知 未知 未知
charCode 未知 未知 支持 支持 未知 未知5.1
code 未知 未知 未知 未知 未知 未知 未知
ctrlKey 未知 未知 支持 未知 未知 未知 未知
isComposing5656 未知31 未知43 不支持
key5151 支持23 未知38 支持
keyCode 未知 未知 支持 未知 未知 未知5.1
keyIdentifier26 — 5426 — 54 未知 不支持 未知 支持 — 415.1
location 未知 未知 支持15 未知 未知8
metaKey 未知 未知 支持 未知 未知 未知 未知
repeat 未知 未知 不支持28 未知 未知10.1
shiftKey 未知 未知 支持 未知 未知 未知 未知
which 支持 支持 支持 支持2 未知 未知5.1
getModifierState3131 支持15 未知 不支持 不支持
DOM_KEY_LOCATION_LEFT 未知 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_NUMPAD 未知 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_RIGHT 未知 未知 未知 未知 未知 未知 未知
DOM_KEY_LOCATION_STANDARD 未知 未知 未知 未知 未知 未知 未知

1. IE 的实现与当前规范不完全匹配，因为它基于较旧版本的规范。

2. Firefox 还在 UIEvent 接口上实现了这个属性。

兼容性说明

从 Firefox 65 开始，除了 Enter 键, Shift + Enter 和 Ctrl + Enter 组合键，non-printable keys不再触发 keypress 事件 (Mozilla bug 968056)（保留这些组合用于跨浏览器兼容性）。

相关链接