Event
=====

**`Event`** 接口表示在 DOM 中出现的事件。

一些事件是由用户触发的，例如鼠标或键盘事件；或者由 API 生成以表示异步任务的进度。事件也可以通过编程方式触发，例如对元素调用 `HTMLElement.click()` 方法，或者定义一些自定义事件，再使用 `EventTarget.dispatchEvent()` 方法将自定义事件派发往指定的目标（target）。

有许多不同类型的事件，其中一些使用基于 `Event` 主接口的其他接口。`Event` 本身包含适用于所有事件的属性和方法。

很多 DOM 元素可以被设计接收 (或者监听) 这些事件，并且执行代码去响应（或者处理）它们。通过 `EventTarget.addEventListener()` 方法可以将事件处理器绑定到不同的 HTML 元素上（比如 `<button>`、`<div>`、`<span>` 等等）。这种方式基本替换了老版本中使用 HTML 事件处理器属性的方式。此外，在正确添加后，还可以使用 `removeEventListener()` 方法移除这些事件处理器。

**备注：** 一个元素可以绑定多个事件处理器，甚至是对于完全相同的事件。尤其是相互独立的代码模块出于不同的目的附加事件处理器。（比如，一个网页同时有着广告模块和统计模块同时监听视频播放。）

当有很多嵌套的元素，每个元素都有着自己的事件处理器，事件处理过程会变得非常复杂。尤其当一个父元素和子元素绑定完全相同的事件时，因为结构上的重叠，事件在技术层面发生在两个元素中，触发的顺序取决于每个处理器的事件冒泡和事件捕获的设置。

基于 Event 的接口
------------

下面是基于 `Event` 主接口的接口列表，每一个接口都设置了指向各自的 MDN API 参考中相应文档的链接。

需要注意的是，所有的事件接口名称都是以“Event”结尾的。

* `AnimationEvent` (en-US)
* `AudioProcessingEvent` (en-US) 
已弃用
* `BeforeUnloadEvent`
* `BlobEvent` (en-US)
* `ClipboardEvent`
* `CloseEvent`
* `CompositionEvent`
* `CustomEvent`
* `DeviceMotionEvent`
* `DeviceOrientationEvent`
* `DragEvent`
* `ErrorEvent`
* `FetchEvent`
* `FocusEvent`
* `FontFaceSetLoadEvent` (en-US)
* `FormDataEvent` (en-US)
* `GamepadEvent`
* `HashChangeEvent`
* `HIDInputReportEvent` (en-US)
* `IDBVersionChangeEvent` (en-US)
* `InputEvent`
* `KeyboardEvent`
* `MediaStreamEvent` 
已弃用
* `MessageEvent`
* `MouseEvent`
* `MutationEvent` (en-US) 
已弃用
* `OfflineAudioCompletionEvent` (en-US)
* `PageTransitionEvent`
* `PaymentRequestUpdateEvent` (en-US)
* `PointerEvent`
* `PopStateEvent` (en-US)
* `ProgressEvent`
* `RTCDataChannelEvent` (en-US)
* `RTCPeerConnectionIceEvent` (en-US)
* `StorageEvent`
* `SubmitEvent` (en-US)
* `SVGEvent` 
已弃用
* `TimeEvent` (en-US)
* `TouchEvent`
* `TrackEvent` (en-US)
* `TransitionEvent`
* `UIEvent`
* `WebGLContextEvent`
* `WheelEvent`
构造函数
----

`Event()`

创建并返回一个 `Event` 对象。

实例属性
----

`Event.bubbles` 只读 

一个布尔值，用来表示该事件是否会在 DOM 中冒泡。

`Event.cancelable` 只读 

一个布尔值，表示事件是否可以取消。

`Event.composed` 只读 

一个布尔值，表示事件是否可以穿过 Shadow DOM 和常规 DOM 之间的边界进行冒泡。

`Event.currentTarget` 只读 

对事件当前注册的目标的引用。这是一个当前计划将事件发送到的对象。它是有可能在*重定向*（retarget）的过程中被改变的。

`Event.defaultPrevented` 只读 

一个布尔值，表示 `event.preventDefault()` 方法是否取消了事件的默认行为。

`Event.eventPhase` 只读 

指示正在处理的事件流阶段。它是以下数字之一：`NONE`、`CAPTURING_PHASE`、`AT_TARGET`、`BUBBLING_PHASE`。

`Event.isTrusted` 只读 

表示事件是由浏览器（例如用户点击）发起的，还是由脚本发起的（例如使用事件创建方法）。

`Event.target` 只读 

对最初分发事件的对象的引用。

`Event.timeStamp` 只读 

事件创建时的时间戳（精度为毫秒）。按照规范，这个时间戳是 Unix 纪元起经过的毫秒数，但实际上，在不同的浏览器中，对此时间戳的定义也有所不同。另外，规范正在将其修改为 `DOMHighResTimeStamp`。

`Event.type` 只读 

事件的类型，不区分大小写。

### 遗留属性和非标准属性

`Event.cancelBubble` 
已弃用

`Event.stopPropagation()` 的历史别名，应该改用。在事件处理程序返回之前将其值设置为 `true` 可以阻止事件传播。

`Event.explicitOriginalTarget` (en-US) 
非标准
 只读 

事件的明确原始目标。

`Event.originalTarget` 
非标准
 只读 

重定向目标前的事件原始目标。

`Event.returnValue` 
已弃用

为了确保现有网站继续工作，而仍然支持的历史属性。请改用 `Event.preventDefault()` 和 `Event.defaultPrevented`。

`Event.scoped` 只读  
已弃用

一个布尔值，指示给定事件是否会穿过影子根节点冒泡到标准 DOM。请改用 `composed`。

实例方法
----

`Event.composedPath()`

返回事件的路径（将在该对象上调用监听器）。如果阴影根（shadow root）节点创建时 `ShadowRoot.mode` 值为 closed，那么路径不会包括该根节点下影子树（shadow tree）的节点。

`event.preventDefault`

取消事件（如果该事件可取消）。

`event.stopImmediatePropagation`

对这个特定的事件而言，没有其他监听器被调用。这个事件既不会添加到相同的元素上，也不会添加到以后将要遍历的元素上（例如在捕获阶段）。

`event.stopPropagation`

停止冒泡，阻止事件在 DOM 中继续冒泡。

### 弃用方法

`Event.initEvent()` 
已弃用

初始化创建的事件的值。如果事件已经被分派，则此方法不执行任何操作。请改用构造函数（`Event()`）。

规范
--

| Specification |
| --- |
| DOM Standard # interface-event |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* 可用的事件类型：Event 参考
* Event 目标的比较（目标 `target` vs 当前目标 `currentTarget` vs 相关目标 `relatedTarget` vs 初始目标 `originalTarget`）
* 创建和触发自定义事件