事件

事件是用于引擎内对象交互的消息传递机制。

事件监听

  1. // 该事件监听每次都会触发,需要手动取消注册
  2. xxx.on(type, func, target);

的方式来监听,其中 type 为事件注册字符串,func 为执行事件监听的回调,target 为事件接收对象。

事件取消

  1. // 取消对象身上所有注册的该类型的事件
  2. xxx.off(type);
  3. // 取消对象身上该类型指定回调指定目标的事件
  4. xxx.off(type, func, target);

事件派发

  1. // 事件派发的时候可以指定派发参数
  2. xxx.emit(type, ...arg);

需要说明的是,出于底层事件派发的性能考虑,这里最多只支持传递 5 个事件参数。所以在传参时需要注意控制参数的传递个数。

事件说明

系统事件

系统事件指的是全局事件,直接从浏览器进行事件监听和派发。

  1. systemEvent.on(type, func, target);

当前支持的系统事件有:触摸事件,鼠标事件,重力事件,按键事件。可以通过 SystemEventType 获取全局事件类型。

事件名事件类型说明
TOUCH_START手指开始触摸事件。
TOUCH_MOVE当手指在屏幕上移动时。
TOUCH_END手指结束触摸事件。
TOUCH_CANCEL当手指在目标节点区域外离开屏幕时。
MOUSE_DOWN当鼠标按下时触发一次。
MOUSE_MOVE当鼠标在目标节点在目标节点区域中移动时,不论是否按下。
MOUSE_UP当鼠标从按下状态松开时触发一次。
MOUSE_WHEEL鼠标滚动事件。
MOUSE_ENTER当鼠标移入目标节点区域时,不论是否按下。
MOUSE_LEAVE当鼠标移出目标节点区域时,不论是否按下。
KEY_DOWN当按下按键时触发的事件。
KEY_UP当松开按键时触发的事件。
DEVICEMOTION重力感应。

KEY 事件获取的键值列表具体可参照 API 的 Macro 来使用。

UI 事件

事件处理是在节点(Node)中完成的。对于组件,可以通过访问节点 this.node 来注册和监听事件。监听事件可以 通过 this.node.on() 函数来注册,方法如下:

  1. import { _decorator, Component, Node } from "Cocos3D";
  2. const { ccclass } = _decorator;
  3. @ccclass("example")
  4. export class example extends Component {
  5. onLoad() {
  6. this.node.on(Node.EventType.TOUCH_CANCEL, this.callback, this);
  7. }
  8. callback(){
  9. }
  10. onDestroy(){
  11. // 一般为了数据回收把控,我们会指定 func,并且在组件 destroy 的时候注销事件
  12. this.node.off(Node.EventType.TOUCH_CANCEL);
  13. }
事件名事件类型说明
TRANSFORM_CHANGED节点改变位置、旋转或缩放事件。
POSITION_PART节点位置改变事件。统一由 TRANSFORM_CHANGED 监听,派发后判断类型。
ROTATION_PART节点旋转事件。统一由 TRANSFORM_CHANGED 监听,派发后判断类型。
SCALE_PART节点缩放事件。统一由 TRANSFORM_CHANGED 监听,派发后判断类型。
SIZE_CHANGED当节点尺寸改变时触发的事件。
ANCHOR_CHANGED当节点锚点改变时触发的事件。
CHILD_ADDED节点子类添加。
CHILD_REMOVED节点子类移除。