游戏引擎 / 系统课时
给互动对象绑定 Pointer 事件
给互动对象绑定 Pointer 事件
用 Phaser 4.2.1 做一个鼠标和触屏通用的「开始游戏」按钮:显式设置可点击范围,响应移入、按下和抬起,并在拖出或离开画布时取消触发。完成后可以直接用浏览器和手机检验按钮是否误触或卡在按下状态。
学习目标
- 给游戏对象设置 260×84 像素的交互命中区域。
- 绑定
pointerover、pointerdown、pointerup、pointerout处理反馈。 - 验证触屏点击、拖出取消和画布外释放的行为。
命中区域与事件范围
Phaser 将鼠标和触摸统一封装为 Pointer。只有对游戏对象调用 setInteractive(),对象自身的 on('pointerdown', ...) 等监听器才会接收指针事件。单击画布任意位置的监听器则写在 this.input 上,两者的触发范围不同。
本例使用一个中心位于 (400, 270)、宽 260、高 84 的 Rectangle 作为按钮底板,并显式传入 new Phaser.Geom.Rectangle(0, 0, 260, 84) 和 Phaser.Geom.Rectangle.Contains。这里的 (0, 0) 是对象局部命中区域的左上角,不是世界坐标;旁边叠放的文字只负责显示,不需要开启交互。
按下、释放和取消
按钮至少有常态、悬停态、按下态。鼠标进入时变亮,按下时变深;只有同一个 Pointer 先在按钮内按下、再在按钮内抬起,才执行一次按钮动作。触屏通常没有预先悬停阶段,应从常态直接进入按下态。

pointerup 只说明指针在对象上释放,并不保证它之前在这个对象上按下。因此用 pressedBy 记住按下者;用对象级 pointerout、场景级 pointerup、pointerupoutside 和 gameout 清除未完成的按压。离开整个画布时不能只依赖对象的 pointerout。
创建可运行按钮
在已安装 Node.js 和 npm 的环境中创建 Vite 原生 JavaScript 工程,安装固定版本 Phaser:
npm create vite@latest pointer-demo -- --template vanilla
cd pointer-demo
npm install
npm install phaser@4.2.1
npm run dev预期结果:终端显示 Vite 开发地址,例如 http://localhost:<PORT>/,具体端口以实际输出为准;首次访问仍是 Vite 初始页面。保持开发服务器运行。
将默认 src/main.js 完整替换为以下代码;Vite 模板的 index.html 已提供 #app 容器,无需下载图片素材。
import Phaser from 'phaser';
document.querySelector('#app').innerHTML = '<div id="game"></div>';
class MenuScene extends Phaser.Scene {
constructor() {
super('Menu');
}
create() {
const normal = 0x176e75;
const hover = 0x229a9d;
const pressed = 0x0b5056;
const button = this.add.rectangle(400, 270, 260, 84, normal)
.setStrokeStyle(2, 0x0f3942);
this.add.text(400, 270, '开始游戏', {
fontFamily: 'sans-serif',
fontSize: '30px',
color: '#ffffff'
}).setOrigin(0.5);
const feedback = this.add.text(400, 395, '等待点击', {
fontFamily: 'sans-serif',
fontSize: '22px',
color: '#263746'
}).setOrigin(0.5);
// 命中区域使用对象局部坐标,不是画布坐标。
button.setInteractive(
new Phaser.Geom.Rectangle(0, 0, 260, 84),
Phaser.Geom.Rectangle.Contains
);
button.input.cursor = 'pointer';
let pressedBy = null;
let count = 0;
const cancelPress = () => {
if (pressedBy === null) return;
pressedBy = null;
button.setFillStyle(normal);
feedback.setText('已取消');
};
button.on('pointerover', () => {
if (pressedBy === null) button.setFillStyle(hover);
});
button.on('pointerout', (pointer) => {
if (pointer === pressedBy) cancelPress();
else if (pressedBy === null) button.setFillStyle(normal);
});
button.on('pointerdown', (pointer) => {
if (pointer.button !== 0 || pressedBy !== null) return;
pressedBy = pointer;
button.setFillStyle(pressed);
feedback.setText('正在按下');
});
button.on('pointerup', (pointer) => {
if (pointer !== pressedBy) return;
if (pointer.wasCanceled || pointer.button !== 0) {
cancelPress();
return;
}
// 只在同一个指针于命中区内完成释放时触发。
pressedBy = null;
count += 1;
button.setFillStyle(pointer.wasTouch ? normal : hover);
feedback.setText(`已触发 ${count} 次`);
});
// 对象外释放和离开画布都要撤销待完成的点击。
this.input.on('pointerup', (pointer) => {
if (pointer === pressedBy) cancelPress();
});
this.input.on('pointerupoutside', (pointer) => {
if (pointer === pressedBy) cancelPress();
});
this.input.on('gameout', () => {
cancelPress();
button.setFillStyle(normal);
});
}
}
new Phaser.Game({
type: Phaser.AUTO,
parent: 'game',
width: 800,
height: 600,
backgroundColor: '#f5f8fa',
scene: MenuScene
});预期结果:保存后页面热更新,显示青绿色「开始游戏」按钮和「等待点击」文字。鼠标移入按钮变亮,按下变深,在按钮内部抬起后文字变为「已触发 1 次」;继续点击时计数逐次加一。手机触摸按下也会变深,松开后恢复常态。
验收与常见误触
按下列顺序测试,不需要打开浏览器控制台:
| 操作 | 应看到的结果 |
|---|---|
| 鼠标在按钮内按下并抬起 | 计数只增加 1 |
| 在按钮内按下,拖到按钮外再松开 | 出现「已取消」,计数不变 |
| 按住后将鼠标拖出画布 | 按钮恢复常态,计数不变 |
| 仅在按钮外按下,移入按钮后抬起 | 不执行按钮动作 |
| 手机手指在按钮内按下并抬起 | 正常增加 1 次,无需悬停 |
若点击完全无效,先检查对象是否调用 setInteractive(),再检查命中区域尺寸和是否有上层互动对象遮挡。若按钮按下后不能复位,检查场景级释放监听器是否注册。本例的事件与参数可对照 Phaser 输入系统文档 核实。