UI 事件

1. 简介

1.1. 概述

UI 事件的设计有两个主要目标。第一个目标是设计一个 事件 系统，允许注册 事件监听器 并描述通过树结构的事件流。此外，该规范还将为用户界面控制和文档变动通知提供标准的事件模块，包括为这些事件模块中的每一个定义上下文信息。

UI 事件的第二个目标是提供当前现有浏览器所使用的事件系统的公共子集。这旨在促进现有脚本和内容的可互操作性。并不预期该目标能完全实现向后兼容。然而，本规范在可能的情况下尝试实现这一点。

1.1.1. 鼠标和滚轮事件

本规范的鼠标事件和滚轮事件部分已移至指针事件 (Pointer Events) 规范 [pointerevents4] 中。

1.2. 一致性

本节是规范性的。

在本规范中，关键词“必须 (MUST)”、“不得 (MUST NOT)”、“必要 (REQUIRED)”、“应 (SHALL)”、“不应 (SHALL NOT)”、“应该 (SHOULD)”、“不应 (SHOULD NOT)”、“推荐 (RECOMMENDED)”、“可以 (MAY)”和“可选 (OPTIONAL)”应按照 [RFC2119] 中的描述进行解释。

本规范应在 DOM Level 3 核心规范 [DOM-Level-3-Core] 的背景下理解，并且适用于 DOM 实现的一般性考虑事项。例如，命名空间 URI 的处理在 XML 命名空间 中进行了讨论。有关 一致性 的更多信息，请参阅 DOM Level 3 核心规范 [DOM-Level-3-Core]。一个 用户代理 不需要为了符合本规范而完全符合另一个规范，但必须符合本规范中所引用的其他规范的特定部分（例如，一个符合 UI 事件的 用户代理 必须支持 [WebIDL] 中定义的 DOMString 数据类型，但为了符合 UI 事件，不需要支持 [WebIDL] 中定义的每个方法或数据类型）。

本规范为不同的 用户代理、规范和内容作者定义了若干类一致性。

1.2.1. Web 浏览器及其他动态或交互式 用户代理

一个动态或交互式的 用户代理，在此处称为“浏览器”（无论是 Web 浏览器、辅助技术 (AT) 应用还是其他类似程序），若其支持以下内容，则符合 UI 事件：

• [DOM-Level-3-Core] 中定义的核心模块

• 本规范中定义的所有接口和事件及其相关的处理方法、属性和语义，但不包括那些标记为 已弃用 的部分（一个符合要求的用户代理可以出于向后兼容性而实现已弃用的接口、事件或 API，但为了符合要求，并不要求这样做）

• [UIEvents-Key] 和 [UIEvents-Code] 中定义的完整 key 和 code 值集（取决于平台可用性），以及

• 本规范中定义的所有其他规范性要求。

符合要求的浏览器必须在满足该 事件类型 定义的条件时，分发 (dispatch) 适用于给定 EventTarget 的事件。

如果浏览器实现了本文档指定的接口和相关 事件类型，则该浏览器特别符合 UI 事件。

符合要求的浏览器必须支持脚本、声明式交互或某种其他以本规范所描述的方式检测和分发事件的方法，并且必须支持为该 事件类型 指定的 API。

除了满足所有其他一致性标准外，符合要求的浏览器可以出于与现有内容的向后兼容性而实现本规范中标记为 已弃用 的功能，但不鼓励这种实现。

符合要求的浏览器还可以支持本规范中未发现的、但使用了本规范中定义的接口、事件或其他功能的功能，并且可以实现适用于该实现的附加接口和 事件类型。此类功能可以在未来的规范中进行标准化。

不符合本规范所有要求部分的浏览器不得声称符合 UI 事件。这种符合本规范部分内容的实现可以声称符合那些特定的部分。

符合要求的浏览器还必须是本规范中 IDL 片段的符合实现的 (conforming implementation)，如 Web IDL 规范 [WebIDL] 中所述。

1.2.2. 创作工具

如果内容创作工具生成的内容以本规范定义的方式一致地使用 事件类型，则该工具符合 UI 事件。

内容创作工具不得针对其生成的、使用了本规范中标记为 已弃用 功能的内容声称符合 UI 事件。

符合要求的内容创作工具应该向内容作者提供一种方法，以在正在生成的内容文档中使用适用于所有 宿主语言 的所有 事件类型 和接口。

1.2.3. 内容作者和内容

如果内容以本规范定义的方式一致地使用 事件类型，则内容 作者 创建的内容即为符合要求的 UI 事件内容。

内容作者不应使用本规范中标记为 已弃用 的功能，而应依赖本规范及其他地方定义的替代机制。

符合要求的内容必须按照本规范中的描述使用接口和 事件类型 的语义。

建议内容作者遵循 无障碍 和 国际化 指南规范中描述的最佳实践。

1.2.4. 规范和宿主语言

如果某规范或 宿主语言 引用并使用了 [DOM] 中定义的事件流机制、接口、事件或其他功能，并且没有以不兼容的方式扩展这些功能，则该规范或宿主语言符合 UI 事件。

如果某规范或 宿主语言 引用并使用了本文档指定的接口和相关 事件类型，则它特别符合 UI 事件。符合要求的规范可以定义适用于该规范的额外接口和 事件类型，或者可以以不与本规范中那些接口和 事件类型 的定义相矛盾或冲突的方式扩展 UI 事件接口和 事件类型。

引用 UI 事件的规范或 宿主语言 不应使用或推荐使用本规范中标记为 已弃用 的功能，而应使用或推荐使用该功能的指定替代品（如有）。

2. 文体惯例

本规范遵循 建议的 W3C 规范惯例，并附带以下补充：

• 键上印制的 键帽 (key cap) 显示为 ↓、= 或 Q。这用于从用户的角度指代按键，而不考虑生成的 KeyboardEvent 中的 key 和 code 值。

• 代表字符的字形显示为："𣧂"。

• Unicode 字符编码显示为：U+003d。

• 由按键生成的按键值名称（即 KeyboardEvent.key 的值）显示为："ArrowDown"、"="、"q" 或 "Q"。

• 与物理按键相关联的按键代码名称（即 KeyboardEvent.code 的值）显示为："ArrowDown"、"Equal" 或 "KeyQ"。

此外，本规范中某些术语具有特定含义。术语“实现 (implementation)”适用于实现本规范的浏览器、内容创作工具或其他 用户代理，而内容作者是编写脚本或代码的人，他们利用本规范中描述的接口、方法、属性、事件和其他功能来制作 Web 应用，用户则是该实现中这些 Web 应用的使用者。

最后

这是一个注释。

这是一个开放问题。

这是一个警告。

interface Example {
    // This is an IDL definition.
};

3. 基本事件接口

[DOM] 中定义的基本事件接口是 UI 事件的基础。实现必须始终支持这些基本事件接口。

• Event 接口及其以下常量、方法和属性：

  • NONE 常量

  • CAPTURING_PHASE 常量

  • AT_TARGET 常量

  • BUBBLING_PHASE 常量

  • type 属性

  • target 属性

  • currentTarget 属性

  • eventPhase 属性

  • bubbles 属性

  • cancelable 属性

  • composed 属性

  • timeStamp 属性

  • defaultPrevented 属性

  • isTrusted 属性

  • stopPropagation() 方法

  • stopImmediatePropagation() 方法

  • preventDefault() 方法

  • initEvent() 方法

• CustomEvent 接口及其以下方法和属性：

  • initCustomEvent() 方法

  • detail 属性

• EventTarget 接口及其以下方法：

  • addEventListener() 方法

  • removeEventListener() 方法

  • dispatchEvent() 方法

• EventListener 接口及其 handleEvent() 方法

• Document 接口的 createEvent() 方法

本规范定义的事件类型派生自这些基本接口，并且必须继承它们所派生的接口的所有属性、方法和常量。

下表描述了本规范所描述接口的继承结构。

3.1. 事件类型列表

每个事件必须与一个类型相关联，该类型称为 事件类型 (event type)，并作为事件对象上的 type 属性提供。事件类型必须是 DOMString 类型。

根据 DOM 支持的级别或用于显示（例如屏幕）或交互（例如鼠标、键盘、触摸屏或语音）的设备，这些事件类型可以由实现生成。当与 [XML] 或 [HTML5] 应用一起使用时，这些语言的规范可能会限制与事件类型相关联的语义和范围（特别是可能的 事件目标）。请参考定义所用语言的规范，以查找这些限制或查找本文档中未定义的事件类型。

下表提供了本规范中描述的事件类型的说明性摘要。

有关本规范中已弃用的事件列表，请参阅本文档末尾的 遗留事件类型 附录。

