游戏引擎 / 系统课时
设计一次完整的自定义事件
设计一次完整的自定义事件
一个触摸输入需要通知分数显示,但发布组件直接操作显示节点会让两者紧密耦合。本节建立一次已计分通知,把共享事件入口、输入发布者与显示订阅者分开,并验证订阅启停、载荷类型和显示变化形成完整消息链。
学习目标
- 为自定义事件统一名称、载荷与发布入口。
- 分离发布者、订阅者和共享通信对象。
- 正确解除监听,明确事件丢失与状态读取的区别。
用通知表达已经发生的事
发布者先完成累计分数,再发 scored 通知,载荷包含增量与当前总数。订阅者显示 total,不再次加分。这样同一消息有多个订阅者时,不会因每个订阅者都修改状态而重复计分。载荷还应尽量小,避免把整个组件实例传给监听者。
共享模块隐藏底层 EventTarget,仅开放一个受类型约束的事件入口。调用方不任意拼写事件名,也不能发布缺少字段的载荷。外部输入仍需要先校验,类型入口只保护经过 TypeScript 检查的内部调用。

定义共享通信入口
以下三文件是 片段示例,依赖 Creator 3.8 项目,放在同一 scripts 目录。文件:scoreEvents.ts。
import { EventTarget } from 'cc';
export interface Scored { amount: number; total: number; }
const bus = new EventTarget();
// 固定事件名,调用者只需提供正确载荷。
export function emitScored(payload: Scored): void { bus.emit('scored', payload); }
export function listenScored(handler: (payload: Scored) => void): () => void {
bus.on('scored', handler);
// 闭包保留原回调,不生成新的 bind 函数。
return () => bus.off('scored', handler);
}模块仅定义通信行为,不在加载时发布事件。文件:ScorePublisher.ts。
import { _decorator, Component, Node } from 'cc';
import { emitScored } from './scoreEvents';
const { ccclass } = _decorator;
@ccclass('ScorePublisher')
export class ScorePublisher extends Component {
private total = 0;
onEnable(): void { this.node.on(Node.EventType.TOUCH_END, this.score, this); }
onDisable(): void { this.node.off(Node.EventType.TOUCH_END, this.score, this); }
private score(): void {
this.total += 10;
// 通知描述修改后的状态。
emitScored({ amount: 10, total: this.total });
}
}发布组件在真实触摸后才通知,避免依赖组件 start 的相对执行顺序。文件:ScoreView.ts。
import { _decorator, Component, Label } from 'cc';
import { listenScored } from './scoreEvents';
const { ccclass, property } = _decorator;
@ccclass('ScoreView')
export class ScoreView extends Component {
@property(Label)
label: Label | null = null;
private stop: (() => void) | null = null;
onEnable(): void {
// 不允许同一实例重复持有订阅。
this.stop?.();
this.stop = listenScored(({ total }) => {
if (this.label) this.label.string = `score:${total}`;
});
}
onDisable(): void { this.stop?.(); this.stop = null; }
}预期结果:Canvas 下创建可点击 UI 节点并挂 ScorePublisher,确认 UITransform 有合理尺寸;创建 Label 节点,挂 ScoreView,把同节点 Label 拖入 label。保存预览后点击两次,显示依次变为 score:10、score:20。
验证消息有效范围
停用 ScoreView 后点击,发布者仍累计,但显示不会收到通知;重新启用后再点击,显示下次通知中的总数。事件是发生时的通知,通常不会自动回放。若要求重新打开界面马上展示最新分数,应由服务提供当前快照,启用时先读快照再订阅。
发布者与订阅者都应有明确生命周期,模块级通信对象比场景组件更长寿,因此订阅者停用时必须清理。不同场景重复创建显示组件时尤其要验证解绑,否则旧实例仍可能收到新消息。这里不在模块顶层保存场景节点,也不假设监听者永远存在。
同一共享模块路径应保持统一,避免复制两份总线文件导致发布者和订阅者连接不同对象。排查无显示时,可以先在订阅回调记录 total,确认消息到达后再检查 Label 配置。
检查载荷与状态边界
Label 引用没有配置时,回调会安全跳过显示;实际项目可在初始化时报告明确配置错误。emitScored 并不校验外部 JSON,外部数据要先转换成可信 Scored。若某监听者抛错,还要根据业务确定异常隔离策略,不能默认事件机制替你完成全部错误处理。
引擎 on、off 和 emit 的对应关系见 Cocos 3.8 事件文档。一条完整事件链必须同时说明何时发、传什么、谁接收,以及何时停止接收。