游戏引擎 / 系统课时

给事件参数补上精确类型

给事件参数补上精确类型

计分通知若只传一个任意对象,发布者改成 points、监听者仍读 amount 时就会静默出错。本节给事件名称和载荷建立配对关系,用一个小型通知器演示发布与订阅,并明确接到 Cocos 事件系统时仍需遵守的边界。

学习目标

  • 为事件设计稳定名称和单一载荷对象。
  • 让发布与监听共享准确的参数类型。
  • 保留解除订阅入口,区分类型协议与运行时事件机制。

先规定消息表示什么

这里的 scored 表示分数已经变化,载荷包含增加量与来源。监听者不应再负责决定是否计分,避免一条通知被多个对象消费后重复修改状态。消息用一个对象传递,新增字段时可清楚看到协议变更,而不必猜测多个位置参数的含义。

事件类型只保证经过这套 TypeScript 入口的代码遵守协议。来自第三方回调或 JavaScript 的值仍可能不符合类型,进入发布入口前需要检查。还要决定监听顺序、解绑和重入策略,这些是事件机制的职责,不能靠接口定义自动获得。

给名称和载荷建立配对

文件:main.ts,完整纯 TypeScript 主例程。为聚焦协议,只实现 scored 一种消息,后续需求出现时再扩展。

ts
export {};
interface Scored { amount: number; source: string; }
type ScoredHandler = (payload: Scored) => void;
class ScoreEvents {
    private listeners = new Set<ScoredHandler>();
    on(name: 'scored', handler: ScoredHandler): () => void {
        this.listeners.add(handler);
        // 返回闭包,解绑使用原来的函数身份。
        return () => { this.listeners.delete(handler); };
    }
    emit(name: 'scored', payload: Scored): void {
        // 快照避免当前分发期间增删集合改变遍历范围。
        for (const handler of [...this.listeners]) handler(payload);
    }
}
const events = new ScoreEvents();
const unsubscribe = events.on('scored', ({ amount, source }) => {
    console.log(`${source}:+${amount}`);
});
events.emit('scored', { amount: 10, source: 'coin' });
unsubscribe();
events.emit('scored', { amount: 20, source: 'quest' });

预期输出:

text
coin:+10

第二次发布没有输出,说明解绑函数对应了原订阅。若把 payload.amount 改为 points,调用处和监听处都会受到类型检查。name 限定为字面量,拼错名称同样会被拒绝;不能只精确载荷却仍允许任意事件名。

接到 Cocos 时保留类型入口

Creator 的 EventTarget、Node.on 与 emit 是运行时事件 API,不能假设任意名称已经与自定义载荷建立了类型对应。可在共享模块中封装某个业务事件的发布函数与订阅函数,由它们统一引用 Scored;组件只调用这层入口,并保存解绑所需的回调引用。

订阅回调写了 Scored 参数,也不表示底层发布方一定传对了数据。只有所有发布路径都走受约束入口时,这个协议才闭合;若服务需要接收外部数据,应在边界转换成可信载荷。不要把事件总线当作绕过校验的通道。

把消息与命令分开

请求加分属于命令,已加分属于通知,两者最好用不同名称和职责。通知监听者可以更新显示或记录日志,但不应再次调用加分流程,否则可能产生递归发布。日志应包含来源与增量,便于在重复消息出现时定位发布者。

本例 Set 会合并同一个回调引用,两个不同闭包仍是两个订阅,这不能替代组件生命周期管理。练习保留同一个回调并订阅两次,再换成两个闭包观察区别。函数参数规则见 TypeScript 函数说明,引擎解绑关系见 Cocos 3.8 事件 API。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给事件参数补上精确类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通