节点事件系统
input
对象支持了全局的 输入事件系统,全局输入事件包括鼠标、触摸、键盘和重力传感四种。而 Node
也实现了 EventTarget
的事件监听接口。在此基础上,我们提供了一些基础的节点相关的系统事件。
本篇文档着重介绍了与 UI 节点树相关联的鼠标和触摸事件,这些事件是被直接触发在 UI 相关节点上的,所以被称为节点事件,使用方式如下:
node.on(Node.EventType.MOUSE_DOWN, (event) => {
console.log('Mouse down');
}, this);
注意:我们不推荐直接使用事件的名称字符串注册事件监听了。例如上述代码示例,请不要使用
node.on('mouse-down', callback, target)
来注册事件监听。
2D UI 节点上的触摸事件监听依赖于 UITransform
组件。如果需要实现对 3D 物体的触摸检测,请参考文档 3D 物体的触摸检测。
鼠标事件类型和事件对象
鼠标事件在 PC 端才会触发,系统提供的事件类型如下:
枚举对象定义 | 事件触发的时机 |
---|---|
Node.EventType.MOUSE_DOWN | 当鼠标在目标节点区域按下时触发一次。 |
Node.EventType.MOUSE_ENTER | 当鼠标移入目标节点区域时触发,不论是否按下。 |
Node.EventType.MOUSE_MOVE | 当鼠标在目标节点区域中移动时触发,不论是否按下。 |
Node.EventType.MOUSE_LEAVE | 当鼠标移出目标节点区域时触发,不论是否按下。 |
Node.EventType.MOUSE_UP | 当鼠标从按下状态松开时触发一次。 |
Node.EventType.MOUSE_WHEEL | 当鼠标滚轮滚动时触发。 |
鼠标事件(Event.EventMouse
)的重要 API 请参考 鼠标事件 API(Event 标准事件 API 除外)。
触摸事件类型和事件对象
触摸事件在移动端和 PC 端都会触发,开发者若希望更好地在 PC 端进行调试,只需要监听触摸事件即可同时响应移动端的触摸事件和 PC 端的鼠标事件。系统提供的触摸事件类型如下:
枚举对象定义 | 事件触发的时机 |
---|---|
Node.EventType.TOUCH_START | 当手指触点落在目标节点区域内时。 |
Node.EventType.TOUCH_MOVE | 当手指在屏幕上移动时。 |
Node.EventType.TOUCH_END | 当手指在目标节点区域内离开屏幕时。 |
Node.EventType.TOUCH_CANCEL | 当手指在目标节点区域外离开屏幕时。 |
触摸事件(Event.EventTouch
)的重要 API 请参考 触摸事件 API(Event 标准事件 API 除外)。
注意:触摸事件支持多点触摸,每个触点都会发送一次事件给事件监听器。
节点事件派发
Cocos Creator 在 Node
上支持了 dispatchEvent
接口,通过该接口派发的事件,会进入事件派发阶段。Creator 的事件派发系统是按照 Web 的事件冒泡及捕获标准 实现的,事件在派发之后,会经历下面三个阶段:
- 捕获:事件从场景根节点,逐级向子节点传递,直到到达目标节点或者在某个节点的响应函数中中断事件传递
- 目标:事件在目标节点上触发
- 冒泡:事件由目标节点,逐级向父节点冒泡传递,直到到达根节点或者在某个节点的响应函数中中断事件传递
当调用 node.dispatchEvent()
时,意味着 node
就是上文提到的目标节点。在事件的传递过程中,我们可以通过调用 event.propagationStopped = true
来中断事件传递。
在 v3.0 中,我们移除了 Event.EventCustom
类,如果要派发自定义事件,需要先实现一个自定义的事件类,该类继承自 Event
类,例如:
// Event 由 cc 模块导入
import { Event } from 'cc';
class MyEvent extends Event {
constructor(name: string, bubbles?: boolean, detail?: any) {
super(name, bubbles);
this.detail = detail;
}
public detail: any = null; // 自定义的属性
}
以上图为例,这张图展示了事件在 目标 和 冒泡 阶段的传递顺序。当我们从节点 c 派发事件 “foobar”
,倘若节点 a,b 均做了 “foobar”
事件的监听,则事件会经由 c 依次传递给 b、a 节点。代码实现示例如下:
// 节点 c 的组件脚本中
this.node.dispatchEvent( new MyEvent('foobar', true, 'detail info') );
如果我们希望在 b 节点截获事件后就不再传递事件,可以通过调用 event.propagationStopped = true
函数来完成。代码实现示例如下:
// 节点 b 的组件脚本中
this.node.on('foobar', (event: MyEvent) => {
event.propagationStopped = true;
});
注意:在派发用户自定义事件的时候,请不要直接创建
cc
内的Event
对象,因为它是一个抽象类。
如果希望将事件注册在捕获阶段,可以给 on
接口传递第四个参数,例如:
// 节点 a 的组件脚本中
this.node.on('foobar', callback, target, true);
事件对象
在事件监听回调中,开发者会接收到一个 Event 类型的事件对象 event,propagationStopped
就是 Event 的标准 API,其它重要的 API 包含:
API 名 | 类型 | 意义 |
---|---|---|
type | String | 事件的类型(事件名)。 |
target | Node | 接收到事件的原始对象。 |
currentTarget | Node | 接收到事件的当前对象,事件在冒泡阶段当前对象可能与原始对象不同。 |
getType | Function | 获取事件的类型。 |
propagationStopped | Boolean | 是否停止传递当前事件。 |
propagationImmediateStopped | Boolean | 是否立即停止当前事件的传递,事件甚至不会被分派到所连接的当前目标。 |
触摸事件的传递
如上所述,注册在 Node
上的触摸事件,引擎内部就是通过 dispatchEvent
接口派发的。下面我们将介绍触摸事件在 目标 和 冒泡 阶段的传递顺序。
触摸事件冒泡
触摸事件支持节点树的事件冒泡,以下图为例:
在上图的场景中,假设 A 节点拥有一个子节点 B,B 拥有一个子节点 C。开发者对 A、B、C 节点都监听了触摸事件(以下的示例默认节点都监听了触摸事件)。
当鼠标或手指在 C 节点区域内按下时,事件将首先在 C 节点触发,C 节点监听器接收到事件(该阶段为目标阶段);接着 C 节点会将事件向其父节点 B 传递这个事件,B 节点的监听器将会接收到事件;同理 B 节点会将事件传递给父节点 A 。这就是最基本的事件冒泡过程。
注意:虽然触点可能不在 A、B 节点区域内,但 A、B 节点也能触发触摸事件,这是通过子节点 C 的触摸事件冒泡机制传递过来的。在触摸事件冒泡的过程中不会有触摸检测。
触摸事件的冒泡过程与普通事件的冒泡过程并没有区别。所以,调用 event.propagationStopped = true
便可主动停止触摸事件的冒泡过程。
同级节点间的触点归属问题
同级节点间,触点归属于处于顶层的节点。假设上图中 B、C 为同级节点,C 节点部分覆盖在 B 节点之上。这时候如果 C 节点接收到触摸事件,那么表示触点归属于 C 节点,这意味着同级节点 B 就不会再接收到触摸事件了,即使触点同时也在 B 节点内。
此时如果 C 节点还存在父节点,那么通过事件冒泡机制 C 节点还可以将触摸事件传递给父节点。
在 v3.4.0 中,我们支持了 事件穿透派发 功能。在上述同级节点的例子中,如果需要把事件穿透也派发给 B 节点,则可以通过调用 event.preventSwallow = true
来阻止事件被 C 节点吞噬。
注意:事件的穿透派发会降低事件派发的效率,请谨慎使用。
不同 Canvas 的触点归属问题
不同 Canvas 之间的触点拦截是根据节点优先级(可在 Canvas 节点默认自带的 Camera 节点的 priority
属性中设置)决定的。在下图的场景中,左侧节点树里的节点 Canvas 1-5 对应着右侧场景中的图片 priority 1-5。可以看出,即使节点 Canvas 3、4、5 在节点树里并没有按照顺序排列,但根据 Canvas 上的优先级(priority
)关系,触点的响应先后顺序仍然是 Canvas 5 -> Canvas 4 -> Canvas 3 -> Canvas 2 -> Canvas 1。只有在优先级相同的情况下,Canvas 之间的排序才是按照节点树的先后顺序进行。
将触摸或鼠标事件注册在捕获阶段
有时候我们需要父节点的触摸或鼠标事件先于它的任何子节点派发,比如 ScrollView 组件就是这样设计的。这时候事件冒泡已经不能满足我们的需求了,需要将父节点的事件注册在捕获阶段。
要实现这个需求,可以在给 node 注册触摸或鼠标事件时,传入第四个参数 true
,表示 useCapture
。代码示例如下:
this.node.on(Node.EventType.TOUCH_START, this.onTouchStartCallback, this, true);
当节点触发 Node.EventType.TOUCH_START
事件时,会先将 Node.EventType.TOUCH_START
事件派发给所有注册在捕获阶段的父节点监听器,然后派发给节点自身的监听器,最后才到了事件冒泡阶段。
事件拦截
正常的事件会按照上文说明的方式去派发。但是如果节点身上带有 Button
、Toggle
或者 BlockInputEvents
这几个组件的话,会停止事件冒泡。
例如下图,图中有两个按钮,分别是 Canvas 0 下的 priority 1 和 Canvas 1 下的 priority 2。如果点击两个按钮的交汇处,也就是图中的蓝色区域,会出现按钮 priority 2 成功接收到了触点事件,而按钮 priority 1 则没有。
这是因为按上文的事件接收规则,按钮 priority 2 优先接收到了触摸事件,并且对事件进行了拦截(event.propagationStopped = true
),以防止事件穿透。如果是非按钮节点,也可以通过添加 BlockInputEvents
组件来对事件进行拦截,防止穿透。
注意:按钮 priority 1 和 priority 2 分别在 Canvas 0 和 Canvas 1 节点下,两个按钮并不是同级节点。
触摸事件举例
以下图举例,总结下触摸事件的传递机制。图中有 A、B、C、D 四个节点,其中 A、B 为同级节点。具体层级关系如下:
- 若触点在 A、B 的重叠区域内,此时 B 接收不到触摸事件,事件的传递顺序是 A -> C -> D
- 若触点在 B 节点内(可见的绿色区域),则事件的传递顺序是 B -> C -> D
- 若触点在 C 节点内,则事件的传递顺序是 C -> D
- 若以第 2 种情况为前提,同时 C D 节点的触摸事件注册在捕获阶段,则事件的传递顺序是 D -> C -> B
Node 的其它事件
所有的 Node
内置事件都可以通过 Node.EventType
获取事件名。
3D 节点事件
枚举对象定义 | 事件触发的时机 |
---|---|
TRANSFORM_CHANGED | 当变换属性修改时,会派发一个枚举值 TransformBit ,根据枚举值定义修改的变换。 |
变换枚举值定义:
枚举值含义 | 对应的变换 |
---|---|
TransformBit.NONE | 属性无改变。 |
TransformBit.POSITION | 节点位置改变。 |
TransformBit.ROTATION | 节点旋转改变。 |
TransformBit.SCALE | 节点缩放改变。 |
TransformBit.RS | 节点旋转及缩放改变。 |
TransformBit.TRS | 节点平移,旋转及缩放都改变。 |
2D 节点事件
枚举对象定义 | 事件触发的时机 |
---|---|
SIZE_CHANGED | 当宽高属性修改时。宽高属性位于 UITransform 组件上。 |
ANCHOR_CHANGED | 当锚点属性修改时。锚点属性位于 UITransform 组件上。 |
COLOR_CHANGED | 当颜色属性修改时。颜色属性位于 UI 渲染组件上。 |
CHILD_ADDED | 添加子节点时。 |
CHILD_REMOVED | 移除子节点时。 |
PARENT_CHANGED | 父节点改变时。 |
SIBLING_ORDER_CHANGED | 兄弟节点顺序改变时。 |
SCENE_CHANGED_FOR_PERSISTS | 改变常驻节点所在场景时。 |
NODE_DESTROYED | 节点销毁时。 |
LAYER_CHANGED | layer 属性改变时。 |
ACTIVE_IN_HIERARCHY_CHANGED | activeInHierarchy 属性改变时。 |
多点触摸事件
引擎有多点触摸事件的屏蔽开关,多点触摸事件默认为开启状态。对于不需要多点触摸的项目,可以通过以下代码关闭多点触摸:
macro.ENABLE_MULTI_TOUCH = false;
或者也可以通过 Creator 顶部菜单栏的 项目 -> 项目设置 -> Macro Config 进行配置,去掉ENABLE_MULTI_TOUCH 属性的勾选。
暂停或恢复节点系统事件
暂停节点系统事件,代码示例如下:
// 暂停当前节点上注册的所有节点系统事件,节点系统事件包含触摸和鼠标事件。
// 如果传递参数 true,那么这个 API 将暂停本节点和它的所有子节点上的节点系统事件。
// example
this.node.pauseSystemEvents();
恢复节点系统事件,代码示例如下:
// 恢复当前节点上注册的所有节点系统事件,节点系统事件包含触摸和鼠标事件。
// 如果传递参数 true,那么这个 API 将恢复本节点和它的所有子节点上的节点系统事件。
// example
this.node.resumeSystemEvents();