以下是解读上述表格的一种方式：load 事件将触发附加在 Element 节点上的、针对该事件以及捕获和目标阶段的 事件监听器。此事件不可取消。如果 load 事件的 事件监听器 附加在除 Window、Document 或 Element 节点之外的节点上，或者仅附加在冒泡阶段，则该 事件监听器 将不会被触发。

不要将上述表格视为对所列事件类型的最终定义。例如，load 事件在其他规范中也有使用，例如 XMLHttpRequest。同样，dispatchEvent() 可用于将不可信事件分发给任何也实现了 EventTarget 的对象上的监听器。

上述事件类型所关联的事件对象包含额外的上下文信息——请参考 DOM 接口的描述以获取进一步信息。

3.2. 用户界面事件

用户界面事件模块包含与用户界面和文档操作相关的基本事件类型。

3.2.1. UIEvent 接口

在 DOM Level 2 中引入

UIEvent 接口提供了与用户界面事件相关的特定上下文信息。

要创建 UIEvent 接口的实例，请使用 UIEvent 构造函数，并传递一个可选的 UIEventInit 字典。

对于新定义的事件，如果它们仅与用户界面相关，则不必继承 UIEvent 接口。仅在 UIEventInit 的成员对这些事件有意义时才继承。

3.2.1.1. UIEvent

[Exposed=Window]
interface UIEvent : Event {
  constructor(DOMString type, optional UIEventInit eventInitDict = {});
  readonly attribute Window? view;
  readonly attribute long detail;
};

UIEvent . view

view 属性标识了生成事件的 Window。

此属性的 未初始化值 必须为 null。

UIEvent . detail

指定关于 Event 的一些详细信息，具体取决于事件的类型。

此属性的 未初始化值 必须为 0。

3.2.1.2. UIEventInit

dictionary UIEventInit : EventInit {
  Window? view = null;
  long detail = 0;
};

UIEventInit . view

应初始化为将在其中分发此事件的全局环境的 Window 对象。如果此事件将分发给一个元素，则 view 属性应设置为包含该元素的 ownerDocument 的 Window 对象。

UIEventInit . detail

此值初始化为一个特定于应用的数字。

3.2.2. UIEvent 算法

3.2.3. UIEvent 类型

用户界面事件类型如下所示。其中一些事件如果是从用户界面生成，则使用 UIEvent 接口，否则使用 Event 接口，详情见每个事件。

3.2.3.1. load

当 DOM 实现完成加载资源（如文档）以及任何依赖资源（如图像、样式表或脚本）时，用户代理必须分发此事件。如果加载它们的资源仍然可以通过 DOM 访问，则加载失败的依赖资源不得阻止此事件触发。如果分发了此事件类型，实现必须至少在 Document 节点上分发此事件。

由于历史原因，文档内部资源（例如图像）的 load 事件在 HTML 实现中不包含传播路径中的 Window。更多信息请参阅 [HTML5]。

3.2.3.2. unload

当 DOM 实现从环境中移除资源（如文档）或任何依赖资源（如图像、样式表、脚本）时，用户代理必须分发此事件。文档必须在此事件类型分发后卸载。如果分发了此事件类型，实现必须至少在 Document 节点上分发此事件。

3.2.3.3. abort

当资源加载中止时（例如用户在加载仍在进行时取消加载），用户代理必须分发此事件。

3.2.3.4. error

当资源加载失败或已加载但无法根据其语义进行解释（如无效图像、脚本执行错误或格式不正确的 XML）时，用户代理必须分发此事件。

3.2.3.5. select

当用户选择某些文本时，用户代理必须分发此事件。此事件在选择发生后分发。

本规范不提供用于访问所选文本的上下文信息。在适用的情况下，宿主语言应定义有关用户如何选择内容（考虑到国际语言惯例）、在何时分发 select 事件以及内容作者如何访问用户所选内容的规则。

为了访问用户所选内容，内容作者将使用宿主语言的原生功能，例如 HTML 编辑 API [Editing] 的 Document.getSelection() 方法。

select 事件可能并非在所有语言的所有元素中都可用。例如，在 [HTML5] 中，select 事件只能在表单 input 和 textarea 元素上分发。实现可以在认为适用的任何上下文中分发 select 事件，包括表单控件之外的文本选择，或图像或标记选择（如在 SVG 中）。

3.3. 焦点事件

此接口及其相关事件类型和 § 3.3.2 焦点事件顺序 是根据 用户代理无障碍指南 2.0 (UAAG 2.0) [UAAG20] 中定义的概念和指南设计的，特别关注 焦点机制 和 焦点术语表条目 中定义的术语。

3.3.1. FocusEvent 接口

在本规范中引入

FocusEvent 接口提供了与焦点事件相关的特定上下文信息。

要创建 FocusEvent 接口的实例，请使用 FocusEvent 构造函数，并传递一个可选的 FocusEventInit 字典。

3.3.1.1. FocusEvent

[Exposed=Window]
interface FocusEvent : UIEvent {
  constructor(DOMString type, optional FocusEventInit eventInitDict = {});
  readonly attribute EventTarget? relatedTarget;
};

FocusEvent . relatedTarget

用于标识与焦点事件相关的次要 EventTarget，具体取决于事件类型。

出于嵌套浏览上下文的安全考虑，在通过 tab 键进入或移出嵌套上下文时，相关的 EventTarget 应为 null。

此属性的 未初始化值 必须为 null。

3.3.1.2. FocusEventInit

dictionary FocusEventInit : UIEventInit {
  EventTarget? relatedTarget = null;
};

FocusEventInit . relatedTarget

relatedTarget 应初始化为失去焦点的元素（对于 focus 或 focusin 事件）或获得焦点的元素（对于 blur 或 focusout 事件）。

3.3.2. 焦点事件顺序

本规范定义的焦点事件相对于彼此按预设顺序发生。以下是当焦点在元素之间切换时的典型事件序列（此顺序假设最初没有元素获得焦点）

本规范未定义与 focus() 或 blur() 等方法交互时的焦点事件行为。有关此类行为，请参阅定义这些方法的相应规范。

3.3.3. 文档焦点和焦点上下文

此事件模块包含用于通知文档 焦点 变化的事件类型。此讨论涉及三个截然不同的焦点上下文：

• 操作系统焦点上下文，可能位于计算机上当前运行的众多不同应用程序之一上。这些具有焦点的应用程序之一可以是浏览器。

• 当浏览器获得焦点时，用户可以（例如使用 tab 键）在不同的浏览器用户界面字段（例如网站地址栏、搜索栏等）之间切换 应用程序焦点上下文。这些用户界面字段之一可以是标签页中显示的文档。

• 当文档本身获得焦点时，文档焦点上下文可以设置为文档中任何可获得焦点的元素。

本规范中定义的事件类型仅涉及文档焦点，并且在事件详情中标识的 事件目标 必须仅是文档或窗口中文档的一部分，绝不是浏览器或操作系统的一部分，即使在从一个焦点上下文切换到另一个焦点上下文时也是如此。

通常，文档始终有一个获得焦点的元素（即使它是文档元素本身）和一个持久的 焦点环。在切换焦点上下文时，文档当前获得焦点的元素和焦点环通常保持其当前状态。例如，如果一个文档有三个可获得焦点的元素，且第二个元素获得焦点，当用户将操作系统焦点切换到另一个应用然后再切换回浏览器时，第二个元素在文档中仍将保持焦点，并且按 tab 键会将焦点切换到第三个元素。宿主语言可以定义哪些元素可以获得焦点、元素可以获得焦点的条件、切换焦点的方法以及焦点切换的顺序。例如，在某些情况下，可以通过将指针移动到元素上来赋予其焦点，而在其他情况下则可能需要鼠标点击。有些元素可能根本无法获得焦点，有些可能只能通过特殊手段（点击该元素）而不是通过 tab 键获得焦点。文档可能包含多个焦点环。其他规范可能定义比本规范中描述的更复杂的焦点模型，包括允许同时有多个元素获得焦点。

3.3.4. 焦点事件类型

焦点事件类型列出如下。

3.3.4.1. blur

当 事件目标 失去焦点时，用户代理必须分发此事件。在分发此事件类型之前，焦点必须从该元素中移除。此事件类型与 focusout 类似，但不冒泡。

3.3.4.2. focus

当 事件目标 获得焦点时，用户代理必须分发此事件。在分发此事件类型之前，焦点必须赋予该元素。此事件类型与 focusin 类似，但不冒泡。

3.3.4.3. focusin

当 事件目标 获得焦点时，用户代理必须分发此事件。该 事件目标 必须是获得焦点的元素。focus 事件必须在分发此事件类型之前触发。此事件类型与 focus 类似，但会冒泡。

