2000年11月13日

1. 文档对象模型事件

编辑
Tom Pixley, Netscape Communications Corp.

目录

1.1. DOM Level 2 事件模型概述

DOM Level 2 事件模型的设计有两个主要目标。第一个目标是设计一个通用的事件系统,允许注册事件处理程序,描述事件在树结构中的流动,并为每个事件提供基本的上下文信息。此外,规范还将提供用于用户界面控制和文档变更通知的标准事件模块,包括为每个这些事件模块定义的上下文信息。

事件模型的第二个目标是提供当前在 DOM Level 0 浏览器中使用的事件系统的通用子集。这旨在促进现有脚本和内容的互操作性。并不期望完全向后兼容。然而,规范在可能的情况下会尝试实现这一点。

以下章节定义了 DOM 事件模型的规范以及为在模型中使用而设计的一系列符合规范的事件模块。事件模型包括关于事件传播和事件监听器注册以及 Event 接口的两个部分。

DOM 应用程序可以使用 hasFeature(feature, version) 方法(参数值分别为 "Events" 和 "2.0")来判断实现是否支持事件模块。为了完整支持此模块,实现还必须支持 DOM Level 2 Core 规范中定义的 "Core" 特性 [DOM Level 2 Core]。有关 DOM Level 2 Core 规范中 符合性 的更多信息,请参阅相应章节 [DOM Level 2 Core]。

每个事件模块在事件模块列表中描述其自身的特性字符串。

1.1.1. 术语

UI 事件
用户界面事件。这类事件由用户通过外部设备(鼠标、键盘等)交互产生。
UI 逻辑事件
与设备无关的用户界面事件,例如焦点变化消息或元素触发通知。
变异事件
由于任何会改变文档结构的操作而产生的事件。
捕获
事件在其目标之前,先由目标的某个祖先处理的过程。
冒泡
事件在其目标处理之后,向上通过其祖先传播的过程。
可取消
一种事件标记,指示在处理该事件时,客户端可以选择阻止 DOM 实现执行与该事件关联的默认行为。

1.2. 事件流描述

事件流是事件从 DOM 实现产生并传递到文档对象模型的过程。事件捕获和事件冒泡以及各种事件监听器注册技术,使得事件可以以多种方式进行处理。它可以在 EventTarget 层面本地处理,或在文档树中更高的 EventTarget 处统一处理。

1.2.1. 基本事件流

每个事件都有一个由 DOM 实现指向的 EventTarget,即事件的目标。该 EventTargetEventtarget 属性中指定。当事件到达目标时,注册在该 EventTarget 上的任何事件监听器都会被触发。虽然所有注册在该 EventTarget 上的 EventListeners 必定会在该 EventTarget 接收到事件时被触发,但规范未规定它们相对于该 EventTarget 上其他 EventListeners 的触发顺序。如果该特定事件既未使用事件捕获也未使用事件冒泡,事件流过程将在所有监听器被触发后结束。若使用了事件捕获或事件冒泡,则事件流将按照下文所述进行相应的修改。

EventListener 内抛出的任何异常都不会阻止事件传播。事件会继续按照描述的方式处理后续的 EventListener

预计 EventListener 所执行的操作可能会导致额外事件触发。这些额外事件应以同步方式处理,并可能导致对事件模型的重新进入。

1.2.2. 事件捕获

事件捕获是指在事件的目标祖先上注册的 EventListener 能在事件被目标接收之前拦截该类型的事件的过程。捕获从树的顶部(通常是 Document)向下进行,是事件冒泡(下文描述)的对称过程。在首次分派事件之前,确定从树的顶部到事件目标的 EventTarget 链。若在事件处理期间树结构被修改,事件流仍基于最初的树状态进行。

EventTarget 上注册的 EventListener 可以通过将 addEventListener 方法的 useCapture 参数设为 true 来选择捕获事件。此后,当指定类型的事件被分派到捕获对象的后代时,位于文档顶部与事件目标之间直线上的相应捕获事件监听器将被触发。此向下传播持续至事件目标被到达。捕获的 EventListener 不会在事件直接分派到其注册的 EventTarget 时被触发。

如果捕获的 EventListener 希望阻止事件的进一步处理,可以调用 Event 接口的 stopProgagation 方法(原文如此)。这将阻止事件的进一步分派,虽然在相同层级注册的其他 EventListener 仍会收到事件。调用一次 stopPropagation 方法后,再次调用不会产生额外效果。如果不存在进一步的捕获者且未调用 stopPropagation,事件将在目标本身触发相应的 EventListeners

