KeyboardEvent

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

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

Event UIEvent KeyboardEvent

构造函数

KeyboardEvent()

创建一个新的 KeyboardEvent 对象。

常量

KeyboardEvent 接口定义了以下常量。

键盘位置

以下常量标识键事件来自键盘的哪个部分。可以通过 KeyboardEvent.DOM_KEY_LOCATION_STANDARD 等访问它们。

键盘位置标识符
常量 值 描述
DOM_KEY_LOCATION_STANDARD 0x00

事件描述的键未被识别为位于键盘的特定区域；它不位于数字键盘上（除非是 NumLock 键），并且对于在键盘左侧和右侧重复的键，无论出于何种原因，该键都不应与该位置相关联。

例如，标准 PC 101 美国键盘上的字母数字键、NumLock 键和空格键。
DOM_KEY_LOCATION_LEFT 0x01

该键是可能在键盘上多个位置存在的键，在这种情况下，位于键盘的左侧。

例如，左侧 Control 键、Macintosh 键盘上的左侧 Command 键或左侧 Shift 键。
DOM_KEY_LOCATION_RIGHT 0x02

该键是可能在键盘上多个位置存在的键，在这种情况下，位于键盘的右侧。

例如，右侧 Shift 键和右侧 Alt 键（Mac 键盘上的 Option 键）。
DOM_KEY_LOCATION_NUMPAD 0x03

该键位于数字键盘上，或者如果该键可能来自多个位置，则与数字键盘关联的虚拟键。NumLock 键不属于此组，并且始终使用位置 DOM_KEY_LOCATION_STANDARD 进行编码。

例如，数字键盘上的数字、键盘的 Enter 键和键盘上的小数点。

实例属性

此接口还继承了其父级 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 3级事件的旧版本。

实例方法

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

KeyboardEvent.getModifierState()

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

已弃用方法

KeyboardEvent.initKeyEvent()

初始化一个 KeyboardEvent 对象。这仅由 Firefox 实现，并且即使在那里也不再受支持；相反，您应该使用 KeyboardEvent() 构造函数。

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

注意：在 Linux 上，Firefox 12 及更早版本也为这些键分派了 keypress 事件。

但是，macOS 事件模型的限制导致 Caps Lock 仅分派 keydown 事件。Num Lock 在某些旧款笔记本电脑型号（2007 年及更早型号）上受支持，但从那时起，macOS 甚至在外部键盘上也不再支持 Num Lock。在具有 Num Lock 键的旧款 MacBook 上，该键不会生成任何键盘事件。如果连接了具有 F14 键的外部键盘，则 Gecko 支持 Scroll Lock 键。在 Firefox 的某些旧版本中，此键会生成 keypress 事件；这种不一致的行为是 Firefox 错误 602812。

自动重复处理

当按下并按住一个键时，它会开始自动重复。这会导致分派一系列类似于以下事件的事件

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<重复，直到用户释放键>>
  6. keyup

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

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

在某些基于 GTK 的环境中，自动重复会自动在自动重复期间分派本机 key-up 事件，并且 Gecko 无法区分一系列重复的 keypresses 和自动重复。因此，在这些平台上，自动重复键将生成以下事件序列

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. <<重复，直到用户释放键>>
  8. keyup

在这些环境中，不幸的是，Web 内容无法区分自动重复键和只是被重复按下的键。

示例

js
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}`);
    }
  },
  false,
);

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");
    }
  },
  false,
);

规范

规范
UI 事件
# interface-keyboardevent

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

浏览器兼容性

BCD 表格仅在浏览器中加载

兼容性说明

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

另请参阅