3.3.4.4. focusout

当 事件目标 失去焦点时，用户代理必须分发此事件。该 事件目标 必须是失去焦点的元素。blur 事件必须在分发此事件类型之前触发。此事件类型与 blur 类似，但会冒泡。

3.4. 输入事件

输入事件会在用户操作（例如在可编辑区域进行键盘输入、删除或格式化文本等）直接导致 DOM 被更新（或即将被更新）时作为通知发送。

3.4.1. InputEvent 接口

3.4.1.1. InputEvent

在 DOM Level 3 中引入

[Exposed=Window]
interface InputEvent : UIEvent {
  constructor(DOMString type, optional InputEventInit eventInitDict = {});
  readonly attribute USVString? data;
  readonly attribute boolean isComposing;
  readonly attribute DOMString inputType;
};

data, 类型为 USVString, 只读, 可为空

data 保存由输入法生成的字符的值。这可以是一个 Unicode 字符或一个非空的 Unicode 字符序列 [Unicode]。字符应按照 [UAX15] 中定义的 Unicode 规范化形式 NFC 进行规范化。此属性可以包含 空字符串。

此属性的 未初始化值 必须为 null。

isComposing, 类型为 boolean, 只读

如果输入事件作为组合会话的一部分发生，则为 true，即在 compositionstart 事件之后且在相应的 compositionend 事件之前。

此属性的 未初始化值 必须为 false。

inputType, 类型为 DOMString, 只读

inputType 包含一个标识与该事件关联的输入类型的字符串。

有关此属性的有效值列表，请参考 [Input-Events] 规范。

此属性的 未初始化值 必须是空字符串 ""。

3.4.1.2. InputEventInit

dictionary InputEventInit : UIEventInit {
  DOMString? data = null;
  boolean isComposing = false;
  DOMString inputType = "";
};

data, 类型为 DOMString, 可为空, 默认为 null

初始化 InputEvent 对象的 data 属性。

isComposing, 类型为 boolean, 默认为 false

初始化 InputEvent 对象的 isComposing 属性。

inputType, 类型为 DOMString，默认为 ""

初始化 InputEvent 对象的 inputType 属性。

3.4.2. 输入事件顺序

本规范中定义的输入事件彼此之间必须按照特定的顺序发生。

3.4.3. 输入事件类型

3.4.3.1. beforeinput

用户代理在 DOM 即将更新时必须分发此事件。

3.4.3.2. input

用户代理必须在 DOM 更新后立即分发此事件。

3.5. 键盘事件

键盘事件与设备相关，即它们依赖于输入设备的功能以及它们在操作系统中的映射方式。有关更多详细信息，包括键盘事件与组合事件结合使用的示例，请参阅 键盘事件和键值。根据字符生成设备的不同，可能不会生成键盘事件。

键盘事件只是提供文本输入的一种模态。对于编辑场景，还可以考虑使用 InputEvent 作为键盘事件的替代方案（或补充）。

3.5.1. KeyboardEvent 接口

在本规范中引入

KeyboardEvent 接口提供了与键盘设备相关的特定上下文信息。每个键盘事件都使用一个值引用一个键。键盘事件通常针对当前获得焦点的元素。

KeyboardEvent 接口为一些常见的修饰键提供了便捷的属性：ctrlKey, shiftKey, altKey, metaKey。这些属性等效于使用 getModifierState() 方法并分别传入 Control, Shift, Alt 或 Meta 参数。

要创建 KeyboardEvent 接口的实例，请使用 KeyboardEvent 构造函数，并传入可选的 KeyboardEventInit 字典。

3.5.1.1. KeyboardEvent

[Exposed=Window]
interface KeyboardEvent : UIEvent {
  constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
  // KeyLocationCode
  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;

  readonly attribute DOMString key;
  readonly attribute DOMString code;
  readonly attribute unsigned long location;

  readonly attribute boolean ctrlKey;
  readonly attribute boolean shiftKey;
  readonly attribute boolean altKey;
  readonly attribute boolean metaKey;

  readonly attribute boolean repeat;
  readonly attribute boolean isComposing;

  boolean getModifierState(DOMString keyArg);
};

DOM_KEY_LOCATION_STANDARD

按键激活不应被区分作为该键的左侧或右侧版本，并且（除 NumLock 键外）不源自数字小键盘（或不源自对应于数字小键盘的虚拟键）。

PC 101 键美式键盘上的 Q 键。
PC 101 键美式键盘上的 NumLock 键。
位于键盘主区的 PC 101 键美式键盘上的 1 键。

DOM_KEY_LOCATION_LEFT

按键激活源自左侧按键位置（当该键有多个可能位置时）。

PC 101 键美式键盘上的左侧 Control 键。

DOM_KEY_LOCATION_RIGHT

按键激活源自右侧按键位置（当该键有多个可能位置时）。

PC 101 键美式键盘上的右侧 Shift 键。

DOM_KEY_LOCATION_NUMPAD

按键激活源自数字小键盘或对应于数字小键盘的虚拟键（当该键有多个可能位置时）。注意，NumLock 键应始终被编码为 location 为 DOM_KEY_LOCATION_STANDARD。

位于数字小键盘上的 PC 101 键美式键盘上的 1 键。

key, 类型为 DOMString，只读

key 保存对应于被按下的键的 键属性值。

key 属性与传统的 keyCode 属性无关，且不具备相同的值集。

此属性的 未初始化值 必须为 ""（空字符串）。

code, 类型为 DOMString，只读

code 保存一个标识正在被按下的物理键的字符串。该值不受当前键盘布局或修饰符状态的影响，因此特定的键始终返回相同的值。

此属性的 未初始化值 必须为 ""（空字符串）。

location, 类型为 unsigned long，只读

location 属性包含了关于该键在设备上逻辑位置的指示。

此属性必须设置为 DOM_KEY_LOCATION 常量之一，以指示键在设备上的位置。

如果 用户代理 允许重映射按键，则重映射后的键的 location 值必须设置为适合新键的值。例如，如果 "ControlLeft" 键被映射到 "KeyQ" 键，则 location 属性必须设置为 DOM_KEY_LOCATION_STANDARD。相反，如果 "KeyQ" 键被重映射到某个 Control 键之一，则 location 属性必须设置为 DOM_KEY_LOCATION_LEFT 或 DOM_KEY_LOCATION_RIGHT。

此属性的 未初始化值 必须为 0。

ctrlKey, 类型为 boolean，只读

如果 Control（控制）键修饰符处于活动状态，则为 true。

此属性的 未初始化值 必须为 false。

shiftKey, 类型为 boolean，只读

如果 shift（Shift）键修饰符处于活动状态，则为 true。

此属性的 未初始化值 必须为 false。

altKey, 类型为 boolean，只读

如果 Alt（备选）（或 "Option"）键修饰符处于活动状态，则为 true。

此属性的 未初始化值 必须为 false。

metaKey, 类型为 boolean，只读

如果 meta（Meta）键修饰符处于活动状态，则为 true。

Macintosh 系统上的 "Command" ("⌘") 键修饰符使用此键修饰符表示。

此属性的 未初始化值 必须为 false。

repeat, 类型为 boolean，只读

如果键被持续按下，则为 true。按住一个键必须导致重复触发事件 keydown、beforeinput 和 input，顺序如上，速率由系统配置决定。对于具有“长按键”行为的移动设备，第一个 repeat 属性值为 true 的键盘事件必须作为“长按”的指示。按键必须被按住多久才能开始重复取决于配置。

此属性的 未初始化值 必须为 false。

isComposing, 类型为 boolean，只读

如果键事件发生在组合会话期间（即在 compositionstart 事件之后且在相应的 compositionend 事件之前），则为 true。

此属性的 未初始化值 必须为 false。

getModifierState(keyArg)

使用键值查询修饰符的状态。

如果它是修饰键并且修饰符已激活，则返回 true；否则返回 false。

DOMString keyArg

修饰键的值。有效的 修饰键 定义在 [UIEvents-Key] 的 修饰键表 中。

如果应用程序希望区分左右修饰符，可以使用键盘事件和 location 推断此信息。

3.5.1.2. KeyboardEventInit

dictionary KeyboardEventInit : EventModifierInit {
  DOMString key = "";
  DOMString code = "";
  unsigned long location = 0;
  boolean repeat = false;
  boolean isComposing = false;
};

key, 类型为 DOMString，默认为 ""

将 KeyboardEvent 对象的 key 属性初始化为 Unicode 字符字符串，该字符串表示在考虑所有键盘修饰符（例如 shift 状态）后按键的含义。此值是键的最终有效值。如果该键不是可打印字符，则它应该是 [UIEvents-Key] 中定义的键值之一。

