游戏引擎 / 系统课时
监听键盘与触控输入
监听键盘与触控输入
桌面角色操作要识别按键按下与松开,移动端还要区分触点按下、拖动、抬起和取消。如果只处理按下事件,角色可能一直移动;如果不清理监听,场景切换后可能重复响应。本课用 Cocos Creator 3.8 编写一个同时观察键盘和单指触控的输入组件。
学习目标
- 判断应使用全局
input事件还是 UI 节点事件。 - 正确监听键盘与触控的开始、变化、结束和取消。
- 通过状态记录、触点 ID 和注销监听避免重复与残留输入。
区分全局输入和节点输入
Cocos Creator 3.8 的 input.on() 用于注册全局键盘、鼠标和触控事件,不要求事件命中某个节点。角色移动、全局快捷键适合先从这里接入。若要判断玩家是否按到了某个 UI 按钮,则通常在带 UITransform 的 UI 节点上使用 node.on(Node.EventType.TOUCH_START, ...),让节点的命中区域参与事件处理。
键盘关注 KEY_DOWN 和 KEY_UP;触控至少要处理 TOUCH_START、TOUCH_MOVE、TOUCH_END 和 TOUCH_CANCEL。其中 TOUCH_CANCEL 表示当前触控被中断,不能把它当成一次成功的点击。

实现可运行的输入探针
在项目中创建 InputProbe.ts,将组件挂到场景中一个处于启用状态的节点,然后运行浏览器预览。示例以 A 键表示一个方向键,触控只追踪第一根手指;这样即使多指同时触摸,也不会用后来的触点覆盖当前操作。
import { _decorator, Component, input, Input, EventKeyboard, EventTouch, KeyCode } from 'cc';
const { ccclass } = _decorator;
@ccclass('InputProbe')
export class InputProbe extends Component {
private aHeld = false;
private trackedTouch: number | null = null;
onEnable(): void {
input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
input.on(Input.EventType.KEY_UP, this.onKeyUp, this);
input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
input.on(Input.EventType.TOUCH_MOVE, this.onTouchMove, this);
input.on(Input.EventType.TOUCH_END, this.onTouchFinish, this);
input.on(Input.EventType.TOUCH_CANCEL, this.onTouchFinish, this);
}
onDisable(): void {
// 组件停用时对称注销全局监听,防止重复回调。
input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
input.off(Input.EventType.KEY_UP, this.onKeyUp, this);
input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
input.off(Input.EventType.TOUCH_MOVE, this.onTouchMove, this);
input.off(Input.EventType.TOUCH_END, this.onTouchFinish, this);
input.off(Input.EventType.TOUCH_CANCEL, this.onTouchFinish, this);
this.aHeld = false;
this.trackedTouch = null;
}
private onKeyDown(event: EventKeyboard): void {
// 长按期间若再次收到按下事件,不重复触发按下动作。
if (event.keyCode !== KeyCode.KEY_A || this.aHeld) return;
this.aHeld = true;
console.log('键盘 A:按下');
}
private onKeyUp(event: EventKeyboard): void {
if (event.keyCode !== KeyCode.KEY_A || !this.aHeld) return;
this.aHeld = false;
console.log('键盘 A:松开');
}
private onTouchStart(event: EventTouch): void {
const id = event.getID();
if (this.trackedTouch !== null || id === null) return;
// 只绑定第一个触点,避免多指拖动时操作对象跳变。
this.trackedTouch = id;
const p = event.getUILocation();
console.log(`触控:按下 id=${id} x=${Math.round(p.x)} y=${Math.round(p.y)}`);
}
private onTouchMove(event: EventTouch): void {
if (this.trackedTouch === null || event.getID() !== this.trackedTouch) return;
const d = event.getUIDelta();
console.log(`触控:移动 dx=${Math.round(d.x)} dy=${Math.round(d.y)}`);
}
private onTouchFinish(event: EventTouch): void {
if (this.trackedTouch === null || event.getID() !== this.trackedTouch) return;
const action = event.type === Input.EventType.TOUCH_CANCEL ? '取消' : '抬起';
console.log(`触控:${action}`);
this.trackedTouch = null;
}
}预期输出(先按下并松开 A,再单指按下、拖动并抬起;触点编号与位置随实际操作变化):
键盘 A:按下
键盘 A:松开
触控:按下 id=<ID> x=<X> y=<Y>
触控:移动 dx=<DX> dy=<DY>
触控:抬起这里的 <ID>、<X>、<Y>、<DX>、<DY> 是演示占位符,不是引擎固定返回值。若触摸被中断,最后一行会变成 触控:取消;若手指没有移动,则不会产生移动日志。
为什么事件和输入状态要分开
KEY_DOWN 是一个发生过的事件,而 aHeld 表示此刻是否保持按住。连续移动应由游戏的 update(deltaTime) 根据当前按键状态和帧间隔计算,不能只靠按下回调移动一次,也不要每次按下就启动一个未清理的定时器。这个探针只负责采集和打印,后续可以把布尔状态交给移动组件消费。
对触控而言,getID() 用来识别同一根手指,getUILocation() 返回当前 UI 坐标,getUIDelta() 返回相邻触控事件间的 UI 位移。它们不等于角色父节点的局部坐标;做虚拟摇杆时,还需要将触点位置换算到摇杆所属 UI 节点的坐标系。多指手势应另行管理多个触点,不能继续使用本例的单一 trackedTouch。
验证事件清理和边界行为
在预览窗口先点击游戏区域使其获得键盘焦点,再按 A、松开 A,确认各出现一次相应日志。接着拖动一个触点,观察 按下 → 移动 → 抬起 的顺序;浏览器预览是否以鼠标模拟触控取决于运行环境,必要时使用移动设备预览。停止拖动后不应继续输出移动日志。
最后禁用挂载该组件的节点或组件,再操作键盘和触屏,确认没有新日志;重新启用后应恢复正常监听。若出现一按就打印多次、切场景后仍响应,优先检查是否把 input.on() 重复放在 update() 或没有在 onDisable() 中成对调用 input.off()。对于应用失焦或切后台,还应在相应的生命周期处理里清空按键状态,避免系统未补发松开事件造成“卡键”。