EventTarget.dispatchEvent()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.
EventTarget
的 dispatchEvent()
方法会向一个指定的事件目标派发一个 Event
,并以合适的顺序(同步地)调用所有受影响的 EventListener
。标准事件处理规则(包括事件捕获和可选的冒泡过程)同样适用于通过手动使用 dispatchEvent()
方法派发的事件。
调用 dispatchEvent()
是触发一个事件的最后一步。被触发的事件应事先通过 Event()
构造函数创建并初始化完毕。
备注:在调用此方法时,Event.target
属性默认为当前的 EventTarget
。
和经由浏览器触发,并通过事件循环异步调用事件处理程序的“原生”事件不同,dispatchEvent()
会同步调用事件处理函数。在 dispatchEvent()
返回之前,所有监听该事件的事件处理程序将在代码继续前执行并返回。
语法
dispatchEvent(event)
参数
event
-
被派发的
Event
。其Event.target
属性为当前的EventTarget
。
返回值
- 当
event
可被取消(cancelable
值为true
),且event
中至少有一个事件处理程序调用了Event.preventDefault()
方法时,返回false
。否则,返回true
。
异常
InvalidStateError
DomException
-
若事件未在初始化时指定类型(
type
属性值),则抛出此异常。
警告:由事件处理程序抛出的异常视为未被捕获的异常。事件处理程序运行在一个嵌套的调用栈中;在其处理完毕前将阻塞 caller
,但异常却不会冒泡至 caller
。
示例
请参考创建和触发事件。
规范
Specification |
---|
DOM Standard # ref-for-dom-eventtarget-dispatchevent③ |
浏览器兼容性
BCD tables only load in the browser