KeyboardEvent

构造函数

KeyboardEvent()

创建一个新的 KeyboardEvent 对象。

常量

KeyboardEvent 接口定义了以下常量。

键盘位置

以下常量标识按键事件源自键盘的哪个部分。它们以 KeyboardEvent.DOM_KEY_LOCATION_STANDARD 等方式访问。

实例属性

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

KeyboardEvent.altKey 只读

返回一个布尔值，如果生成按键事件时 Alt 键（macOS 上为 Option 或 ⌥ 键）处于活动状态，则返回 true。

KeyboardEvent.code 只读

返回一个字符串，其中包含事件所代表的物理键的代码值。

警告： 这会忽略用户的键盘布局，因此如果用户在 QWERTY 键盘布局中按下 "Y" 位置的键（在主行上方一行的中间附近），这将始终返回 "KeyY"，即使用户使用的是 QWERTZ 键盘（这意味着用户期望一个 "Z"，所有其他属性也将指示一个 "Z"）或 Dvorak 键盘布局（用户期望一个 "F"）。如果你想向用户显示正确的按键，可以使用 Keyboard.getLayoutMap()。

KeyboardEvent.ctrlKey 只读

返回一个布尔值，如果生成按键事件时 Ctrl 键处于活动状态，则返回 true。

KeyboardEvent.isComposing 只读

返回一个布尔值，如果事件在 compositionstart 之后和 compositionend 之前触发，则返回 true。

KeyboardEvent.key 只读

返回一个字符串，表示事件所代表的键的键值。

KeyboardEvent.location 只读

返回一个数字，表示键盘或其他输入设备上按键的位置。标识位置的常量列表显示在上面的键盘位置中。

KeyboardEvent.metaKey 只读

返回一个布尔值，如果生成按键事件时 Meta 键（Mac 键盘上的 ⌘ Command 键；Windows 键盘上的 Windows 键 (⊞)）处于活动状态，则返回 true。

KeyboardEvent.repeat 只读

返回一个布尔值，如果按键被按住并自动重复，则返回 true。

KeyboardEvent.shiftKey 只读

返回一个布尔值，如果生成按键事件时 Shift 键处于活动状态，则返回 true。

已废弃的属性

KeyboardEvent.charCode 已弃用 只读

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

KeyboardEvent.keyCode 已弃用 只读

返回一个数字，表示一个系统和实现相关的数字代码，用于标识按下的键的未修改值。

KeyboardEvent.keyIdentifier 非标准 已弃用 只读

此属性为非标准属性，已弃用，建议改用 KeyboardEvent.key。它曾是 DOM Level 3 Events 旧版本的一部分。

实例方法

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

KeyboardEvent.getModifierState()

返回一个布尔值，指示在创建事件时是否按下了修饰键，例如 Alt、Shift、Ctrl 或 Meta。

已废弃的方法

KeyboardEvent.initKeyboardEvent() 已弃用

初始化一个 KeyboardEvent 对象。此方法现已弃用。您应该改用 KeyboardEvent() 构造函数。

事件

以下事件基于 KeyboardEvent 类型。在下面的列表中，每个事件都链接到该事件的 Element 处理程序的文档，该处理程序通常适用于所有接收者，包括 Element、Document 和 Window。

keydown

按键已被按下。

keyup

按键已被释放。

废弃事件

keypress 已弃用

通常会产生字符值的按键已被按下。此事件高度依赖于设备且已废弃。您不应使用它。

用法说明

有三种类型的键盘事件：keydown、keypress 和 keyup。对于大多数按键，Gecko 会按以下方式分发一系列按键事件：

1. 当第一次按下键时，会发送 keydown 事件。
2. 如果按键不是修饰键，则发送 keypress 事件。
3. 当用户释放按键时，会发送 keyup 事件。

特殊情况

某些键会切换指示灯的状态；这些键包括 Caps Lock、Num Lock 和 Scroll Lock 等键。在 Windows 和 Linux 上，这些键只分发 keydown 和 keyup 事件。

然而，macOS 事件模型的限制导致 Caps Lock 只分发 keydown 事件。Num Lock 在一些较旧的笔记本电脑型号（2007 年及更早型号）上受支持，但从那时起，macOS 即使在外部键盘上也不支持 Num Lock。在带有 Num Lock 键的旧款 MacBook 上，该键不生成任何键事件。如果连接了带 F14 键的外部键盘，Gecko 支持 Scroll Lock 键。在某些旧版本的 Firefox 中，此键会生成 keypress 事件；这种不一致的行为是 Firefox 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 内容无法区分自动重复键和仅仅是重复按下的键。

示例

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' (e.g., 'a' is pressed),
    // event.ctrlKey may be true if Ctrl key is pressed at the same time.
    alert(`Combination of ctrlKey + ${keyName}`);
  } else {
    alert(`Key pressed ${keyName}`);
  }
});

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

  // As the user releases the Ctrl key, the key is no longer active,
  // so event.ctrlKey is false.
  if (keyName === "Control") {
    alert("Control key was released");
  }
});

规范

KeyboardEvent 接口规范经历了无数草案版本，首先在 DOM Events Level 2 中因未能达成共识而被放弃，然后是 DOM Events Level 3。这导致了非标准初始化方法的实现，早期 DOM Events Level 2 版本 KeyboardEvent.initKeyEvent() 由 Gecko 浏览器实现，以及早期 DOM Events Level 3 版本 KeyboardEvent.initKeyboardEvent() 由其他浏览器实现。两者都已被现代构造函数 KeyboardEvent() 取代。

浏览器兼容性

兼容性说明

• 从 Firefox 65 开始，对于不可打印的键（Firefox bug 968056），不再触发 keypress 事件，但 Enter 键以及 Shift + Enter 和 Ctrl + Enter 键组合除外（这些是为了跨浏览器兼容性而保留的）。

另见

• KeyboardEvent.code.
• KeyboardEvent.key.
• KeyboardEvent.getModifierState()