如何在 Phaser 3 中正确为 DOM UI 元素添加事件监听器

在 phaser 3 中使用 `this.add.dom()` 加载 html ui 后，若在 `update` 方法中重复调用 `addeventlistener`，会导致每秒叠加数十个监听器，引发性能问题且事件失效；正确做法是仅在 `create` 阶段一次性绑定事件。

Phaser 的 DOM Element（通过 this.add.dom() 创建）本质上是将一个真实 DOM 节点挂载到 Phaser 渲染场景中，但它仍遵循标准浏览器 DOM 行为——即事件监听器需在目标元素就绪后、且仅绑定一次才能稳定响应。

常见错误示例（❌ 危险写法）：

update() {
  // ❌ 错误：每帧（约60fps）都重新绑定，导致监听器爆炸式增长
  document.querySelector("#dirt").addEventListener("click", () => {
    console.log("add dirt");
  });
}

这不仅无法触发预期日志，还会迅速拖慢运行速度，甚至使按钮完全失灵。

✅ 正确做法：在 create() 中获取 DOM 元素并绑定事件，确保只执行一次：

create() {
  // 1. 加载并添加 DOM UI（确保 'ui' 已预加载到 cache）
  const domElement = this.add.dom(0, 0).createFromCache('ui');

  // 2. 等待 DOM 内容渲染完成（关键！）
  // Phaser DOM 元素的 contentDocument 在创建后可能尚未 ready，
  // 推荐通过 domElement.node 访问其根节点，并确保子元素已挂载
  this.time.delayedCall(0, () => {
    const button = domElement.node?.querySelector("#dirt");
    if (button) {
      button.addEventListener("click", () => {
        console.log("add dirt");
        // ✅ 此处可安全调用 Phaser 游戏逻辑，如修改状态、播放音效等
        this.addDirt(); // 示例：自定义方法
      });
    } else {
      console.warn("DOM element #dirt not f
ound in ui.html");
    }
  });
}

⚠️ 注意事项：

• 必须预加载 HTML：确保 ui.html 已通过 this.load.html('ui', 'assets/ui.html') 正确加载并缓存；
• 避免 update 中操作 DOM：除极少数动态更新（如文本内容）外，所有初始化和事件绑定均应在 create 或 init 中完成；
• 检查元素存在性：domElement.node 是挂载的真实 DOM 根节点，务必先校验 querySelector 返回值非 null；
• 内存与解绑：若 UI 会反复销毁重建，建议在销毁前调用 removeEventListener（或使用事件委托 + 一次性监听器）防止内存泄漏。

总结：Phaser DOM UI 不是“黑盒”，而是桥梁——它让 HTML 与 Phaser 共存，但事件生命周期仍由浏览器 DOM 规则主导。坚守“一次创建、一次绑定、避免帧循环干扰”的原则，即可稳定实现交互式 UI。