虽然事件捕获类似于基于委托的事件模型(所有感兴趣的方直接在目标上注册监听器),但在两个重要方面有所不同。首先,事件捕获仅允许拦截针对捕获EventTarget后代的事件;它不拦截针对捕获者的祖先兄弟节点或兄弟节点的后代的事件。其次,事件捕获不是针对单个 EventTarget 而是针对特定类型的事件。一旦指定,捕获会拦截所有针对捕获者任意后代的该类型事件。

1.2.3. 事件冒泡

标记为冒泡的事件最初的事件流与非冒泡事件相同。事件首先被分派到其目标 EventTarget,并触发该处的任何事件监听器。随后,冒泡事件会沿着 EventTarget 的父链向上遍历,检查每个连续的 EventTarget 上是否注册了事件监听器,并触发它们。此向上传播会持续到包括 Document 在内的最高层级。注册为捕获者的 EventListener 在此阶段不会被触发。事件目标到树顶端的 EventTarget 链在首次分派事件前已确定。若在事件处理期间树结构被修改,事件流仍依据初始状态进行。

任何事件处理程序都可以通过调用 Event 接口的 stopPropagation 方法来阻止事件的进一步传播。如果有 EventListener 调用此方法,则当前 EventTarget 上的所有其余监听器仍会被触发,但冒泡将在该层级停止。只需一次调用 stopPropagation 即可阻止进一步的冒泡。

1.2.4. 事件取消

某些事件被声明为可取消的。对于这些事件,DOM 实现通常会有一个默认行为。例如,网页中的超链接。当用户点击超链接时,默认行为是激活该链接。在处理此类事件之前,实现必须先检查是否有监听器注册以接收该事件并将其分派给这些监听器。随后,监听器可以选择取消实现的默认行为,或允许默认行为继续执行。以浏览器中的超链接为例,取消该行为将导致链接不被激活。

通过调用 EventpreventDefault 方法可以实现取消。如果一个或多个 EventListener 在事件流的任何阶段调用了 preventDefault,则默认操作将被取消。

不同的实现会为各个事件指定各自的默认行为(如果有的话)。DOM 并不试图在规范中定义这些行为。

1.3. 事件监听器注册

1.3.1. 事件注册接口

接口 EventTarget(自 DOM Level 2 起引入)

在支持 DOM 事件模型的实现中,所有 Node 都实现了 EventTarget 接口。因此,可以通过绑定特定的强制类型转换方法在 Node 实例上获取此接口。该接口允许在 EventTarget 上注册和移除 EventListeners,以及向该 EventTarget 分派事件。


IDL 定义
// Introduced in DOM Level 2:
interface EventTarget {
  void               addEventListener(in DOMString type, 
                                      in EventListener listener, 
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type, 
                                         in EventListener listener, 
                                         in boolean useCapture);
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
};

方法
addEventListener
此方法允许在事件目标上注册事件监听器。如果在 EventListener 被添加到正在处理事件的 EventTarget 时加入,它不会被当前的动作触发,但可能在事件流的后续阶段(如冒泡阶段)被触发。
如果在同一 EventTarget 上使用相同参数注册了多个相同的 EventListener,重复的实例会被丢弃。它们不会导致 EventListener 被调用两次,因被丢弃,无需使用 removeEventListener 方法将其移除。
参数
type,类型为 DOMString
用户要注册的事件类型。
listener,类型为 EventListener
listener 参数接受用户实现的接口,该接口包含事件发生时要调用的方法。
useCapture,类型为 boolean
如果为 true,useCapture 表示用户希望启动捕获。启动捕获后,指定类型的所有事件将在分派到树中其下层的任何 EventTarget 之前,首先分派给已注册的 EventListener。向上冒泡的事件不会触发标记为使用捕获的 EventListener
无返回值
无异常
dispatchEvent
此方法允许将事件分派到实现的事件模型中。以此方式分派的事件将具有与实现直接分派的事件相同的捕获和冒泡行为。事件的目标是调用 dispatchEventEventTarget
参数
evt,类型为 Event
指定事件的类型、行为以及处理该事件所需的上下文信息。
返回值

boolean

dispatchEvent 的返回值指示是否有任何处理该事件的监听器调用了 preventDefault。如果调用了 preventDefault,返回值为 false;否则返回 true。

异常

EventException

UNSPECIFIED_EVENT_TYPE_ERR:如果在调用 dispatchEvent 之前未通过初始化事件指定 Event 的 type,则抛出此错误。将事件的 type 指定为 null 或空字符串也会触发此异常。

