游戏引擎 / 系统课时

设计一次完整的自定义事件

设计一次完整的自定义事件

一个触摸输入需要通知分数显示,但发布组件直接操作显示节点会让两者紧密耦合。本节建立一次已计分通知,把共享事件入口、输入发布者与显示订阅者分开,并验证订阅启停、载荷类型和显示变化形成完整消息链。

学习目标

  • 为自定义事件统一名称、载荷与发布入口。
  • 分离发布者、订阅者和共享通信对象。
  • 正确解除监听,明确事件丢失与状态读取的区别。

用通知表达已经发生的事

发布者先完成累计分数,再发 scored 通知,载荷包含增量与当前总数。订阅者显示 total,不再次加分。这样同一消息有多个订阅者时,不会因每个订阅者都修改状态而重复计分。载荷还应尽量小,避免把整个组件实例传给监听者。

共享模块隐藏底层 EventTarget,仅开放一个受类型约束的事件入口。调用方不任意拼写事件名,也不能发布缺少字段的载荷。外部输入仍需要先校验,类型入口只保护经过 TypeScript 检查的内部调用。

触摸到显示的消息流

定义共享通信入口

以下三文件是 片段示例,依赖 Creator 3.8 项目,放在同一 scripts 目录。文件:scoreEvents.ts。

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。

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。

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 事件文档。一条完整事件链必须同时说明何时发、传什么、谁接收,以及何时停止接收。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计一次完整的自定义事件

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

登录哪都通