到这个系列的第三篇棋盘绘制、方块生成这些基础已经搞定俄罗斯方块真正能玩起来靠的是把玩家的手指和遥控器变成游戏世界里的移动指令。在 Flutter for OpenHarmony 这套环境里交互控制与事件处理不像普通项目中那么理所当然键盘事件、焦点系统、触摸手势都需要重新梳理一遍有些坑只有真机跑过才意识得到。这篇文章我以俄罗斯方块为载体重点讲 OpenHarmony 上 Flutter 的交互控制与事件处理怎么做从输入需求拆解到 Focus 和 KeyEvent 的关系再到按键映射、触摸屏方案和真机调试经验。适合准备在 OpenHarmony 上用 Flutter 写游戏或工具型应用、尤其是之前只写过 Android/iOS 标准项目的开发者读完可以直接把架构思路抄到项目里。1. 先理清需求俄罗斯方块的输入到底要处理什么1.1 六个动作两种触发方式俄罗斯方块看起来简单输入需求一点也不少。横向移动、旋转、软降、硬降、暂停、重新开始至少六个基础动作。这里面真正容易出问题的是触发方式有的动作只按一次就够比如旋转和硬降有的动作要求按住之后持续响应比如左移、右移和软降。这两种触发方式如果混在一个机制里手感就会出问题。我一开始做的时候直接在按键回调里调用 game.moveLeft()结果长按方向键时就发现不对了按键会自动重复但不同设备的重复频率完全不一样在模拟器上很快到开发板上就慢吞吞。所以交互层的首要原则是把“按下”和“按住”分开处理按下的事件只负责更新状态按住期间产生的连续移动交给游戏自己的循环去驱动而不是依赖系统自动重复。这一条同样适用于触摸屏。屏幕上放置的左移按钮按下时进入按住状态抬起时清除状态左移的连续行为还是由同一套游戏循环统一计算。这样键盘和触摸用的移动逻辑就是同一份交互层只需要做“事件采集”后面做真机适配会轻松很多。梳理一下输入需求可以直接当作映射配置来用动作触发方式期望行为键盘建议左移/右移按住持续每帧按设定速度连续移动左/右方向键、A/D顺时针旋转单次触发方块立刻旋转90度上方向键、W、X逆时针旋转单次触发方块反向旋转90度Q、Z软降按住持续以更高频率下移松开恢复下方向键、S硬降单次触发当前方块直接落底并锁定空格暂停/继续单次触发切换暂停状态P重新开始单次触发重置整局R1.2 OpenHarmony 设备有多种输入形态必须先抽象第二件要提前想清楚的事是 OpenHarmony 的落地设备形态很杂。最常见的输入设备有三种遥控器、触摸屏、外接键盘。电视盒子用遥控器一体机和班牌用触摸屏部分开发板接键盘调试。三类设备的体验目标不一样但游戏逻辑必须共用同一套状态机。在 OpenHarmony 的 Flutter 移植运行时里系统输入会被尽量转换成标准的 Flutter KeyEvent 和 PointerEvent但它和传统 Android 原生的 KeyEvent 并不是一一对应的。比如遥控器上的一些键在部分设备里走的是硬件扫描码Flutter 侧收到的 logicalKey 可能不是标准命名空间里的值有些键会被系统本身消费掉游戏窗口根本收不到。所以交互层必须做两件事一是把事件来源抽象掉无论键盘还是触摸最终都转成统一的游戏动作二是在真机上用日志验证每个键实际到达的 Key 对象别拿按键名称字符串去做硬编码判断。这里我必须强调一个取舍交互层要尽量走 Flutter 引擎自己的输入通道而不是绕道平台通道。除非某台设备的输入适配确实有问题需要你在原生侧通过 EventChannel 把 KeyEvent 转发给 Dart 侧否则不应该动用 EventChannel 或 PlatformView 这类机制。按键事件是高频、低延迟的输入走通道封装会平白增加一层不稳定的中转可能带来时序错乱。基础思路是先抽象输入再谈具体设备这能让代码同时服务键盘和触摸屏也是后续所有操作的地基。2. 定位关键Flutter for OpenHarmony 的事件处理架构与焦点机制2.1 FocusNode 是按键事件的“门卫”Flutter 的按键事件机制很多人一开始搞不懂明明我写了 GestureDetector 的 onTap为什么键盘按下去没反应原因在于按键事件和触摸事件走的是两套完全不同的通道。触摸事件由命中测试决定投向哪个 Widget按键事件则依赖焦点系统。只有焦点树里当前持有焦点的节点才有资格收到 KeyEvent。所以用键盘控制俄罗斯方块第一步不是写事件监听而是先把游戏区域变成一个可以获焦的节点。做法是创建一个 FocusNode用 Focus 组件包住游戏棋盘再把 autofocus 打开更稳的做法是页面加载完成后主动申请一次焦点。class _GameScreenState extends StateGameScreen { final FocusNode _gameFocusNode FocusNode(); override void initState() { super.initState(); _gameFocusNode.autofocus true; } override void dispose() { _gameFocusNode.dispose(); super.dispose(); } override Widget build(BuildContext context) { return Focus( focusNode: _gameFocusNode, onKeyEvent: _onKeyEvent, child: const GameBoard(), ); } }需要重点提醒的是焦点这东西丢了以后不会自动回来它需要你主动维护状态。我的习惯是在路由过渡动画结束或者页面重新可见时调用一次 FocusScope.of(context).requestFocus(_gameFocusNode)确保焦点始终落在游戏区。特别是从弹窗、二级页面返回的时候不少移植平台会把焦点清零不重新申请就只能重启应用才能恢复键盘操作。2.2 监听按键是直接走 Focus还是引入 Shortcuts/ActionsFlutter 官方推荐的按键处理方案是 Shortcuts Actions 自定义 Intent把按键映射到语义化动作上。比如“Delete 删除选中项”这类场景这个方案很优雅。但俄罗斯方块这类状态变化极其频繁的小游戏直接监听 KeyEvent 往往更省心。Shortcuts/Actions 的价值是解耦按键与业务逻辑而在一套已经做了 GameAction 抽象的游戏里事件回调只做一件事把 KeyDown 转换成 action再交给输入控制器。这已经达到了解耦目标没必要再叠一层。我实际开发中的区分原则是全局的快捷键比如暂停 P、重新开始 R可以用 Shortcuts/Actions 来做高频的移动、旋转、软降直接走 Focus 的 onKeyEvent。混合使用也不会冲突因为 Shortcuts 内部也是靠焦点链分发事件只要焦点节点在正确的分支上两者能共存。但如果你是第一次做建议先从 onKeyEvent 入手跑通之后再考虑优化。监听按键时要把 KeyDown 和 KeyUp 区分清楚。按住一个键系统持续发送 KeyDown 类型的事件后面事件的 repeat 标记为 true。想做“按一下移动一格长按连续移动”就不能看见 KeyDown 就执行移动必须把重复事件过滤掉单独维护按下状态。还要注意回调返回值onKeyEvent 返回 true 表示事件已经被处理不会继续向祖先节点传播返回 false 则可能触发上层快捷键。俄罗斯方块里我一般返回 true防止方向键误触页面的其它逻辑。2.3 为什么不建议依赖 RawKeyboard 全局监听以及 EventChannel 的边界老项目里经常见到 RawKeyboard.instance.addListener 这种写法它不依赖焦点也能收到全局按键事件。但这种方式绕过了焦点系统在路由切换、多个输入区域并存时无法判断事件到底该给谁。在 OpenHarmony 上我更不建议这么做因为移植版本的全局通道在某些设备上不保证与窗口焦点同步容易出现事件重复或漏报。如果你维护的是老代码可以继续用新代码统一走 Focus 体系。另外偶尔会有人提出用 EventChannel 从原生侧把 KeyEvent 转发到 Dart 侧理由是“原生层拿到的键码更全”。这个思路能用但要有限度。EventChannel 适合传递低频的结构化消息比如设备连接状态、系统设置变化不适合连续高频的按键输入。我实测过一台开发板按键事件经过原生侧转发以后偶发乱序操作节奏一快就会“按下和抬起调换”游戏手感完全没法看。除非 Flutter 引擎层的输入适配已经损坏否则不要走这条路。真到了那一步也要在原生侧做事件合流和去抖再交给 Dart 侧消费。3. 实操代码按键到游戏动作的绑定与连动控制3.1 先建立输入意图层别让事件直接改游戏状态为了不让按键事件和游戏状态耦合我先定义一个动作枚举把所有可执行动作列出来enum GameAction { moveLeft, moveRight, rotate, softDrop, hardDrop, pause, restart, }然后实现一个输入控制器。它内部维护两个集合一个记录当前被按住的持续动作一个保存只触发一次的即时动作队列。按键事件来了只负责更新这两个集合不直接碰棋盘数据游戏循环每帧来消费它们。这样事件处理与游戏逻辑彻底解耦键盘和触摸屏都能复用同一个入口。class InputController extends ChangeNotifier { final SetGameAction _heldActions {}; final ListGameAction _oneShotQueue []; bool handleKeyDown(LogicalKeyboardKey key) { final action _mapKey(key); if (action null) return false; if (_isContinuous(action)) { _heldActions.add(action); } else { _oneShotQueue.add(action); } notifyListeners(); return true; } bool handleKeyUp(LogicalKeyboardKey key) { final action _mapKey(key); if (action null) return false; _heldActions.remove(action); notifyListeners(); return true; } void consumeOneShotQueue() { _oneShotQueue.clear(); } bool isHeld(GameAction action) _heldActions.contains(action); }这段代码是核心骨架实际项目里 _mapKey 的映射表会单独抽成配置触摸屏按钮只要调用 handleKeyDown/handleKeyUp 的同一个入口后面扩展新输入设备就是加一行映射的事。3.2 按键映射表与真机键位确认在 OpenHarmony 上做键位映射建议同时了解 two 个概念logicalKey 和 physicalKey。physicalKey 是键的物理位置比如主键盘左上角那个键logicalKey 是逻辑含义比如“向左”。映射优先用 logicalKey因为它表达的是“用户想让游戏做什么”。但在部分电视遥控器上某些键的 logicalKey 可能并不标准这时候需要先打印出来再补映射。下面是我项目里的键位对照参考游戏动作键盘逻辑键遥控器建议moveLeftarrowLeft / keyA方向键左真机确认moveRightarrowRight / keyD方向键右真机确认rotatearrowUp / keyW / keyX方向键上或确认键softDroparrowDown / keyS方向键下hardDropspace确认键需真机验证pausekeyP菜单键restartkeyR长按确认键实现里判断 key 时不能用 label要用 keyId 比较。比如判断左移GameAction? _mapKey(LogicalKeyboardKey key) { final id key.keyId; if (id LogicalKeyboardKey.arrowLeft.keyId || id LogicalKeyboardKey.keyA.keyId) { return GameAction.moveLeft; } // ... 其余映射 }为什么不建议用 label因为 label 是给用户展示用的字符串在 OpenHarmony 的某些设备上可能是空字符串也可能是与标准布局不同的符号直接比较容易踩坑。keyId 是稳定的键值跨平台表现一致。3.3 GameLoop 里消费持续动作统一节奏前面强调过长按不能依赖系统键盘的 repeat解决办法是让游戏循环亲自消费动作。通常用 Ticker 或 Timer.periodic 作为游戏心跳每帧做四件事消费一次性的动作队列、根据按住状态更新移动、执行软降、刷新界面。以软降为例正常下落是每 800ms 下移一行软降键按住了就改成每 40ms 下移一行。这样不管遥控器有没有自动重复软降速度都稳定。如果使用 Timer.periodic记得在页面挂起或游戏暂停时停掉否则切后台再回来游戏可能已经结束。我踩过跟硬降相关的坑硬降触发后应该立即落底并锁定方块它是一次性动作。但如果在同一帧里队列中残留了两个硬降动作会出现方块落底后又强制触发一次锁定视觉上就“闪了一下”。解决办法是消费一次性动作后立刻清空队列且每次都校验一次“当前方块是否已经锁定”。代码上不要用 removeAt 一个个取直接用 clear 清空整条队列更安全。4. 触摸方案手势识别、虚拟按键设计与焦点回收4.1 触摸设备是 OpenHarmony 的重要场景不能省遥控器不是唯一选择。我接触到的 OpenHarmony 项目里不少交互终端是触摸屏自助一体机、电子班牌、展厅大屏。触摸屏上再拿遥控器就很不自然。但触摸方案想做得顺不是画四个按钮那么简单。需要处理好三件事手势冲突、连续触发、焦点回收。连续触发的问题前面已经解决触摸按钮按下时调用输入控制器的 handleKeyDown抬起时调用 handleKeyUp剩余移动逻辑和键盘完全一样。这是整个交互层抽象带来的最大好处我几乎不用为触摸单独设计移动逻辑。手势冲突则要看具体布局下面给方案。4.2 滑动区分移动按钮区分旋转与硬降长按软降把游戏区按空间切分成两个区域左侧是移动区右侧是操作区。移动区用 GestureDetector 识别横向滑动每次滑动超过一格的大小就转成一步 moveLeft/moveRight右侧放旋转和硬降两个按钮。这样点击与滑动不在同一块区域竞争GestureDetector 的 gesture arena 冲突就少了一大半。GestureDetector( onPanUpdate: (details) { _dragOffset details.delta.dx; final threshold _tileSize; if (_dragOffset threshold) { inputController.handleKeyDown(LogicalKeyboardKey.arrowRight); inputController.handleKeyUp(LogicalKeyboardKey.arrowRight); _dragOffset 0; } else if (_dragOffset -threshold) { inputController.handleKeyDown(LogicalKeyboardKey.arrowLeft); inputController.handleKeyUp(LogicalKeyboardKey.arrowLeft); _dragOffset 0; } }, child: gameBoard, )右侧旋转按钮上还可以叠加长按软降点击执行旋转按住超过 400ms 进入软降状态。实现上我用按压状态判断onTapDown 启动一个 Timer400ms 到期后把软降动作加入按住集合如果 Timer 到期前触发了 onTapUp就取消 Timer 并执行一次旋转。这样点击就是短按旋转长按才进入连降互不干扰。唯一要注意的是取消 Timer 的时机onTapCancel 里也要清掉防止手指滑出去后仍在软降。4.3 焦点回收别让按钮把游戏焦点抢走这是触摸方案里最隐蔽的问题。游戏页面里如果放一个 Material 风格的 IconButton点击它会默认申请焦点焦点一旦被按钮拿走键盘和遥控器上的方向键就失效了相当于给玩家关上了一扇门。解决起来不难第一游戏区域内的控制按钮尽量不要用会抢焦点的组件优先用 GestureDetector 或自绘组件。第二如果某些场景确实用了 Button在 onPressed 回调末尾调用 FocusScope.of(context).requestFocus(_gameFocusNode)把焦点拉回来。第三如果点击后还有动画或弹窗就放到 WidgetsBinding.instance.addPostFrameCallback 里再申请确保焦点树已经完全构建。另外触摸方案的点击反馈也很重要。我一般用 AnimatedContainer 的颜色变化按下变深、抬起恢复成本极低玩家却明显能感受到自己按中了。这个细节看起来不起眼实际调试时帮我筛掉了很多“我是不是没按到”的疑问。5. 真机调试事件驱动的几个深坑与排查速查5.1 焦点“神秘消失”的排查流程一旦出现“按键没反应”先不要怀疑按键映射九成是焦点丢了。我的排查顺序是先在 FocusNode 上注册监听打印 hasFocus 变化然后触发可能引起焦点变化的行为比如页面切换、弹窗打开关闭、点击屏幕、键盘弹出收起如果日志显示 hasFocus 变成 false说明焦点确实被抢占接下来看 Widget 树中哪个组件在管理焦点最后在恢复路径上统一补一次 requestFocus。有时候焦点树比你想的更复杂。页面外层包了 Scaffold里层还有别的 FocusScoperequestFocus 只作用于当前 scope 内。遇到这种情况可以临时调用 debugDumpFocusTree() 打印整棵焦点树它能清楚看到每个节点的 hasFocus 状态和 scope 层级比瞎猜高效得多。这是我排焦点问题最常用的命令。5.2 KeyDown 的 repeat 不可靠KeyUp 可能迟到甚至缺失遥控器键盘最让人头疼的是重复事件。标准 Flutter 有 KeyRepeatEvent但 OpenHarmony 的设备适配往往把 repeat 当成普通 KeyDown 的 repeat 标志位不同设备的长按重复频率差异很大。如果直接用 repeat 做软降就会出现同一台机器上按方向键移动时快时慢的问题。最终我全部改用游戏循环定时消费按住状态彻底绕开 repeat。KeyUp 缺失的问题更隐蔽。某些设备在按住期间如果焦点发生变化或者系统把它当成长按扫描码处理Flutter 侧可能收不到 KeyUp。为此我给按住状态加了一个超时清理逻辑如果某个动作超过 1 秒都没有收到新的按键事件自动清除按住状态。这个操作几乎不消耗性能但能在异常输入情况下防止方块“自己往一个方向冲出去”。5.3 热重载导致事件重复先查监听器泄漏开发时用 Hot Reload 调试事件代码最容易遇到的现象是按一次左移方块移动了两格。第一反应是业务逻辑重复执行了仔细查才发现是旧的 FocusNode 监听没释放又叠加了新的监听。解决办法不要在 initState 里使用匿名 listener改用具名方法并在 dispose 中 remove热重载后怀疑监听泄漏就切换成 Hot Restart 复测确认问题消失后再回到业务代码。另一个类似问题是计时器泄漏。我给游戏启动了一个 60fps 的 Ticker 控制循环页面被路由推走时没有停掉返回游戏页后旧 Ticker 还在跑方块每帧被驱动两次。现在的习惯是所有周期性的东西都跟着 State 生命周期走dispose 里统一 cancel不要指望框架自动收拾。5.4 问题速查表与最终经验现象可能原因排查与解决按方向键完全无反应焦点不在游戏区域打点确认 hasFocus并 requestFocus按键能触发但方向反了映射用了 label 或搞反 KeyDown/Up打印 logicalKey基于 keyId 判断长按移动速度不稳定依赖系统 repeat改由 GameLoop 统一节奏驱动一次按键触发两次动作监听器泄漏或重复绑定清理 dispose用 Hot Restart 复测点击触摸按钮后键盘失灵按钮抢走焦点点击后恢复游戏焦点避免可聚焦组件部分遥控器键收不到系统消费了按键在原生侧确认透传情况必要时改键位说实话按键映射和手势识别本身都不难真正花时间的全在焦点和生命周期管理上。如果你也遇到看起来莫名其妙的问题先对照这张表过一遍大概率能定位到方向。最后再分享一个小经验做跨设备交互不要把输入逻辑写在 Widget 的 build 方法里也不要依赖具体设备的 label。把“按键/触摸”转换成“动作意图”再让游戏逻辑消费意图是我在做俄罗斯方块这套代码里收益最大的一次重构。后面等这个系列写动画和音效部分时这套输入控制器还能继续复用不会因为加了新玩法就推倒重来。