removeEventListener
此方法允许从事件目标移除事件监听器。如果在 EventListener 正在处理事件时将其从 EventTarget 上移除,则它不会在当前操作中被触发。EventListener 在被移除后永不再被调用。
使用未标识当前已注册的任何 EventListener 的参数调用 removeEventListener 不会产生任何影响。
参数
type,类型为 DOMString
指定要移除的 EventListener 的事件类型。
listener,类型为 EventListener
参数 EventListener 表示要被移除的 EventListener
useCapture,类型为 boolean
指示被移除的 EventListener 是否是以捕获方式注册的。如果同一监听器分别以捕获和非捕获方式注册,则必须分别移除。移除捕获监听器不会影响同一监听器的非捕获版本,反之亦然。
无返回值
无异常
接口 EventListener(自 DOM Level 2 起引入)

EventListener 接口是处理事件的主要方式。用户实现 EventListener 接口并通过 AddEventListener 方法将其注册到 EventTarget。在不再需要该监听器时,用户应将其从对应的 EventTarget 中移除。

当使用 cloneNode 方法复制 Node 时,源 Node 上附加的 EventListener 不会复制到新 Node 上。如果用户希望在新创建的副本上拥有相同的 EventListener,必须手动添加。


IDL 定义
// Introduced in DOM Level 2:
interface EventListener {
  void               handleEvent(in Event evt);
};

方法
handleEvent
每当发生所注册类型的事件时,都会调用此方法。
参数
evt,类型为 Event
Event 包含事件的上下文信息。它还包含 stopPropagationpreventDefault 方法,用于决定事件的流向和默认操作。
无返回值
无异常

1.3.2. 与 HTML 4.0 事件监听器的交互

在 HTML 4.0 中,事件监听器作为元素的属性指定。因此,同一类型的第二个事件监听器会替换第一个监听器。DOM 事件模型允许在单个 EventTarget 上注册多个事件监听器。为实现此目的,事件监听器不再存储为属性值。

为了兼容 HTML 4.0,实现者可以将表示事件处理程序的属性设置视为在 EventTarget 上创建并注册一个 EventListeneruseCapture 的默认值为 false。此 EventListener 的行为与可在 EventTarget 上注册的其他 EventListeners 相同。如果代表事件监听器的属性被更改,可视为先前注册的 EventListener 被移除并注册了新的监听器。HTML 4.0 的事件监听器无法访问为每个事件定义的上下文信息。

1.4. 事件接口

接口 Event(自 DOM Level 2 起引入)

Event 接口用于向处理事件的处理函数提供上下文信息。实现 Event 接口的对象通常作为事件处理函数的第一个参数传入。通过从 Event 派生更具体的接口(包含与特定事件类型直接相关的信息),可以向事件处理函数提供更详细的上下文信息。这些派生接口同样由传递给监听器的对象实现。


IDL 定义
// Introduced in DOM Level 2:
interface Event {

  // PhaseType
  const unsigned short      CAPTURING_PHASE                = 1;
  const unsigned short      AT_TARGET                      = 2;
  const unsigned short      BUBBLING_PHASE                 = 3;

  readonly attribute DOMString        type;
  readonly attribute EventTarget      target;
  readonly attribute EventTarget      currentTarget;
  readonly attribute unsigned short   eventPhase;
  readonly attribute boolean          bubbles;
  readonly attribute boolean          cancelable;
  readonly attribute DOMTimeStamp     timeStamp;
  void               stopPropagation();
  void               preventDefault();
  void               initEvent(in DOMString eventTypeArg, 
                               in boolean canBubbleArg, 
                               in boolean cancelableArg);
};

定义组 PhaseType

一个整数,指示当前正在处理的事件流阶段。