code, 类型为 DOMString，默认为 ""

将 KeyboardEvent 对象的 code 属性初始化为表示被按下键的 Unicode 字符字符串，忽略键盘布局等任何键盘修改。此值应为 [UIEvents-Code] 中定义的代码值之一。

location, 类型为 unsigned long，默认为 0

将 KeyboardEvent 对象的 location 属性初始化为以下位置数值常量之一

• DOM_KEY_LOCATION_STANDARD (数值 0)

• DOM_KEY_LOCATION_LEFT (数值 1)

• DOM_KEY_LOCATION_RIGHT (数值 2)

• DOM_KEY_LOCATION_NUMPAD (数值 3)

repeat, 类型为 boolean，默认为 false

初始化 KeyboardEvent 对象的 repeat 属性。如果当前的 KeyboardEvent 被视为由单个键长按导致的相似事件重复序列的一部分，则此属性应设置为 true，否则设置为 false。

isComposing, 类型为 boolean，默认为 false

初始化 KeyboardEvent 对象的 isComposing 属性。如果正在构造的事件作为组合序列的一部分发生，则此属性应设置为 true，否则设置为 false。

为了与现有内容兼容，虚拟键盘（例如屏幕输入设备上的软件键盘）即使没有物理按键，也被期望产生正常的键盘事件范围。

在某些实现或系统配置中，某些按键事件或其值可能会被使用的 IME 抑制。

3.5.2. 键盘事件键位置

location 属性可用于消除可能由键盘上不同物理按键生成的 key 值之间的歧义，例如左右 Shift 键，或者物理方向键与数字小键盘方向键（当 NumLock 关闭时）。

下表定义了在键盘上有多个位置的特殊键的有效 location 值

对于本表中未列出的所有其他键，location 属性必须始终设置为 DOM_KEY_LOCATION_STANDARD。

3.5.3. 事件修饰符初始化程序

MouseEvent 和 KeyboardEvent 接口共享一组键盘修饰符属性，并支持一种检索额外修饰符状态的机制。以下字典使作者能够初始化 MouseEvent 和 KeyboardEvent 接口的键盘修饰符属性，以及通过 getModifierState() 查询的额外修饰符状态。使用此字典构造鼠标事件的步骤定义在 [pointerevents4] 规范中。

dictionary EventModifierInit : UIEventInit {
  boolean ctrlKey = false;
  boolean shiftKey = false;
  boolean altKey = false;
  boolean metaKey = false;

  boolean modifierAltGraph = false;
  boolean modifierCapsLock = false;
  boolean modifierFn = false;
  boolean modifierFnLock = false;
  boolean modifierHyper = false;
  boolean modifierNumLock = false;
  boolean modifierScrollLock = false;
  boolean modifierSuper = false;
  boolean modifierSymbol = false;
  boolean modifierSymbolLock = false;
};

ctrlKey, 类型为 boolean，默认为 false

如果 Control 键修饰符被视为活动状态，则将 MouseEvent 或 KeyboardEvent 对象的 ctrlKey 属性初始化为 true，否则为 false。

当为 true 时，实现还必须初始化事件对象的键修饰符状态，使得当传入参数 Control 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

shiftKey, 类型为 boolean，默认为 false

如果 Shift 键修饰符被视为活动状态，则将 MouseEvent 或 KeyboardEvent 对象的 shiftKey 属性初始化为 true，否则为 false。

当为 true 时，实现还必须初始化事件对象的键修饰符状态，使得当传入参数 Shift 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

altKey, 类型为 boolean，默认为 false

如果 Alt（备选）（或 Option）键修饰符被视为活动状态，则将 MouseEvent 或 KeyboardEvent 对象的 altKey 属性初始化为 true，否则为 false。

当为 true 时，实现还必须初始化事件对象的键修饰符状态，使得当传入参数 Alt 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

metaKey, 类型为 boolean，默认为 false

如果 Meta 键修饰符被视为活动状态，则将 MouseEvent 或 KeyboardEvent 对象的 metaKey 属性初始化为 true，否则为 false。

当为 true 时，实现还必须初始化事件对象的键修饰符状态，使得当传入参数 Meta 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierAltGraph, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 AltGraph 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierCapsLock, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 CapsLock 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierFn, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 Fn 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierFnLock, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 FnLock 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierHyper, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 Hyper 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierNumLock, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 NumLock 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierScrollLock, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 ScrollLock 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierSuper, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 Super 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierSymbol, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 Symbol 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

modifierSymbolLock, 类型为 boolean，默认为 false

初始化事件对象的键修饰符状态，使得当传入参数 SymbolLock 时，调用 getModifierState() 或 getModifierState() 必须返回 true。

3.5.4. KeyboardEvent 算法

3.5.4.1. KeyboardEvent 的全局状态

3.5.4.1.1. 用户代理级状态

UA 必须维护以下在整个用户代理中共享的值：

一种 键修饰符状态（初始为空），用于跟踪系统上可用的每个 修饰键 的当前状态。

3.5.5. 键盘事件顺序

本规范中定义的键盘事件对于任何给定的键，彼此之间按照固定的顺序发生

如果键被持续按住，以下事件可能会以环境相关的速率重复

通常，与特定键关联的任何 默认动作 都会在 keyup 事件分发之前完成。这可能会稍微延迟 keyup 事件（尽管这不太可能是可感知的延迟）。

键事件的 事件目标 是当前处理键盘活动的获得焦点的元素。这通常是 HTML input 元素或可编辑的文本元素，但也可以是 宿主语言 定义的用于非文本用途的元素，例如激活加速键或触发某些其他行为。如果没有合适的元素获得焦点，事件目标将是 HTML body 元素（如果可用），否则为 根元素。

事件目标可能会在不同的键事件之间发生变化。例如，Tab 键的 keydown 事件的 事件目标 很可能与同一按键上的 keyup 事件不同。

3.5.6. 键盘事件类型

3.5.6.1. keydown

用户代理在按键被按下时必须分发此事件。keydown 事件类型与设备相关，依赖于输入设备的功能以及它们在操作系统中的映射方式。此事件类型必须在 键映射 之后生成。此事件类型必须在与同一按键相关联的 beforeinput、input 和 keyup 事件之前分发。

keydown 事件的默认动作取决于具体的键

• 如果该键与字符相关联，则默认动作必须是分发 beforeinput 事件，随后分发 input 事件。在键与多个字符关联（例如宏或某些死键序列）的情况下，默认动作必须是为每个字符分发一组 beforeinput / input 事件

• 如果该键与 文本组合系统 相关联，则默认动作必须是启动该系统

• 如果该键是 Tab 键，则默认动作必须是将文档焦点从当前获得焦点的元素（如果有）切换到新的焦点元素，如 焦点事件类型 所述

• 如果该键是 Enter 或  （空格）键，且当前焦点在状态改变元素上，则默认动作必须是分发 click 事件；如果 用户代理 支持该事件类型，则还需分发 DOMActivate 事件。

如果此事件被取消，则不应分发相关的事件类型，也不应执行相关的动作。

keydown 和 keyup 事件传统上与检测任何按键相关，而不限于那些产生 字符值 的按键。

3.5.6.2. keyup

用户代理在按键被释放时必须分发此事件。keyup 事件类型与设备相关，依赖于输入设备的功能以及它们在操作系统中的映射方式。此事件类型必须在 键映射 之后生成。此事件类型必须在与同一按键相关联的 keydown、beforeinput 和 input 事件之后分发。

keydown 和 keyup 事件传统上与检测任何按键相关，而不限于那些产生 字符值 的按键。

3.6. 组合事件

组合事件提供了一种以不同于键盘事件的方式输入文本的手段，以便使用键盘上可能不常见的字符。例如，组合事件可用于向字符添加变音符号（即使标准美式键盘上没有），从基础组件或类别构建多种亚洲语言的语标，从移动设备键盘上的组合按键中选择词语，或者使用语音识别处理器将语音命令转换为文本。有关如何将组合事件与键盘事件结合使用的示例，请参阅 § 4 键盘事件和键值。

从概念上讲，一个组合会话由一个 compositionstart 事件、一个或多个 compositionupdate 事件和一个 compositionend 事件组成，data 属性的值在每次会话的事件链的每个“阶段”之间保持不变。

注意：当组合会话处于活动状态时，如果键盘是与组合会话配合使用的输入设备，则键盘事件仍可分发到 DOM。有关相关事件顺序，请参见 compositionstart 事件详细信息和 IME 部分。

