KeyboardEvent

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

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 US 键盘上的字母数字键、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 位置编码。

例如数字小键盘上的数字、小键盘上的回车键和小键盘上的小数点。

实例属性

此接口从其父类 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 事件模型的限制，大写锁定只能派发 keydown 事件。一些较旧的笔记本电脑型号（2007 年及以前的型号）支持数字锁定，但从那时起，即使在外置键盘上，macOS 也不支持数字锁定。在带有数字锁定键的旧款 MacBook 上，该键不会生成任何按键事件。如果连接了带有 F14 键的外置键盘，Gecko 确实支持滚动锁定键。在某些旧版本的 Firefox 中，该键会生成 keypress 事件；这种不一致的行为是 Firefox bug 602812。

处理自动重复

按下并按住一个键后，该键开始自动重复。这将导致一系列类似以下的事件发生：

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

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

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

在某些基于 GTK 的环境中，自动重复按键会在自动重复按键期间自动派发一个本地按键事件，而 Gecko 无法区分一系列重复按键和自动重复按键。因此，在这些平台上，自动重复按键将产生以下事件序列：

  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") {
      // 如果只按下了 Control 键，不要警告
      return;
    }

    if (event.ctrlKey) {
      // 即使 event.key 不为“Control”（如按下了“a“键），
      // 在同时按下了 Ctrl 键的情况下，event.ctrlKey 也可能为 true。
      alert(`ctrlKey + ${keyName} 组合`);
    } else {
      alert(`按下了 ${keyName} 键`);
    }
  },
  false,
);

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

    // 当用户释放了 Ctrl 键时，该键不再为激活状态，
    // 故 event.ctrlKey 为 false。
    if (keyName === "Control") {
      alert("释放了 Control 键");
    }
  },
  false,
);

规范

Specification
UI Events
# interface-keyboardevent

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

浏览器兼容性

BCD tables only load in the browser

兼容性说明

  • 从 Firefox 65 开始，非打印按键不再触发 keypress 事件（Firefox bug 968056），除

    Enter

    键，以及

    Shift

    +

    Enter

    和

    Ctrl

    +

    Enter

    组合键（保留这些内容是为了实现跨浏览器兼容）。

参见