定义的常量
目标阶段
事件当前正在目标 EventTarget 处评估。
冒泡阶段
当前事件阶段是冒泡阶段。
捕获阶段
当前事件阶段是捕获阶段。
属性
bubbles,类型为 boolean,只读
用于指示事件是否为冒泡事件。若事件能够冒泡,则值为 true;否则为 false。
cancelable,类型为 boolean,只读
用于指示事件是否可以取消其默认行为。若默认行为可以被取消,则值为 true;否则为 false。
currentTarget,类型为 EventTarget,只读
用于指示当前正在处理其 EventListenersEventTarget。在捕获和冒泡期间尤其有用。
eventPhase,类型为 unsigned short,只读
用于指示当前正在评估的事件流阶段。
target,类型为 EventTarget,只读
用于指示最初分派该事件的 EventTarget
timeStamp,类型为 DOMTimeStamp,只读
用于指定事件创建的时间(相对于纪元的毫秒数)。由于某些系统可能不提供此信息,timeStamp 的值并非对所有事件都可用。若不可用,则返回 0。纪元时间的例子包括系统启动时间或 1970 年 1 月 1 日 0:0:0 UTC。
type,类型为 DOMString,只读
事件的名称(不区分大小写)。名称必须是 XML 名称
方法
initEvent
initEvent 方法用于初始化通过 DocumentEvent 接口创建的 Event 的值。此方法只能在 Event 通过 dispatchEvent 方法分派之前调用,尽管在该阶段如有必要可以调用多次。若多次调用,则最后一次调用的值优先。如果在 Event 的子类中调用,仅会修改 initEvent 方法中指定的属性值,其他属性保持不变。
参数
eventTypeArg,类型为 DOMString
指定事件类型。此类型可以是本规范中当前定义的任何事件类型,也可以是新事件类型。字符串必须是 XML 名称
任何新定义的事件类型均不得以大小写任意组合的 “DOM” 为前缀。该前缀保留供未来的 DOM 事件集使用。强烈建议第三方在添加自定义事件时使用自己的前缀,以避免混淆并降低与其他新事件冲突的概率。
canBubbleArg,类型为 boolean
指示事件是否能够冒泡。
cancelableArg,类型为 boolean
指示事件的默认行为是否可以被取消。
无返回值
无异常
preventDefault
如果事件是可取消的,则使用 preventDefault 方法表示该事件应被取消,即实现本应因该事件而执行的任何默认动作都不会发生。如果在事件流的任何阶段调用了 preventDefault,则该事件被取消,关联的默认行为将不执行。对不可取消的事件调用此方法没有任何效果。调用后该状态将在事件传播的剩余阶段保持有效。此方法可在事件流的任意阶段使用。
无参数
无返回值
无异常
stopPropagation
stopPropagation 方法用于在事件流过程中阻止事件的进一步传播。如果任何 EventListener 调用此方法,事件将在当前 EventTarget 上的所有监听器完成分派后停止传播。此方法可在事件流的任何阶段使用。
无参数
无返回值
无异常
异常 EventException(自 DOM Level 2 起引入)

事件操作可能会抛出 EventException,如其方法描述中所指定。


IDL 定义
// Introduced in DOM Level 2:
exception EventException {
  unsigned short   code;
};
// EventExceptionCode
const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;

定义组 EventExceptionCode

一个指示生成的错误类型的整数。

定义的常量
未指定的事件类型错误
如果在调用方法之前未通过初始化事件指定 Event 的 type,或将 Event 的 type 指定为 null 或空字符串,也会触发此异常。

1.5. DocumentEvent 接口

接口 DocumentEvent(自 DOM Level 2 起引入)

DocumentEvent 接口提供了一种机制,使用户能够创建实现所支持类型的 Event。预计在支持事件模型的实现中,DocumentEvent 接口将与实现 Document 接口的同一对象一起实现。


IDL 定义
// Introduced in DOM Level 2:
interface DocumentEvent {
  Event              createEvent(in DOMString eventType)
                                        raises(DOMException);
};

方法
创建事件
参数
eventType,类型为 DOMString
参数 eventType 指定要创建的 Event 接口的类型。如果实现支持该 Event 接口,则此方法返回一个新建的指定接口类型的 Event。如果要通过 dispatchEvent 方法分派该 Event,则创建后必须调用相应的 init 方法以初始化 Event 的值。例如,用户希望合成某种 UIEvent,可以使用参数 "UIEvents" 调用 createEvent。随后可以在新创建的 UIEvent 上调用 initUIEvent 方法,设置要分派的 UIEvent 的具体类型并设置其上下文信息。
createEvent 方法用于在用户自行创建 Event 不方便或不必要时创建事件。当实现提供的 Event 不足时,用户可以提供自己的 Event 实现,以配合 dispatchEvent 方法使用。
返回值

Event

新创建的 Event

异常

DOMException

NOT_SUPPORTED_ERR:如果实现不支持请求的 Event 接口类型,则抛出此错误。

1.6. 事件模块定义

DOM Level 2 事件模型允许 DOM 实现支持多个事件模块。该模型的设计便于根据需要添加新的事件模块。DOM 不会尝试定义所有可能的事件。为实现互操作性,DOM 将定义包括低层设备相关事件的用户界面事件模块、UI 逻辑事件模块以及文档变更事件模块。第三方定义的任何新事件类型不得以 "DOM" 的任意大小写形式开头,该前缀已保留用于未来的 DOM 事件模块。强烈建议第三方在添加自定义事件时使用自有前缀,以避免混淆并降低与其他新事件冲突的概率。

1.6.1. 用户界面事件类型

用户界面事件模块由 HTML 4.0 中列出的事件以及在 DOM Level 0 浏览器中支持的额外事件组成。

DOM 应用程序可以使用 hasFeature(feature, version) 方法(参数值分别为 "UIEvents" 和 "2.0")来判断实现是否支持用户界面事件模块。为了完整支持此模块,实现还必须支持本规范中定义的 "Events" 特性以及 DOM Level 2 Views 规范中定义的 "Views" 特性 [DOM Level 2 Views]。有关 符合性 的更多信息,请参阅 DOM Level 2 Core 规范 [DOM Level 2 Core]。