并非所有 IME 系统或设备都会向 DOM 公开必要的数据，因此活动的组合字符串（“阅读窗口”或“候选选择菜单选项”）可能无法通过此接口获取，在这种情况下，选择内容可以用 空字符串 表示。

3.6.1. Interface CompositionEvent

在本规范中引入

CompositionEvent 接口提供了与组合事件相关的特定上下文信息。

要创建 CompositionEvent 接口的实例，请使用 CompositionEvent 构造函数，并传入可选的 CompositionEventInit 字典。

3.6.1.1. CompositionEvent

[Exposed=Window]
interface CompositionEvent : UIEvent {
  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
  readonly attribute USVString data;
};

data, 类型为 USVString，只读

data 保存由输入法生成的字符值。这可以是单个 Unicode 字符或非空的 Unicode 字符序列 [Unicode]。字符应按照 [UAX15] 中定义的 Unicode 标准化形式 NFC 进行标准化。此属性可以是 空字符串。

此属性的 未初始化值 必须为 ""（空字符串）。

3.6.1.2. CompositionEventInit

dictionary CompositionEventInit : UIEventInit {
  DOMString data = "";
};

data, 类型为 DOMString，默认为 ""

将 CompositionEvent 对象的 data 属性初始化为 IME 组合生成的字符。

3.6.2. 组合事件顺序

本规范中定义的组合事件彼此之间必须按照以下固定顺序发生

3.6.3. 手写识别系统

以下示例描述了使用手写识别系统（例如在绘图板上）编写文本段落“text”时可能发生的事件序列，使用组合事件建模。

3.6.4. 取消组合事件

如果 keydown 事件被取消，则不应分发任何原本作为该 keydown 结果触发的组合事件

如果初始的 compositionstart 事件被取消，则文本组合会话应终止。无论组合会话是否终止，都必须发送 compositionend 事件。

3.6.5. 组合期间的键事件

在组合会话期间，仍必须发送 keydown 和 keyup 事件，并且这些事件必须将 isComposing 属性设置为 true。

3.6.6. 组合期间的输入事件

在组合会话期间，必须在发送 beforeinput 之后但在发送 input 事件之前分发 compositionupdate。

大多数 IME 不支持在组合会话期间取消更新。

只要 DOM 作为组合的一部分被更新，beforeinput 和 input 事件就会与 compositionupdate 事件一起发送。由于与 compositionend 事件关联的 DOM 更新不存在，因此不应在该时间发送 beforeinput 和 input 事件。

3.6.7. 组合事件类型

3.6.7.1. compositionstart

用户代理在启用 文本组合系统 且新的组合会话即将开始（或已经开始，取决于 文本组合系统）以为组合文本段落做准备时，必须分发此事件。此事件类型与设备相关，且可能依赖于文本转换系统的功能及其在操作系统中的映射方式。当使用键盘为输入法编辑器提供输入时，此事件类型在 keydown 事件之后生成，但语音或手写识别系统可能在没有键盘事件的情况下发送此事件类型。某些实现可能使用文档中当前选定的文本（用于编辑和替换）来填充 compositionstart 事件的 data 属性。否则，data 属性的值必须是 空字符串。

此事件必须在 文本组合系统 开始新的组合会话之前以及由于组合过程导致 DOM 被修改之前立即分发。此事件的默认动作是 文本组合系统 开始新的组合会话。如果此事件被取消，文本组合系统 应放弃当前的组合会话。

取消 compositionstart 事件类型 不同于取消 文本组合系统 本身（例如通过点击取消按钮或关闭 IME 窗口）。

某些 IME 不支持取消正在进行的组合会话（例如 GTK 目前没有这样的 API）。在这些情况下，调用 preventDefault() 将不会停止此事件的默认动作。

3.6.7.2. compositionupdate

当文本组合系统使用新字符更新其活动文本段落（该更新反映在 data 字符串中）时，用户代理应（SHOULD）触发此事件。

在将正在进行的组合与输入控件保持同步的文本组合系统中，必须（MUST）在更新控件之前触发 compositionupdate 事件。

一些文本组合系统可能不会将此信息暴露给 DOM，在这种情况下，此事件在组合过程中不会触发。

如果组合会话被取消，此事件将在 compositionend 事件之前立即触发，并且 data 属性将被设置为空空字符串。

3.6.7.3. compositionend

当文本组合系统完成或取消当前组合会话时，用户代理必须（MUST）触发此事件；compositionend 事件必须（MUST）在控件更新后触发。

此事件在文本组合系统完成组合会话后立即触发（例如：IME 关闭、最小化、失去焦点或以其他方式被取消，且焦点切回到用户代理）。

4. 键盘事件和键值

本节包含有关键盘事件的必要信息。

• 键盘布局、映射和键值的解释。

• 键之间的关系，例如死键（dead keys）或修饰键。

• 键盘事件与默认行为之间的关系。

• key 值集合，以及如何扩展该集合的指南。

本节使用了塞尔维亚语和日语汉字，在 PDF 版本或打印版本中可能会显示异常或无法显示。

4.1. 键盘输入

本节为非规范性内容

每个键与完整键盘之间的关系有三个不同的方面，每个方面因键盘的型号和配置（特别是由于区域设置）而异：

• 机械布局：键盘上物理按键的尺寸、大小和位置。

• 视觉标记：标记每个键的标签（或称图例）。

• 功能映射：每个键的抽象键值关联。

本规范仅定义了功能映射，具体表现为 key 值和 code 值，但简要描述了键图例以提供背景信息。

4.1.1. 键图例

本节具有资料性质

键图例是印制或压印在键帽（覆盖按键机械开关的矩形“盖子”）上的视觉标记。这些标记通常由一个或多个按键将产生的字符组成（例如 "G"、"8" 或 "ш"），或者是指示该键功能的名称或符号（例如指向上的箭头 "⇧" 表示 Shift，或者字符串 "Enter"）。按键通常按此标记引用（例如：“按 "Shift" 和 "G" 键”）。但请注意，按键的视觉外观与其数字表示无关，在许多配置中甚至可能完全不准确。即使是控制键和功能键（如 Enter），也可能被映射到不同的功能，甚至被映射为字符键。

许多键盘包含通常不产生任何字符的键，即使该符号可能具有 Unicode 等效项。例如，Shift 键可能带有符号 "⇧"，其 Unicode 码点为 U+21E7，但按下 Shift 键不会产生此字符值，且 Shift 没有对应的 Unicode 码点。

4.2. 键码

键 code 是键盘事件的一个属性，可用于识别与该事件关联的物理按键。它类似于 USB 使用 ID，因为它提供了一个与供应商无关的底层值（类似于扫描码）。

code 属性的主要目的是提供一种基于物理位置识别按键的一致且连贯的方法。此外，它还提供了一个稳定名称（不受当前键盘状态影响），用于唯一标识键盘上的每个按键。

有效的 code 值列表定义在 [UIEvents-Code] 中。

4.2.1. code 属性的动机

标准 PC 键盘有一组按键（我们称之为书写系统键），它们根据用户选择的当前键盘布局生成不同的 key 值。这种情况使得编写基于物理位置检测按键的代码变得困难，因为代码需要知道当前生效的布局，才能确定检查哪些 key 值。一个现实世界的例子是：想要使用 "W"、"A"、"S" 和 "D" 键来控制玩家移动的游戏。code 属性通过提供一个不受当前键盘布局影响的稳定值来解决这个问题。

此外，key 属性中的值也取决于当前的键盘状态。因此，相对于修饰键按下和释放的顺序可能会影响存储在 key 属性中的值。code 属性通过提供一个不受当前键盘状态影响的稳定值解决了这个问题。

4.2.2. key 和 code 之间的关系

key

key 属性旨在服务于关心所按按键含义的用户，它会考虑当前的键盘布局（以及 IME；死键被赋予唯一的 key 值）。使用场景示例：检测组合键或纯修饰键（例如，执行快捷键操作）。

code

code 属性旨在服务于关心用户按下了哪个物理键的用户，无需应用任何布局修改。使用场景示例：检测 WASD 键（例如，游戏中的移动控制）或捕获所有按键（例如，远程桌面客户端将所有按键发送到远程主机）。

4.2.3. code 示例

4.2.4. code 和虚拟键盘

code 属性在虚拟键盘（以及遥控器和和弦键盘）上的用处并不那么明显。通常，如果虚拟键盘（或遥控器）正在模仿标准键盘的布局和功能，那么它也必须（MUST）适当地设置 code 属性。对于不模仿标准键盘布局的键盘，code 属性可以设置为标准键盘上最接近的匹配项，也可以保持未定义。

