egret.IEventDispatcher
包 egret
接口 public interface IEventDispatcher
继承 egret.IEventDispatcher → egret.HashObject
子类 egret.SoundChannel,eui.ICollection
IEventDispatcher 接口定义用于添加或删除事件侦听器的方法，检查是否已注册特定类型的事件侦听器，并调度事件。事件目标是 Egret 事件模型的重要组成部分。事件目标是事件如何通过显示列表层次结构这一问题的焦点。当发生触摸轻拍事件时，会将事件对象调度到从显示列表根开始的事件流中。事件对象进行到事件目标的往返行程，在概念上，此往返行程被划分为三个阶段：
捕获阶段包括从根到事件目标节点之前的最后一个节点的行程，目标阶段仅包括事件目标节点，冒泡阶段包括到显示列表的根的回程上遇到的任何后续节点。通常，使用户定义的类能够调度事件的最简单方法是扩展 EventDispatcher。如果无法扩展（即，如果该类已经扩展了另一个类），则可以实现 IEventDispatcher 接口，创建 EventDispatcher 成员，并编写一些简单的挂钩，将调用连接到聚合的 EventDispatcher 中。
公共属性
| 属性 |
|---|
公共方法
| 方法 |
|---|
| addEventListener(type:string,listener:Function,thisObject:any,useCapture:boolean,priority:number):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知 |
| dispatchEvent(event:egret.Event):boolean 将事件分派到事件流中 |
| hasEventListener(type:string):boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器 |
| once(type:string,listener:Function,thisObject:any,useCapture:boolean,priority:number):void 添加仅回调一次的事件侦听器，此方法与on()方法不同，on()方法会持续产生回调，而此方法在第一次回调时就会自动移除监听 |
| removeEventListener(type:string,listener:Function,thisObject:any,useCapture:boolean):void 从 EventDispatcher 对象中删除侦听器 |
| willTrigger(type:string):boolean 检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器 |
属性详细信息
方法详细信息
addEventListener()
public addEventListener(type:string,listener:Function,thisObject:any,useCapture:boolean,priority:number):void
使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。可以为特定类型的事件、阶段和优先级在显示列表的所有节点上注册事件侦听器。成功注册一个事件侦听器后，无法通过额外调用 on() 来更改其优先级。要更改侦听器的优先级，必须先调用 removeEventListener()。然后，可以使用新的优先级再次注册该侦听器。注册该侦听器后，如果继续调用具有不同 type 或 useCapture值的 on()，则会创建单独的侦听器注册。
如果不再需要某个事件侦听器，可调用 EventDispatcher.removeEventListener()删除它；否则会产生内存问题。由于垃圾回收器不会删除仍包含引用的对象，因此不会从内存中自动删除使用已注册事件侦听器的对象。复制EventDispatcher 实例时并不复制其中附加的事件侦听器。（如果新近创建的节点需要一个事件侦听器，必须在创建该节点后附加该侦听器。）但是，如果移动 EventDispatcher 实例，则其中附加的事件侦听器也会随之移动。如果在正在处理事件的节点上注册事件侦听器，则不会在当前阶段触发事件侦听器，但会在事件流的稍后阶段触发，如冒泡阶段。如果从正在处理事件的节点中删除事件侦听器，则该事件侦听器仍由当前操作触发。删除事件侦听器后，决不会再次调用该事件侦听器（除非再次注册以备将来处理）。
- 支持版本:Egret 2.4
- 运行平台:Web,Native
- 参数
- type:string - 事件的类型。
- listener:Function - 处理事件的侦听器函数。此函数必须接受 Event 对象作为其唯一的参数，并且不能返回任何结果，如下面的示例所示： function(evt:Event):void 函数可以有任何名称。
- thisObject:any - 侦听函数绑定的this对象
- useCapture:boolean - 确定侦听器是运行于捕获阶段还是运行于冒泡阶段。如果将 useCapture 设置为 true，则侦听器只在捕获阶段处理事件，而不在冒泡阶段处理事件。如果 useCapture 为 false，则侦听器只在冒泡阶段处理事件。要在两个阶段都侦听事件，请调用 on() 两次：一次将 useCapture 设置为 true，一次将 useCapture 设置为 false。
- priority:number - 事件侦听器的优先级。优先级由一个带符号的整数指定。数字越大，优先级越高。优先级为 n 的所有侦听器会在优先级为 n -1 的侦听器之前得到处理。如果两个或更多个侦听器共享相同的优先级，则按照它们的添加顺序进行处理。默认优先级为 0。
dispatchEvent()
public dispatchEvent(event:egret.Event):boolean
将事件分派到事件流中。事件目标是对其调用 dispatchEvent() 方法的 EventDispatcher 对象。
支持版本:Egret 2.4
运行平台:Web,Native
参数
- event:egret.Event - 调度到事件流中的 Event 对象。
返回:如果成功调度了事件，则值为 true。值 false 表示失败或对事件调用了 preventDefault()。
hasEventListener()
public hasEventListener(type:string):boolean
检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。这样，您就可以确定 EventDispatcher 对象在事件流层次结构中的哪个位置改变了对事件类型的处理。要确定特定事件类型是否确实会触发事件侦听器，请使用 IEventDispatcher.willTrigger()。hasEventListener()与 willTrigger() 的区别是：hasEventListener() 只检查它所属的对象，而 willTrigger() 检查整个事件流以查找由 type 参数指定的事件。
支持版本:Egret 2.4
运行平台:Web,Native
参数
- type:string - 事件的类型。
返回:如果指定类型的侦听器已注册，则值为 true；否则，值为 false。
once()
public once(type:string,listener:Function,thisObject:any,useCapture:boolean,priority:number):void
添加仅回调一次的事件侦听器，此方法与on()方法不同，on()方法会持续产生回调，而此方法在第一次回调时就会自动移除监听。
- 支持版本:Egret 2.4
- 运行平台:Web,Native
- 参数
- type:string - 事件的类型。
- listener:Function - 处理事件的侦听器函数。此函数必须接受 Event 对象作为其唯一的参数，并且不能返回任何结果，如下面的示例所示： function(evt:Event):void 函数可以有任何名称。
- thisObject:any - 侦听函数绑定的this对象
- useCapture:boolean - 确定侦听器是运行于捕获阶段还是运行于冒泡阶段。如果将 useCapture 设置为 true，则侦听器只在捕获阶段处理事件，而不在冒泡阶段处理事件。如果 useCapture 为 false，则侦听器只在冒泡阶段处理事件。要在两个阶段都侦听事件，请调用 once() 两次：一次将 useCapture 设置为 true，一次将 useCapture 设置为 false。
- priority:number - 事件侦听器的优先级。优先级由一个带符号整数指定。数字越大，优先级越高。优先级为 n 的所有侦听器会在优先级为 n -1 的侦听器之前得到处理。如果两个或更多个侦听器共享相同的优先级，则按照它们的添加顺序进行处理。默认优先级为 0。
removeEventListener()
public removeEventListener(type:string,listener:Function,thisObject:any,useCapture:boolean):void
从 EventDispatcher 对象中删除侦听器。如果没有向 EventDispatcher 对象注册任何匹配的侦听器，则对此方法的调用没有任何效果。
- 支持版本:Egret 2.4
- 运行平台:Web,Native
- 参数
willTrigger()
public willTrigger(type:string):boolean
检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。将指定类型的事件调度给此EventDispatcher 对象或其任一后代时，如果在事件流的任何阶段触发了事件侦听器，则此方法返回 true。hasEventListener() 与 willTrigger() 方法的区别是：hasEventListener() 只检查它所属的对象，而 willTrigger() 方法检查整个事件流以查找由 type 参数指定的事件。
支持版本:Egret 2.4
运行平台:Web,Native
参数
- type:string - 事件类型
返回:是否注册过监听器，如果注册过返回true，反之返回false
示例
/*
* 以下示例类来说明如何实现和使用 IEventDispatcher 类。
* 本示例通过以与 EventDispatcher 相同的方式实现 MyEventDispatcher 的每个方法来完成此任务。
*/
class IEventDispatcherExample extends egret.DisplayObjectContainer {
public constructor() {
super();
const key: string = "doSomething";
const decorDispatcher: MyEventDispatcher = new MyEventDispatcher();
decorDispatcher.addEventListener(key, this.onEvent, this);
decorDispatcher.dispatchEvent(new egret.Event(key));
}
public onEvent(event: egret.Event): void {
egret.log("doSomething");
}
}
class MyEventDispatcher extends egret.HashObject implements egret.IEventDispatcher {
private dispatcher: egret.EventDispatcher;
public constructor() {
super();
this.dispatcher = new egret.EventDispatcher(this);
}
public once(type: string, listener: Function, thisObject: any, useCapture?: boolean, priority?: number): void {
this.dispatcher.once(type, listener, thisObject, useCapture, priority);
}
public addEventListener(type: string, listener: Function, thisObject: any, useCapture: boolean = false, priority: number = 0): void {
this.dispatcher.addEventListener(type, listener, thisObject, useCapture, priority);
}
public dispatchEvent(evt: egret.Event): boolean {
return this.dispatcher.dispatchEvent(evt);
}
public hasEventListener(type: string): boolean {
return this.dispatcher.hasEventListener(type);
}
public removeEventListener(type: string, listener: Function, useCapture: boolean = false): void {
this.dispatcher.removeEventListener(type, listener, useCapture);
}
public willTrigger(type: string): boolean {
return this.dispatcher.willTrigger(type);
}
}