注意:要创建 UIEvent 接口的实例,请在 DocumentEvent 接口的 createEvent 方法中使用特性字符串 "UIEvents" 作为输入参数的值。

接口 UIEvent(自 DOM Level 2 起引入)

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


IDL 定义
// Introduced in DOM Level 2:
interface UIEvent : Event {
  readonly attribute views::AbstractView  view;
  readonly attribute long             detail;
  void               initUIEvent(in DOMString typeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg, 
                                 in views::AbstractView viewArg, 
                                 in long detailArg);
};

属性
detail,类型为 long,只读
根据事件类型,指定关于 Event 的一些详细信息。
view,类型为 views::AbstractView,只读
view 属性标识生成事件的 AbstractView
方法
initUIEvent
initUIEvent 方法用于初始化通过 DocumentEvent 接口创建的 UIEvent 的值。此方法只能在 UIEvent 通过 dispatchEvent 方法分派之前调用,尽管在该阶段如有必要可以多次调用。若多次调用,最终调用的值优先。
参数
typeArg,类型为 DOMString
指定事件类型。
canBubbleArg,类型为 boolean
指示事件是否能够冒泡。
cancelableArg,类型为 boolean
指示事件的默认行为是否可以被取消。
viewArg,类型为 views::AbstractView
指定 EventAbstractView
detailArg,类型为 long
指定 Event 的 detail 信息。
无返回值
无异常

可能出现的此类事件的不同类型有:

DOMFocusIn
DOMFocusIn 事件在 EventTarget 获取焦点时发生,例如通过将指针设备移动到元素上或通过 Tab 键导航至该元素。与 HTML 的 focus 事件不同,DOMFocusIn 可应用于任何可获得焦点的 EventTarget,不仅限于 FORM 控件。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
DOMFocusOut
DOMFocusOut 事件在 EventTarget 失去焦点时发生,例如通过将指针设备移出元素或通过 Tab 键导航离开该元素。与 HTML 的 blur 事件不同,DOMFocusOut 可应用于任何可获得焦点的 EventTarget,不仅限于 FORM 控件。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
DOMActivate
当元素被激活时会触发 activate 事件,例如通过鼠标点击或键盘按键。会提供一个数值参数以指示激活的类型:1 表示普通激活(如一次点击或 Enter),2 表示超激活(如双击或 Shift+Enter)。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:detail(数值)

1.6.2. 鼠标事件类型

鼠标事件模块由 HTML 4.0 中列出的事件以及在 DOM Level 0 浏览器中支持的额外事件组成。该事件模块专为鼠标输入设备设计。

DOM 应用程序可以使用 hasFeature(feature, version) 方法(参数值分别为 "MouseEvents" 和 "2.0")来判断实现是否支持鼠标事件模块。为了完整支持此模块,实现还必须支持本规范中定义的 "UIEvents" 特性。有关 符合性 的更多信息,请参阅 DOM Level 2 Core 规范 [DOM Level 2 Core]。

注意:要创建 MouseEvent 接口的实例,请在 DocumentEvent 接口的 createEvent 方法中使用特性字符串 "MouseEvents" 作为输入参数的值。

接口 MouseEvent(自 DOM Level 2 起引入)

MouseEvent 接口提供与鼠标事件相关的特定上下文信息。

UIEvent 继承的 detail 属性表示在一次用户操作期间,鼠标按钮在同一屏幕位置被按下并释放的次数。用户开始该操作时属性值为 1,随后每完成一次完整的按下‑释放序列该值递增 1。如果用户在 mousedown 与 mouseup 之间移动了鼠标,则该值被设为 0,表示没有点击发生。

在嵌套元素的情况下,鼠标事件始终指向最深层的子元素。目标元素的祖先可以通过冒泡机制获取其子孙元素内部发生的鼠标事件的通知。


IDL 定义
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
  readonly attribute long             screenX;
  readonly attribute long             screenY;
  readonly attribute long             clientX;
  readonly attribute long             clientY;
  readonly attribute boolean          ctrlKey;
  readonly attribute boolean          shiftKey;
  readonly attribute boolean          altKey;
  readonly attribute boolean          metaKey;
  readonly attribute unsigned short   button;
  readonly attribute EventTarget      relatedTarget;
  void               initMouseEvent(in DOMString typeArg, 
                                    in boolean canBubbleArg, 
                                    in boolean cancelableArg, 
                                    in views::AbstractView viewArg, 
                                    in long detailArg, 
                                    in long screenXArg, 
                                    in long screenYArg, 
                                    in long clientXArg, 
                                    in long clientYArg, 
                                    in boolean ctrlKeyArg, 
                                    in boolean altKeyArg, 
                                    in boolean shiftKeyArg, 
                                    in boolean metaKeyArg, 
                                    in unsigned short buttonArg, 
                                    in EventTarget relatedTargetArg);
};