对于具有根据某些修饰状态产生不同值的按键的虚拟键盘，code 值应为设备处于出厂重置状态时按下按钮所生成的 key 值。

4.3. 键盘事件 key 值

键值是一个 DOMString，可用于通过其产生的值来指示键盘上的任何给定按键，无论其位置或状态如何。这些键值可以用作实现生成的键盘事件的返回值，也可以由内容作者用作输入值来指定所需的输入（例如用于键盘快捷键）。

有效的 key 值列表定义在 [UIEvents-Key] 中。

键值可用于检测已按下的键的值，使用 key 属性。内容作者可以检索大写或小写字母、数字、符号或其他产生字符的按键的字符值，以及控制键、修饰键、功能键或其他不产生字符的按键的键值。这些值可用于监控特定的输入字符串、结合其他输入（如鼠标）来检测并对修饰键输入采取行动、创建虚拟键盘或用于许多其他目的。

键值还可由内容作者用于字符串比较、作为合规宿主语言中标记属性（如 HTML accesskey）的值，或用于其他相关目的。合规的宿主语言应（SHOULD）允许内容作者使用键值的两种等效字符串值之一：字符值或键值。

虽然实现将独立于平台或键盘布局映射使用键的最相关值，但内容作者不能假设键盘设备有能力生成它们。当使用键盘事件和键值进行快捷键组合时，内容作者可以“考虑使用数字和功能键（F4, F5 等）而不是字母”([DWW95])，因为大多数键盘布局都会提供这些按键。

键值并不指示物理键盘上的特定键，也不反映印在键上的字符。键值指示事件的当前值，并考虑所有活动键和键输入模式（包括 Shift 模式）的当前状态，这反映在操作系统的键盘映射中并报告给实现。换句话说，在QWERTY键盘上标记为 O 的键，在未按下 Shift 的状态下具有键值 "o"，在按下 Shift 的状态下具有键值 "O"。由于用户可以将他们的键盘映射到任意自定义配置，鼓励内容作者不要假设键的移位状态和非移位状态与字符表示的大写形式（upper-case or capital letters）和小写形式（lower-case or small letters）之间存在关系，而是鼓励使用 key 属性的值。例如，[UIEvents-Code] 中描述的标准“102”键盘布局说明了一种可能键盘布局上的一组可能的键映射。存在许多其他的映射，包括标准的和独特的。

为了简化死键支持，当操作系统的键盘映射正在处理死键状态时，死键序列的当前状态不会通过 key 属性报告。相反，报告的键值为 "Dead"。实现会生成组合事件，其中包含通过 data 属性报告的死键序列的中间状态。正如前一个示例所示，在QWERTY键盘上标记为 O 的键，在死键操作中添加元音变音符号（umlaut diacritic）的未按下 Shift 状态下，其 data 值为 "ö"；在按下 Shift 状态下，其值为 "Ö"。

同样重要的是要注意，键事件状态和键值之间不是一对一的关系。一个特定的键值可能与多个键相关联。例如，许多标准键盘包含多个具有 Shift 键值的键（通常通过 location 值 DOM_KEY_LOCATION_LEFT 和 DOM_KEY_LOCATION_RIGHT 区分）或 8 键值（通常通过 location 值 DOM_KEY_LOCATION_STANDARD 和 DOM_KEY_LOCATION_NUMPAD 区分），用户自定义的键盘布局可能在多种键状态场景下重复任何键值（请注意，location 旨在用于标准键盘布局，并不总能指示有意义的区别）。

最后，任何给定字符表示的含义是上下文相关的且复杂的。例如，在某些上下文中，星号（star）符号（"*"）代表脚注或强调（当括号括起一段文本时）。然而，在某些文档或可执行程序中，它等同于数学乘法运算，而在其他文档或可执行程序中，该功能保留用于乘法符号（"×"，Unicode 值 U+00D7）或拉丁小写字母 "x"（由于许多键盘上缺乏乘法键以及符号 "×" 和 "x" 的表面相似性）。因此，字符表示的语义含义或功能超出了本规范的范围。

4.3.1. 修饰键

键盘输入使用修饰键来改变按键的正常行为。与其他键一样，修饰键生成 keydown 和 keyup 事件，如下例所示。一些修饰符在按键被按下或保持按下时激活，例如 Alt、Control、Shift、AltGraph 或 Meta。其他修饰符根据其状态激活，例如 CapsLock、NumLock 或 ScrollLock。状态的改变发生在修饰键被按下的时刻。KeyboardEvent 接口为一些常见的修饰键提供了方便的属性：ctrlKey、shiftKey、altKey、metaKey。一些操作系统使用 Alt 和 Control 修饰键的组合来模拟 AltGraph 修饰键。鼓励实现使用 AltGraph 修饰键。

keydown 和 keyup 事件中的值会根据按键时生效的当前键盘布局而变化。这意味着美式布局上的 v 键和阿拉伯语布局上的 ر 键将产生不同的事件，即使它们是同一个物理按键。要识别这些事件来自同一个物理按键，您需要利用 code 属性。

在某些情况下，修饰键会改变键事件的 key 值。例如，在某些 MacOS 键盘上，标记为“delete”的键在未被修饰时与 Windows OS 上的 Backspace 键功能相同；但当被 Fn 键修饰时，它充当 Delete 键，并且 key 的值将匹配该键在当前修饰状态下最合适的功能。

4.3.2. 死键（Dead keys）

一些键盘输入使用死键来输入组合字符序列。与用户先输入基字符的手写序列不同，键盘输入需要在一个死键被按下时进入一种特殊状态，并仅在输入了有限数量的“合法”基字符之一时才输出字符。

MacOS 和 Linux 操作系统使用输入法来处理死键。

死键（在所有键盘布局和映射中）由键值 Dead 表示。响应任何死键按下时，组合事件必须由用户代理触发，并且 compositionupdate 事件的 data 值必须是死键组合序列当前状态的字符值。

虽然 Unicode 组合字符总是遵循手写序列（组合字符跟在相应的字母之后），但典型的死键输入可能会反转该序列，即将组合字符置于相应的字母之前。例如，使用组合变音符号 ¨ 的单词 naïve，在 Unicode 中按序列表示为 nai¨ve，但输入时可能会输入为 na¨ive。按键序列 U+0302（组合扬抑符键）和 U+0065（标有拉丁小写字母 E 的键）很可能会产生（在使用法语映射且未激活任何修饰符的法语键盘上）Unicode 字符 "ê"（带有扬抑符的拉丁小写字母 E），这正是 Unicode 规范化形式 NFC 所偏好的形式。

在第二个 keydown 事件（第 5 步）中，在正常情况下，键值（假设事件未被抑制）将不是 "e"（拉丁小写字母 E 键），因为传递给用户代理的值已经被死键操作修改了。

当用户在按下死键后输入不支持的基字符（即活动变音符号不可用的基字符）时，此过程可能会中止。

4.3.3. 输入法编辑器（Input Method Editors）

本规范通过 CompositionEvent 接口和事件包含了输入法编辑器（IME）的模型。然而，组合事件和键盘事件并不一定是一对一的关系。例如，接收到 Accept 键值的 keydown 事件并不一定意味着当前在 IME 中选择的文本正在被接受，它仅表明发生了一次按键操作，与 IME 的“接受”功能脱节（在大多数 IME 系统中，该功能通常会导致 compositionend 事件）。键盘事件无法用于确定输入法编辑器的当前状态，该状态可通过 CompositionEvent 接口的 data 属性获取。此外，IME 系统和设备的功能各不相同，用于激活该功能的按键也不尽相同，因此 Convert 和 Accept 键可以由其他可用按键表示。键盘事件对应于键盘布局映射后输入设备生成的事件。

在某些实现或系统配置中，一些键事件或其值可能会被正在使用的 IME 抑制。

以下示例描述了使用日语输入法生成 Unicode 字符 "市"（汉字，CJK 统一表意文字的一部分）的可能按键序列。此示例假设已激活输入法编辑器并处于日语-罗马字输入模式。根据所使用的输入设备和 IME 的配置，键 Convert 和 Accept 可以被其他键替换，例如它们可以分别是 U+0020（空格键）和 Enter。

"詩"（诗歌）和 "市"（城市）是同音词，读音均为 し (shi/si)，因此用户需要使用 Convert 键来选择正确的选项。

IME 组合也可以像以下示例一样取消，条件与前一个示例相同。根据所使用的输入设备和 IME 的配置，Cancel 键也可以被其他键替换，例如它可以是 U+001B（Escape 键）。

一些输入法编辑器（例如在 MacOS 操作系统上）可能会在取消组合之前将空字符串设置到组合数据属性中。

