前言前面我们用onTouch处理手势、onHover处理悬停——但都是「指针」类输入。还有种「按键」类输入PC 键盘WASD/方向键/空格、TV 遥控器方向键/确认/返回、手机外接手柄/键盘。这类输入不走触摸/悬停要走onKeyEvent事件——捕获按下/抬起/长按三阶段配合KeyCode判定具体键。本篇以「猫猫大作战」PC 端用方向键选列、空格投放、ESC 暂停为预演场景把onKeyEvent 三阶段触发、KeyCode 判定具体键、KeyEventSource 判定输入源、与 onClick/onTouch 的取舍四大要点讲透。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–52 篇。本篇是阶段三第三篇。一、场景拆解PC 键盘操控游戏「猫猫大作战」当前用onClick列投放第 37 篇——手机端玩家点击列。但 PC 端玩家想用键盘←/→ 方向键左右选列高亮预览空格键投放选中列ESC 键暂停/恢复R 键重新开始onClick和onTouch都捕获不到键盘——要用onKeyEvent// 预演Index 加 onKeyEvent 键盘操控 State highlightCol: number 0; // 键盘选中列0-4 build() { Stack() { /* ... */ } .onKeyEvent((event: KeyEvent) { switch (event.keyCode) { case KeyCode.KEYCODE_LEFT: // ← 左移 this.highlightCol Math.max(0, this.highlightCol - 1); break; case KeyCode.KEYCODE_RIGHT: // → 右移 this.highlightCol Math.min(4, this.highlightCol 1); break; case KeyCode.KEYCODE_SPACE: // 空格投放 if (event.type KeyType.Down) { this.handleColumnClick(this.highlightCol); } break; case KeyCode.KEYCODE_ESCAPE: // ESC 暂停/恢复 if (event.type KeyType.Down) { if (this.gameState GameState.PLAYING) { this.pauseGame(); } else if (this.gameState GameState.PAUSED) { this.resumeGame(); } } break; case KeyCode.KEYCODE_R: // R 重新开始 if (event.type KeyType.Down) { this.clearTimers(); this.startGame(); } break; } return true; // ← 消费事件 }) }核心问题onKeyEvent的三阶段Down/Up/Repeat分别在何时触发KeyCode怎么判定按的是哪个键KeyEventSource怎么判定是键盘、遥控器还是手柄按键事件和点击事件怎么协同二、onKeyEvent 三阶段触发2.1 三种阶段键按下down→ onKeyEvent(KeyType.Down) 键松开up→ onKeyEvent(KeyType.Up) 键住不动repeat→ onKeyEvent(KeyType.Repeat) 持续触发阶段KeyType触发时机频率按下Down键被按下1 次抬起Up键被松开1 次重复Repeat按住不放高频系统 repeatRate关键经验onKeyEvent 三阶段和 onTouch 类似——Down 开始、Repeat 持续、Up 结束。但「按键」走 onKeyEvent「触摸」走 onTouch。2.2 事件回调签名.onKeyEvent((event: KeyEvent) { // event.type: KeyTypeDown/Up/Repeat // event.keyCode: KeyCode具体键 // event.keyText: 键文本如 A, Space // event.source: KeyEventSource输入源 // event.repeatCount: 重复次数Repeat 阶段累加 // event.timestamp: 时间戳 return true; // 返回 true 消费事件false 不消费向上冒泡 })2.3 返回值消费 vs 冒泡.onKeyEvent((event: KeyEvent) { if (event.keyCode KeyCode.KEYCODE_SPACE) { this.handleColumnClick(this.highlightCol); return true; // 消费空格不向上冒泡 } return false; // 其他键不消费向上冒泡给父组件 })关键经验返回 true 消费事件false 向上冒泡——父组件的 onKeyEvent 会收到子未消费的键。本系列第 66 篊会专讲事件冒泡。三、KeyCode 判定具体键3.1 常用 KeyCodeenum KeyCode { // 方向键 KEYCODE_LEFT 2, KEYCODE_RIGHT 3, KEYCODE_UP 4, KEYCODE_DOWN 5, // 功能键 KEYCODE_SPACE 49, KEYCODE_ESCAPE 6, KEYCODE_ENTER 66, KEYCODE_BACK 4, // 字母键 KEYCODE_A 29, KEYCODE_R 46, KEYCODE_P 44, // 数字键 KEYCODE_0 7, KEYCODE_1 8, // ... // 遥控器专有 KEYCODE_DPAD_CENTER 23, // 遥控器确认键 KEYCODE_DPAD_LEFT 21, KEYCODE_DPAD_RIGHT 22, KEYCODE_DPAD_UP 19, KEYCODE_DPAD_DOWN 20, }3.2 判定具体键.onKeyEvent((event: KeyEvent) { switch (event.keyCode) { case KeyCode.KEYCODE_LEFT: case KeyCode.KEYCODE_DPAD_LEFT: // ← 键和遥控左键都算左移 this.highlightCol Math.max(0, this.highlightCol - 1); break; case KeyCode.KEYCODE_RIGHT: case KeyCode.KEYCODE_DPAD_RIGHT: this.highlightCol Math.min(4, this.highlightCol 1); break; case KeyCode.KEYCODE_SPACE: case KeyCode.KEYCODE_DPAD_CENTER: // 空格和遥控确认都算投放 if (event.type KeyType.Down) { this.handleColumnClick(this.highlightCol); } break; } return true; })关键经验PC 键盘和 TV 遥控器键码可能不同——KEYCODE_LEFTvsKEYCODE_DPAD_LEFT用case并列兼容多设备。3.3 keyText 辅助判定.onKeyEvent((event: KeyEvent) { console.info(按了 ${event.keyText}keyCode: ${event.keyCode}); // 打印按了 AkeyCode: 29 })实战经验debug 用 keyText 直观逻辑用 keyCode 精确——keyText 可能因输入法/键盘布局变keyCode 固定。四、KeyEventSource 判定输入源4.1 三种输入源enum KeyEventSource { KEYBOARD 0, // PC 键盘 REMOTE 1, // TV 遥控器 GAMEPAD 2, // 手柄 OTHER 3, }4.2 判定输入源做差异化.onKeyEvent((event: KeyEvent) { switch (event.source) { case KeyEventSource.KEYBOARD: console.info(PC 键盘输入); break; case KeyEventSource.REMOTE: console.info(TV 遥控输入); break; case KeyEventSource.GAMEPAD: console.info(手柄输入); break; } /* ... 按键逻辑 ... */ })实战经验通常不区分输入源——KeyCode 已兼容多设备。只在「手柄摇杆模拟方向」「遥控长按确认」特殊场景才区分 source。五、onKeyEvent vs onClick/onTouch 取舍5.1 三种事件覆盖输入事件输入设备触发条件onClick鼠标、手指、遥控确认完整点击onTouch鼠标、手指接触全过程onHover鼠标、遥控焦点不接触接近onKeyEvent键盘、遥控、手柄按键全过程5.2 取舍决策输入设备 ├─ 手指/鼠标 → onTouch onClick onHover └─ 键盘/遥控/手柄 → onKeyEvent关键经验跨设备应用同时加 onTouch/onHover/onKeyEvent——手机端用 onTouchPC 端用 onHoveronKeyEventTV 端用 onHoveronKeyEvent各自触发不冲突。5.3 同组件共存Stack() { /* ... */ } .onClick(() { /* 鼠标/手指点击 */ }) .onTouch((event) { /* 手指/鼠标全过程 */ }) .onHover((isHover) { /* 鼠标/遥控悬停 */ }) .onKeyEvent((event) { /* 键盘/遥控按键 */ }) // 四种事件各自独立不冲突六、实战PC 键盘操控游戏6.1 改造 Index 加 onKeyEvent// 预演Index 加 onKeyEvent 键盘操控 import { KeyCode, KeyType, KeyEvent, KeyEventSource } from ohos.multimodalInput; Entry Component struct Index { State gameState: GameState GameState.IDLE; State cats: Cat[] []; State highlightCol: number 0; // ← 键盘选中列0-4 /* ... 其他 state */ private gameEngine: GameEngine new GameEngine(); private readonly cols: number[] [0, 1, 2, 3, 4]; /* startGame / pauseGame / resumeGame / endGame / clearTimers / formatTime / aboutToDisappear 筑略 */ handleColumnClick(column: number) { if (this.gameState ! GameState.PLAYING) return; if (this.gameEngine.dropCat(column)) { this.cats this.gameEngine.getAllCats(); this.nextCatLevel this.gameEngine.getNextCatLevel(); } } // onKeyEvent 键盘操控处理本篇重点 onGameKeyEvent(event: KeyEvent): boolean { // 只在 PLAYING 态响应方向键和空格 if (this.gameState ! GameState.PLAYING this.gameState ! GameState.PAUSED) { return false; } switch (event.keyCode) { case KeyCode.KEYCODE_LEFT: case KeyCode.KEYCODE_DPAD_LEFT: if (event.type KeyType.Down) { this.highlightCol Math.max(0, this.highlightCol - 1); } return true; case KeyCode.KEYCODE_RIGHT: case KeyCode.KEYCODE_DPAD_RIGHT: if (event.type KeyType.Down) { this.highlightCol Math.min(4, this.highlightCol 1); } return true; case KeyCode.KEYCODE_SPACE: case KeyCode.KEYCODE_DPAD_CENTER: if (event.type KeyType.Down) { this.handleColumnClick(this.highlightCol); } return true; case KeyCode.KEYCODE_ESCAPE: if (event.type KeyType.Down) { if (this.gameState GameState.PLAYING) { this.pauseGame(); } else if (this.gameState GameState.PAUSED) { this.resumeGame(); } } return true; case KeyCode.KEYCODE_R: if (event.type KeyType.Down) { this.clearTimers(); this.startGame(); this.highlightCol 0; } return true; } return false; // 未识别键不消费向上冒泡 } Builder GameView() { Column() { this.GameHUD() Column() { Row() { /* 预告区 */ } Stack() { /* 棋盘背景 */ ForEach(this.cats, (cat: Cat) { /* ... */ }, (cat: Cat) cat.id) // 列点击层onClick 键盘高亮 Row() { ForEach(this.cols, (col: number) { Column() .width(GameConfig.CELL_SIZE) .height(GameConfig.BOARD_HEIGHT * GameConfig.CELL_SIZE) // 键盘选中列高亮 .backgroundColor(this.highlightCol col ? rgba(46, 204, 113, 0.3) : rgba(0,0,0,0)) .onClick(() { this.handleColumnClick(col); }) }, (col: number) click_${col}) } } .width(GameConfig.BOARD_WIDTH * GameConfig.CELL_SIZE) .height(GameConfig.BOARD_HEIGHT * GameConfig.CELL_SIZE) .borderRadius(12).clip(true).backgroundColor(#D6EEF5) }.alignItems(HorizontalAlign.Center) Spacer() Row() { /* 底部控制栏 */ } .width(100%).padding({ left: 24, right: 24, bottom: 24, top: 12 }) } .width(100%).height(100%) .linearGradient({ direction: GradientDirection.Bottom, colors: [[#E8F4F8, 0.0], [#D6EEF5, 0.5], [#C9E8F2, 1.0]] }) .alignItems(HorizontalAlign.Center) } build() { Stack() { if (this.gameState GameState.IDLE) { this.MainMenuView() } else { this.GameView() } if (this.gameState GameState.PAUSED) { this.PauseOverlay() } if (this.gameState GameState.GAME_OVER) { this.GameOverOverlay() } } .width(100%).height(100%) .onKeyEvent((event: KeyEvent) this.onGameKeyEvent(event)) // ← onKeyEvent } /* GameHUD / MainMenuView / PauseOverlay / GameOverOverlay / StatItem 等略 */ }6.2 触发流程PC 键盘场景按 → 键 →onKeyEvent(Down, KEYCODE_RIGHT)→highlightCol从 0 变 1 → 选中列高亮。按 → 键 →highlightCol从 1 变 2。按空格 →onKeyEvent(Down, KEYCODE_SPACE)→handleColumnClick(2)→ 第 2 列投放猫。按 ESC →onKeyEvent(Down, KEYCODE_ESCAPE)→pauseGame()。按 ESC →onKeyEvent(Down, KEYCODE_ESCAPE)→resumeGame()。按 R →onKeyEvent(Down, KEYCODE_R)→ 重新开始。TV 遥控场景按 → 方向键 →onKeyEvent(Down, KEYCODE_DPAD_RIGHT)→ 同 KEYCODE_RIGHT 效果。按确认键 →onKeyEvent(Down, KEYCODE_DPAD_CENTER)→ 同空格效果。按返回键 →onKeyEvent(Down, KEYCODE_BACK)→ 通常路由返回未在本例处理。手机手指场景onKeyEvent不触发手机无物理键盘——但外接蓝牙键盘会触发。七、踩坑提示7.1 onKeyEvent 用普通函数丢 this// ❌ 错误普通函数 this 不指向组件 .onKeyEvent(function (event) { this.highlightCol; }) // ✅ 正确箭头函数保留 this第 38 篇讲过 .onKeyEvent((event: KeyEvent) { this.highlightCol; })7.2 忘判 KeyType.Down 重复触发// ❌ 错误没判 Down按住空格 Repeat 阶段也投放连投放多只 case KeyCode.KEYCODE_SPACE: this.handleColumnClick(this.highlightCol); // Down Repeat 都触发 break; // ✅ 正确只在 Down 触发Repeat 忽略 case KeyCode.KEYCODE_SPACE: if (event.type KeyType.Down) { this.handleColumnClick(this.highlightCol); } break;关键经验「单次操作」只判 Down忽略 Repeat——否则按住连发。连发场景如移动才用 Repeat。7.3 忘返回值冒泡// ❌ 错误没返回事件可能被父组件误处理 .onKeyEvent((event: KeyEvent) { if (event.keyCode KeyCode.KEYCODE_SPACE) { this.handleColumnClick(this.highlightCol); } // 忘了 return默认 undefined非 true }) // ✅ 正确返回 true 消费false 冒泡 .onKeyEvent((event: KeyEvent) { if (event.keyCode KeyCode.KEYCODE_SPACE) { this.handleColumnClick(this.highlightCol); return true; } return false; })7.4 忘兼容 PC 和 TV 键码// ❌ 错误只判 KEYCODE_LEFTTV 遥控的 KEYCODE_DPAD_LEFT 不响应 case KeyCode.KEYCODE_LEFT: this.highlightCol--; break; // ✅ 正确并列 PC 和 TV 键码 case KeyCode.KEYCODE_LEFT: case KeyCode.KEYCODE_DPAD_LEFT: this.highlightCol--; break;7.5 暂停态忘屏蔽方向键// ❌ 错误暂停态还能按方向键改 highlightCol但游戏暂停了没意义 onGameKeyEvent(event: KeyEvent): boolean { // 忘了守卫PAUSE 态也响应 switch (event.keyCode) { /* ... */ } } // ✅ 正确守卫屏蔽非 PLAYING 态 onGameKeyEvent(event: KeyEvent): boolean { if (this.gameState ! GameState.PLAYING this.gameState ! GameState.PAUSED) { return false; } // PAUSED 态只响应 ESC 恢复不响应方向键 if (this.gameState GameState.PAUSED event.keyCode ! KeyCode.KEYCODE_ESCAPE) { return false; } switch (event.keyCode) { /* ... */ } }八、调试技巧console.info打 keyCode 和 keyText追按了什么键确认键码。console.info打 type追 Down/Up/Repeat确认是否只 Down 触发。不触发排查确认焦点在组件上onKeyEvent 需组件有焦点确认设备有物理键盘手机无。连发排查检查是否忘判 KeyType.DownRepeat 阶段也会触发。九、性能与最佳实践跨设备同时加 onTouch/onHover/onKeyEvent——各自独立不冲突。KeyCode 用 case 并列兼容 PC 和 TV——KEYCODE_LEFT 和 KEYCODE_DPAD_LEFT 都算。「单次操作」只判 Down连发用 Repeat——避免按住连投放。返回 true 消费false 冒泡——父组件能收到子未消费的键。守卫屏蔽非游戏态——暂停/结束时只响应特定键ESC/R不响应方向键。回调用箭头函数保留 this——普通函数 this 丢失。十、阶段三进度51–55本篇是阶段三「交互与动画」第 3 篇篇主题核心要点51onTouch手势三阶段 Down/Move/Up52onHover悬停进入/离开TV/PC 场景53本篇onKeyEvent键盘/遥控按键三阶段KeyCode 判定54bindContextMenu右键/长按上下文菜单55animateTo显式动画触发总结本篇我们从 onKeyEvent 按键切入掌握了三阶段触发Down/Up/Repeat、KeyCode 判定具体键PC TV 兼容、KeyEventSource 输入源、与 onClick/onTouch 的取舍四大要点并给出了 PC 键盘操控游戏的完整代码。核心要点按键走 onKeyEvent 不走 onTouchKeyCode 并列兼容 PC/TV单次操作只判 Down 避免连发返回 true 消费 false 冒泡。下一篇我们将拆解 bindContextMenu——右键/长按上下文菜单。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源「猫猫大作战」项目源码本仓库entry/src/main/ets/pages/Index.etsArkUI onKeyEvent 按键事件官方指南KeyCode 键码枚举官方文档HarmonyOS 多模态输入最佳实践开源鸿蒙跨平台社区HarmonyOS 开发者官方文档首页系列索引本仓库articles/INDEX.md