属性
altKey,类型为 boolean,只读
用于指示在触发事件期间是否按下了 'alt' 键。在某些平台上,此键可能会映射到替代键名。
button,类型为 unsigned short,只读
在由鼠标按钮按下或释放引发的鼠标事件中,button 用于指示哪个鼠标按钮改变了状态。button 的取值范围为:0 表示左键,1 表示中键(如果有),2 表示右键。对于左手使用且按钮功能被反转的鼠标,取值顺序则从右至左读取。
clientX,类型为 long,只读
事件发生时相对于 DOM 实现的客户端区域的水平坐标。
clientY,类型为 long,只读
事件发生时相对于 DOM 实现的客户端区域的垂直坐标。
ctrlKey,类型为 boolean,只读
用于指示在触发事件期间是否按下了 'ctrl' 键。
metaKey,类型为 boolean,只读
用于指示在触发事件期间是否按下了 'meta' 键。在某些平台上,此键可能会映射到替代键名。
relatedTarget,类型为 EventTarget,只读
用于标识与 UI 事件相关的第二个 EventTarget。当前该属性在 mouseover 事件中用于指示指针设备离开的 EventTarget,在 mouseout 事件中用于指示指针设备进入的 EventTarget
screenX,类型为 long,只读
事件发生的水平坐标,相对于屏幕坐标系统的原点。
screenY,类型为 long,只读
事件发生的垂直坐标,相对于屏幕坐标系统的原点。
shiftKey,类型为 boolean,只读
用于指示在触发事件期间是否按下了 'shift' 键。
方法
initMouseEvent
initMouseEvent 方法用于初始化通过 DocumentEvent 接口创建的 MouseEvent 的值。此方法只能在 MouseEvent 通过 dispatchEvent 方法分派之前调用,尽管在该阶段如有必要可以多次调用。若多次调用,最终调用的值优先。
参数
typeArg,类型为 DOMString
指定事件类型。
canBubbleArg,类型为 boolean
指示事件是否能够冒泡。
cancelableArg,类型为 boolean
指示事件的默认行为是否可以被取消。
viewArg,类型为 views::AbstractView
指定 EventAbstractView
detailArg,类型为 long
指定 Event 的鼠标点击计数。
screenXArg,类型为 long
指定 Event 的屏幕 X 坐标。
screenYArg,类型为 long
指定 Event 的屏幕 Y 坐标。
clientXArg,类型为 long
指定 Event 的客户端 X 坐标。
clientYArg,类型为 long
指定 Event 的客户端 Y 坐标。
ctrlKeyArg,类型为 boolean
指定在 Event 发生期间是否按下了 Ctrl 键。
altKeyArg,类型为 boolean
指定在 Event 发生期间是否按下了 Alt 键。
shiftKeyArg,类型为 boolean
指定在 Event 发生期间是否按下了 Shift 键。
metaKeyArg,类型为 boolean
指定在 Event 发生期间是否按下了 Meta 键。
buttonArg,类型为 unsigned short
指定 Event 所涉及的鼠标按钮。
relatedTargetArg,类型为 EventTarget
指定 Event 的相关 EventTarget
无返回值
无异常

可能出现的鼠标事件类型有:

click
当指点设备的按钮在元素上被点击时会触发 click 事件。click 被定义为在同一屏幕位置上一次 mousedown 与一次 mouseup 的组合。其事件顺序为:
    mousedown
    mouseup
    click
   
如果在同一屏幕位置上发生多次点击,则该序列会重复,并且 detail 属性随每一次重复而递增。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey、button、detail
mousedown
当指点设备的按钮在元素上被按下时会触发 mousedown 事件。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey、button、detail
mouseup
当指点设备的按钮在元素上被释放时会触发 mouseup 事件。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey、button、detail
mouseover
当指点设备移动到元素上时会触发 mouseover 事件。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey、relatedTarget,表示指针设备正离开的 EventTarget
mousemove
当指点设备在元素上移动时会触发 mousemove 事件。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey
mouseout
当指点设备从元素移开时会触发 mouseout 事件。此事件适用于大多数元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:screenX、screenY、clientX、clientY、altKey、ctrlKey、shiftKey、metaKey、relatedTarget,表示指针设备正进入的 EventTarget

1.6.3. 键盘事件

DOM Level 2 事件规范未提供键盘事件模块。用于键盘输入设备的事件模块将在更高版本的 DOM 规范中加入。

1.6.4. 变动事件类型