4.3.3.1. 输入法编辑器模式键

某些设备上的某些键旨在激活输入法编辑器功能，或更改活动输入法编辑器的模式。可以为不同的设备或语言模式定义用于此目的的自定义键。本规范为此目的定义的键包括："Alphanumeric", "CodeInput", "FinalMode", "HangulMode", "HanjaMode", "Hiragana", "JunjaMode", "KanaMode", "KanjiMode", "Katakana", 和 "Romaji"。当按下其中一个键且当前未激活 IME 时，预期的适当 IME 将以该键指示的模式激活（如果可用）。如果按下该键时 IME 已经激活，则活动的 IME 可能会更改为指示的模式，或者可能会启动不同的 IME，或者在设备和应用程序特定基础上忽略该按键。

本规范还定义了其他旨在专门与输入法编辑器配合操作的键："Accept", "AllCandidates", "Cancel", "Convert", "Compose", "Zenkaku" (全角), "Hankaku" (半角), "NextCandidate", "NonConvert", 和 "PreviousCandidate"。这些键的功能未在本规范中定义——有关输入法编辑器功能的详细信息，请参阅其他资源。

具有输入法编辑器功能的键并不局限于该目的，还可以具有其他设备或实现特定的目的。

4.3.4. 默认行为和可取消的键盘事件

取消 keydown 事件的默认行为不得影响其相应的 keyup 事件，但必须防止生成相应的 beforeinput 和 input（以及如果支持的话，keypress）事件。以下示例描述了在美式键盘上使用美式映射生成 Unicode 字符 Q（拉丁大写字母 Q）时可能发生的按键序列。

如果该键是修饰键，则按键仍必须计入修饰符状态。以下示例描述了在美式键盘上使用美式映射生成 Unicode 字符 Q（拉丁大写字母 Q）时可能发生的按键序列。

如果该键是几个按键序列的一部分，无论它是死键还是有助于输入法编辑器序列的键，仅当在 keydown 事件上取消默认行为时，按键才必须被忽略（不计入）。在 keyup 事件上取消死键对 beforeinput 或 input 事件没有影响。以下示例在法语键盘上使用法语映射且未激活任何修饰符的情况下，使用了死键 "Dead"（U+0302 组合扬抑符键）和 "e"（U+0065，拉丁小写字母 E 键）。

5. 外部算法

本节包含本规范所要求的算法，但由其他规范托管更为恰当。

其目的是让本节作为这些定义的临时存放处，它们最终应移动到更合适的宿主，以便可以删除整个本节。

5.1. 核心 DOM 算法

以下算法应移动到……某个地方。

5.2. PointerLock 算法

以下算法应移动到 [PointerLock] 规范中。

5.2.1. PointerLock 的全局状态

5.2.1.1. 窗口级状态

UA 必须维护以下在窗口中共享的值：

一个 最后鼠标移动 值（最初未定义），记录最后一次 mousemove 事件的位置。

6. 遗留事件初始化器

本节是规范性的。以下功能已过时，仅应由需要与遗留软件兼容的用户代理实现。

本规范的早期版本在接口上包含了一个初始化方法（例如 initMouseEvent），该方法需要长参数列表，在大多数情况下，这些参数无法完全初始化事件对象的所有属性。因此，从基本 Event 接口派生的事件接口要求显式调用每个派生接口的初始化器，以便完全初始化事件。

部分由于本标准开发时间较长，某些实现可能已对这些（现已弃用）初始化器方法产生了依赖。为了完整起见，这些遗留事件初始化器在本附录中进行了描述。

6.1. 遗留事件初始化器接口

本节具有资料性质

本节记录了在本规范早期版本中引入的遗留初始化器方法。

6.1.1. UIEvent 接口的初始化器

partial interface UIEvent {
  // Deprecated in this specification
  undefined initUIEvent(DOMString typeArg,
    optional boolean bubblesArg = false,
    optional boolean cancelableArg = false,
    optional Window? viewArg = null,
    optional long detailArg = 0);
};

initUIEvent(typeArg)

初始化 UIEvent 对象的属性。此方法具有与 initEvent() 相同的行为。

initUIEvent 方法已弃用，但为了与广泛部署的实现向后兼容而提供支持。

DOMString typeArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean bubblesArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean cancelableArg

有关此参数的描述，请参阅 initEvent() 方法。

Window? viewArg

指定 view。此值可以是 null。

long detailArg

指定 detail。

6.1.2. KeyboardEvent 接口的初始化器

此遗留 KeyboardEvent 初始化器的参数列表不包括 detailArg（存在于其他初始化器中），并添加了 locale 参数；为与现有实现兼容，必须保留此不一致性。

partial interface KeyboardEvent {
  // Originally introduced (and deprecated) in this specification
  undefined initKeyboardEvent(DOMString typeArg,
    optional boolean bubblesArg = false,
    optional boolean cancelableArg = false,
    optional Window? viewArg = null,
    optional DOMString keyArg = "",
    optional unsigned long locationArg = 0,
    optional boolean ctrlKey = false,
    optional boolean altKey = false,
    optional boolean shiftKey = false,
    optional boolean metaKey = false);
};

initKeyboardEvent(typeArg)

初始化 KeyboardEvent 对象的属性。此方法具有与 UIEvent.initUIEvent() 相同的行为。detail 的值保持未定义。

initKeyboardEvent 方法已弃用。

DOMString typeArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean bubblesArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean cancelableArg

有关此参数的描述，请参阅 initEvent() 方法。

Window? viewArg

指定 view。此值可以是 null。

DOMString keyArg

指定 key。

unsigned long locationArg

指定 location。

boolean ctrlKey

指定 Control 键修饰符是否激活。

boolean altKey

指定 Alt 键修饰符是否激活。

boolean shiftKey

指定 Shift 键修饰符是否激活。

boolean metaKey

指定 Meta 键修饰符是否激活。

6.1.3. CompositionEvent 接口的初始化器

此遗留 CompositionEvent 初始化器的参数列表不包括 detailArg（存在于其他初始化器中），并添加了 locale 参数；为与现有实现兼容，必须保留此不一致性。

partial interface CompositionEvent {
  // Originally introduced (and deprecated) in this specification
  undefined initCompositionEvent(DOMString typeArg,
    optional boolean bubblesArg = false,
    optional boolean cancelableArg = false,
    optional WindowProxy? viewArg = null,
    optional DOMString dataArg = "");
};

initCompositionEvent(typeArg)

初始化 CompositionEvent 对象的属性。此方法具有与 UIEvent.initUIEvent() 相同的行为。detail 的值保持未定义。

initCompositionEvent 方法已弃用。

DOMString typeArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean bubblesArg

有关此参数的描述，请参阅 initEvent() 方法。

boolean cancelableArg

有关此参数的描述，请参阅 initEvent() 方法。

Window? viewArg

指定 view。此值可以是 null。

DOMString dataArg

指定 data。

7. 遗留键和鼠标事件属性

本节是非规范性的。以下属性已过时，仅应由需要与需要这些键盘事件的遗留软件兼容的用户代理实现。

这些功能从未正式指定，目前的浏览器实现存在显著差异。大量依赖检测用户代理并采取相应行动的遗留内容（包括脚本库）意味着，任何正式化这些遗留属性和事件的尝试都可能破坏与它修复或启用的一样多的内容。此外，这些属性不适合国际化使用，也没有解决无障碍性问题。

因此，本规范没有对处理键盘输入时常用的事件和属性进行规范定义，尽管它们为了与遗留内容兼容，可能存在于用户代理中。作者应（SHOULD）使用 key 属性，而不是 charCode 和 keyCode 属性。

然而，为了记录这些功能的当前状态及其与规范事件和属性的关系，本节提供了一个信息性描述。对于支持这些属性和事件的实现，建议使用本节中提供的定义。

7.1. 遗留 UIEvent 补充接口

本节为非规范性内容

用户代理传统上包含了 which 属性，以便 KeyboardEvent 和 MouseEvent 可以记录补充事件信息。

本规范的早期版本在 KeyboardEvent 和 MouseEvent 上直接定义了单独的 which 属性，而不是在 UIEvent 上定义共享的 which 属性。

7.1.1. UIEvent 接口（补充）

部分 UIEvent 接口是 UIEvent 接口的信息性扩展，增加了 which 属性。

partial interface UIEvent {
  // The following support legacy user agents
  readonly attribute unsigned long which;
};

which， 类型为 unsigned long，只读

对于 MouseEvent，此属性包含的值等于 button+1。对于 KeyboardEvent，此属性保存一个依赖于系统和实现的数值代码，表示与按下按键关联的未修饰标识符。在大多数情况下，该值与 keyCode 相同。

7.1.2. 接口 UIEventInit（补充）

在 UIEvent 中支持 which 的浏览器也应将以下成员添加到 UIEventInit 字典中。

部分 UIEventInit 字典是 UIEventInit 字典的提示性扩展，它添加了 which 成员以初始化相应的 UIEvent 属性。

partial dictionary UIEventInit {
  unsigned long which = 0;
};

which, 类型为 unsigned long，默认值为 0

初始化 UIEvent 的 which 属性。

7.2. 旧版 KeyboardEvent 补充接口

本节为非规范性内容

浏览器对键盘的支持传统上依赖于三个临时属性：keyCode、charCode 以及 UIEvent 的 which。

这三个属性都返回一个数字代码，代表所按按键的某个方面：keyCode 是按键本身的索引；charCode 是字符键的 ASCII 值；which 在可用时为字符值，否则为按键索引。这些属性的值以及属性的可用性在不同平台、键盘语言和布局、用户代理、版本甚至事件类型之间均不一致。

7.2.1. 接口 KeyboardEvent（补充）

部分 KeyboardEvent 接口是 KeyboardEvent 接口的提示性扩展，它添加了 charCode 和 keyCode 属性。

在支持此扩展的实现中，可以通过调用 createEvent() 方法来获取部分 KeyboardEvent 接口。

partial interface KeyboardEvent {
  // The following support legacy user agents
  readonly attribute unsigned long charCode;
  readonly attribute unsigned long keyCode;
};

charCode, 类型为 unsigned long，只读

charCode 包含产生字符输入的 keypress 事件的字符值。该值为该字符的 Unicode 参考编号（码点）（例如，对于可打印字符，event.charCode = event.key.charCodeAt(0)）。对于 keydown 或 keyup 事件，charCode 的值为 0。

keyCode, 类型为 unsigned long，只读

keyCode 包含一个依赖于系统和实现的数值代码，表示与所按按键关联的未修改标识符。与 key 属性不同，本规范并未规范性地定义可能的值集。通常，keyCode 的这些值应代表 ASCII [RFC20][US-ASCII] 或 Windows 1252 [WIN1252] 中的十进制码点，但也可能取自其他合适的字符集。无法识别按键的实现使用键值 0。

有关如何确定 keyCode 值的更多详细信息，请参阅 § 7.3 旧版键模型。

7.2.2. 接口 KeyboardEventInit（补充）

在 KeyboardEvent 中支持 keyCode 和 charCode 的浏览器也应将以下成员添加到 KeyboardEventInit 字典中。

部分 KeyboardEventInit 字典是 KeyboardEventInit 字典的提示性扩展，它添加了 charCode 和 keyCode 成员以初始化相应的 KeyboardEvent 属性。

partial dictionary KeyboardEventInit {
  // The following support legacy user agents
  unsigned long charCode = 0;
  unsigned long keyCode = 0;
};

charCode, 类型为 unsigned long，默认值为 0

将 KeyboardEvent 的 charCode 属性初始化为事件字符的 Unicode 码点。

keyCode, 类型为 unsigned long，默认值为 0

将 KeyboardEvent 的 keyCode 属性初始化为表示与所按按键关联的未修改标识符的系统和实现相关数值代码。

7.3. 旧版键模型

本节为非规范性内容

不同实现对于在不同事件类型中这些属性暴露的值有所不同。实现可以选择在 keyCode 属性中同时暴露虚拟键码和字符码（合并模型），或者报告单独的 keyCode 和 charCode 属性（分离模型）。

7.3.1. 如何确定 keyCode 用于 keydown 和 keyup 事件

keydown 或 keyup 事件的 keyCode 计算如下：

• 如果可用，从操作系统的事件信息中读取虚拟键码。

• 如果输入法编辑器（IME）正在处理按键输入且事件为 keydown，则返回 229。

• 如果输入键在没有修饰符的情况下按下会插入数字字符（0-9），则返回该数字字符的 ASCII 码。

• 如果输入键在没有修饰符的情况下按下会插入 a-z 范围内的字母字符，则返回该字符大写形式的 ASCII 码。

• 如果实现支持操作系统和平台的键码转换表，则查表。如果转换表为给定的输入指定了替代的虚拟键值，则返回该指定值。

• 如果按键功能（以实现特定的方式确定）对应于 § 7.3.3 固定虚拟键码表中的某个键，则返回相应的键码。

• 返回操作系统提供的虚拟键码。

• 如果未找到键码，则返回 0。

7.3.2. 如何确定 keyCode 用于 keypress 事件

keypress 事件的 keyCode 计算如下：

• 如果实现支持合并模型，将 keyCode 设置为所输入字符的 Unicode 码点。

• 如果实现支持分离模型，将 keyCode 设置为 0。

7.3.3. 固定虚拟键码

以下按键的虚拟键码在桌面系统的键盘布局中通常不会改变：

7.3.4. 可选的固定虚拟键码

以下标点符号字符在键盘布局之间可能会改变虚拟码，但报告这些值对于期望美式英语键盘布局的旧版内容来说可能具有更好的兼容性：

8. 旧版事件类型

本节具有规范性。以下事件类型已过时，仅应由需要与旧版软件兼容的用户代理实现。

本节旨在记录这些功能的当前状态及其与规范事件的关系。对于确实支持这些事件的实现，建议使用本节中提供的定义。

下表提供了本规范中已弃用的事件类型的提示性摘要。它们包含在此处仅供参考和完整性。

8.1. 旧版 UIEvent 事件

8.1.1. 旧版 UIEvent 事件类型

8.1.1.1. DOMActivate

当按钮、链接或其他状态更改元素被激活时，用户代理必须分发此事件。

DOMActivate 事件类型在本规范中定义仅供参考和完整性，但本规范弃用该事件类型的使用，转而支持相关的 事件类型 click。其他规范可以定义并维护其自己的 DOMActivate 事件类型以实现向后兼容。

虽然 DOMActivate 和 click 并不完全等效，但 click 事件类型的实现行为已发展为涵盖 DOMActivate 事件类型所设计的关键无障碍访问方面，且得到更广泛的实现。建议内容创作者使用 click 事件类型而非相关的 mousedown 或 mouseup 事件类型，以确保最大的无障碍性。

支持 DOMActivate 事件类型的实现也应将 DOMActivate 事件分发为与激活触发器相关联的 click 事件的默认行为。然而，此类实现对于任何给定的激活触发器，应仅启动相关联的激活行为一次。

不要依赖 DOMActivate 在许多用户代理中的互操作性支持。相反，应使用 click 事件类型，因为它由于更广泛的实现支持而提供更具无障碍性的行为。

DOMActivate 事件类型在本规范中已弃用。

8.1.2. 激活事件顺序

如果 用户代理支持 DOMActivate 事件，则这些事件必须相对于彼此按设定的顺序分发（仅列出相关事件）：

如果焦点元素是通过按键事件激活的，则下表显示了典型的事件序列（仅列出相关事件）：

8.2. 旧版 FocusEvent 事件

8.2.1. 旧版 FocusEvent 事件类型

8.2.1.1. DOMFocusIn

当事件目标接收焦点时，用户代理必须分发此事件。在分发此事件类型之前，必须将焦点赋予该元素。此事件类型必须在事件类型 focus 之后分发。

DOMFocusIn 事件类型在本规范中定义仅供参考和完整性，但本规范弃用该事件类型的使用，转而支持相关的事件类型 focus 和 focusin。

8.2.1.2. DOMFocusOut

当事件目标失去焦点时，用户代理必须分发此事件。在分发此事件类型之前，必须从该元素移除焦点。此事件类型必须在事件类型 blur 之后分发。

DOMFocusOut 事件类型在本规范中定义仅供参考和完整性，但本规范弃用该事件类型的使用，转而支持相关的事件类型 blur 和 focusout。

8.2.2. 旧版 FocusEvent 事件顺序

以下是焦点在元素之间转移时的典型事件序列，包括已弃用的 DOMFocusIn 和 DOMFocusOut 事件。所示顺序假设初始时没有任何元素获得焦点。

8.3. 旧版 KeyboardEvent 事件

keypress 事件是捕获按键事件并将其处理，然后再用按键效果更新 DOM 的传统方法。使用 keypress 事件的代码通常依赖于旧版 charCode、keyCode 和 which 属性。

请注意，keypress 事件特定于按键事件，已被更通用的 beforeinput 和 input 事件序列所取代。这些新的 input 事件不特定于键盘操作，可用于捕获用户输入，无论其原始来源为何。

8.3.1. 旧版 KeyboardEvent 事件类型

8.3.1.1. keypress