变更事件模块旨在对文档结构的任何更改(包括属性和文本的修改)进行通知。需要注意的是,列出的变更事件均未标记为可取消的。这源于使用现有 DOM 接口进行文档修改时,如果相关事件被取消,文档是否会实际发生更改难以确定。虽然仍希望具备此功能,但决定将其留待 DOM 引入事务后再实现。

对树的单次修改常常会导致多条 mutation 事件被触发。由于不可能为每一种可能的树结构变动指定明确的事件顺序,事件的触发顺序交由实现自行决定。

DOM 应用程序可以使用 hasFeature(feature, version) 方法(参数值分别为 "MutationEvents" 和 "2.0")来判断实现是否支持变更事件模块。为了完整支持此模块,实现还必须支持本规范中定义的 "Events" 特性。有关 符合性 的更多信息,请参阅 DOM Level 2 Core 规范 [DOM Level 2 Core]。

注意: 要创建 MutationEvent 接口的实例,请使用特性字符串 "MutationEvents" 作为与 createEvent 方法一起使用的输入参数的值,该方法属于 DocumentEvent 接口。

接口 MutationEvent(引入自 DOM Level 2

MutationEvent 接口提供与 Mutation(变动)事件相关的特定上下文信息。


IDL 定义
// Introduced in DOM Level 2:
interface MutationEvent : Event {

  // attrChangeType
  const unsigned short      MODIFICATION                   = 1;
  const unsigned short      ADDITION                       = 2;
  const unsigned short      REMOVAL                        = 3;

  readonly attribute Node             relatedNode;
  readonly attribute DOMString        prevValue;
  readonly attribute DOMString        newValue;
  readonly attribute DOMString        attrName;
  readonly attribute unsigned short   attrChange;
  void               initMutationEvent(in DOMString typeArg, 
                                       in boolean canBubbleArg, 
                                       in boolean cancelableArg, 
                                       in Node relatedNodeArg, 
                                       in DOMString prevValueArg, 
                                       in DOMString newValueArg, 
                                       in DOMString attrNameArg, 
                                       in unsigned short attrChangeArg);
};

定义组 attrChangeType

一个整数,指示 Attr 以何种方式被更改。

定义的常量
添加
Attr 刚被添加。
修改
Attr 在原位被修改。
移除
Attr 刚被移除。
属性
attrChange 类型为 unsigned short,只读
attrChange 表示触发 DOMAttrModified 事件的更改类型。其值可以是 MODIFICATIONADDITIONREMOVAL
attrName 类型为 DOMString,只读
attrName 表示在 DOMAttrModified 事件中被更改的 Attr 节点的名称。
newValue 类型为 DOMString,只读
newValue 表示 DOMAttrModified 事件中 Attr 节点的新值,以及 DOMCharDataModified 事件中 CharacterData 节点的新值。
prevValue 类型为 DOMString,只读
prevValue 表示 DOMAttrModified 事件中 Attr 节点的先前值,以及 DOMCharDataModified 事件中 CharacterData 节点的先前值。
relatedNode 类型为 Node,只读
relatedNode 用于标识与突变事件相关的次要节点。例如,如果突变事件被分派到一个节点,指示其父节点已更改,则 relatedNode 为已更改的父节点。如果事件是分派到一个子树,指示其中的某个节点已更改,则 relatedNode 为已更改的节点。在 DOMAttrModified 事件的情况下,它指示被修改、添加或移除的 Attr 节点。
方法
initMutationEvent
initMutationEvent 方法用于初始化通过 DocumentEvent 接口创建的 MutationEvent 的值。此方法只能在 MutationEvent 通过 dispatchEvent 方法分派之前调用,尽管在该阶段如果需要可以调用多次。如果多次调用,则最后一次调用优先。
参数
typeArg,类型为 DOMString
指定事件类型。
canBubbleArg,类型为 boolean
指示事件是否能够冒泡。
cancelableArg,类型为 boolean
指示事件的默认行为是否可以被取消。
relatedNodeArg 类型为 Node
指定 Event 的相关节点。
prevValueArg 类型为 DOMString
指定 EventprevValue 属性。该值可以为 null。
newValueArg 类型为 DOMString
指定 EventnewValue 属性。该值可以为 null。
attrNameArg 类型为 DOMString
指定 EventattrName 属性。该值可以为 null。
attrChangeArg 类型为 unsigned short
指定 EventattrChange 属性
无返回值
无异常

可能出现的 Mutation(变动)事件类型有:

DOMSubtreeModified
这是一个通用的事件,用于通知文档的所有更改。它可以代替下面列出的更具体的事件。该事件可以在单次文档修改后触发,也可以在实现自行决定的情况下,在多次更改发生后一次性触发。后者通常用于一次性处理同步或快速连续发生的多次更改。该事件的目标是所有已发生更改的最低公共父节点。此事件会在由同一次变动产生的其他任何事件之后派发。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
DOMNodeInserted
当一个节点被添加为另一个节点的 子节点 时触发。此事件在插入完成后分派。该事件的目标是被插入的节点。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:relatedNode 为父节点
DOMNodeRemoved
当一个节点从其父节点中被移除时触发。此事件在节点从树中移除之前分派。该事件的目标是被移除的节点。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:relatedNode 为父节点
DOMNodeRemovedFromDocument
当一个节点被从文档中移除时触发(无论是直接删除该节点,还是删除包含该节点的子树),该事件在实际移除之前派发。事件的目标是被移除的节点。如果节点是直接被删除,则 DOMNodeRemoved 事件会先于 DOMNodeRemovedFromDocument 事件触发。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
DOMNodeInsertedIntoDocument
当一个节点被插入到文档中时触发(无论是直接插入该节点,还是插入包含该节点的子树),该事件在插入完成后派发。事件的目标是被插入的节点。如果节点是直接插入,则 DOMNodeInserted 事件会先于 DOMNodeInsertedIntoDocument 事件触发。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
DOMAttrModified
在节点的 Attr 被修改后触发。该事件的目标是其 Attr 发生变化的 Node。attrChange 的值指示 Attr 是被修改、添加还是移除。relatedNode 的值指示受影响值的 Attr 节点。预期对 Attr 值进行基于字符串的替换将被视为对 Attr 的修改,因为其标识未改变。随后用不同的 Attr 节点替换该 Attr 节点将被视为首次 Attr 节点的移除以及第二个 Attr 节点的添加。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:attrName、attrChange、prevValue、newValue、relatedNode
DOMCharacterDataModified
当节点内部的 CharacterData 被修改但节点本身未被插入或删除时触发。该事件同样会在处理指令(PI)元素的修改时触发。事件的目标是被修改的 CharacterData 节点。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:prevValue、newValue

1.6.5. HTML 事件类型

HTML 事件模块包括 HTML 4.0 中列出的事件以及在 DOM Level 0 浏览器中支持的额外事件。

DOM 应用程序可以使用 DOMImplementation 接口的 hasFeature(feature, version) 方法,将参数值分别设为 “HTMLEvents” 与 “2.0”,以确定实现是否支持 HTML 事件模块。为完整支持此模块,实施还必须支持本规范中定义的 “Events” 特性。请参阅 DOM Level 2 Core 规范中有关 合规性 的更多信息 [DOM Level 2 Core]。

注意:要为 HTML 事件模块创建 Event 接口的实例,请使用特性字符串 "HTMLEvents" 作为与 createEvent 方法一起使用的输入参数的值,该方法属于 DocumentEvent 接口。

HTML 事件使用基础的 DOM Event 接口来传递上下文信息。

可能出现的此类事件的不同类型有:

load
当 DOM 实现完成对文档中所有内容、FRAMESET 中的所有框架或 OBJECT 元素的加载时会触发 load 事件。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
unload
当 DOM 实现从窗口或框架中移除文档时会触发 unload 事件。此事件适用于 BODY 和 FRAMESET 元素。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
abort (中止)
当页面加载在图像尚未完全加载完毕之前被中止时会触发 abort 事件。此事件适用于 OBJECT 元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
error
当图像加载失败或脚本执行期间出现错误时会触发 error 事件。此事件适用于 OBJECT 元素、BODY 元素以及 FRAMESET 元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
select
当用户在文本框中选择了文字时会触发 select 事件。此事件适用于 INPUT 和 TEXTAREA 元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
change
当控件失去输入焦点且自获得焦点以来其值已被修改时会触发 change 事件。此事件适用于 INPUT、SELECT 和 TEXTAREA 元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
submit (提交)
当表单被提交时会触发 submit 事件。此事件仅适用于 FORM 元素。
  • 冒泡:是
  • 可取消:是
  • 上下文信息:无
重置
当表单被重置时会触发 reset 事件。此事件仅适用于 FORM 元素。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
focus
当元素通过指点设备或 Tab 键导航获得焦点时会触发 focus 事件。此事件适用于以下元素:LABEL、INPUT、SELECT、TEXTAREA 和 BUTTON。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
blur
当元素通过指点设备或 Tab 键导航失去焦点时会触发 blur 事件。此事件适用于以下元素:LABEL、INPUT、SELECT、TEXTAREA 和 BUTTON。
  • 冒泡:否
  • 可取消:否
  • 上下文信息:无
resize
当文档视图的尺寸被改变时会触发 resize 事件。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无
scroll
当文档视图被滚动时会触发 scroll 事件。
  • 冒泡:是
  • 可取消:否
  • 上下文信息:无