TV与键盘焦点导航全解:Skills的compose-focus-navigation技能实战(D-pad与焦点遍历)

原创2026-10-14 10:50:221,750 阅读

TV与键盘焦点导航全解:Skills的compose-focus-navigation技能实战(D-pad与焦点遍历)

如果你正在开发 TV 端应用、需要键盘导航,或者想搞清楚 Jetpack Compose 里的 D-pad 焦点遍历到底该怎么写,这篇文章带你系统拆解 skills 项目中的 compose-focus-navigation 技能。skills 是一套面向 Kotlin、Jetpack Compose 与 Android 开发的专业技能集合,其中的焦点导航技能专门解决 TV 遥控器、键盘和桌面输入的焦点问题,帮你写出"焦点去哪儿、何时请求、怎么测试"都清清楚楚的 UI 代码。

Kotlin与Jetpack Compose焦点导航技能集合Skills项目横幅图

一、为什么 TV 和键盘应用必须重视焦点导航? 📺

在触屏手机上,用户点哪儿就是哪儿;但在 TV、桌面或无障碍场景下,焦点(Focus)就是用户的"光标":

  • TV 遥控器:用户用 D-pad(十字方向键)上下左右移动焦点,按确认键触发点击;
  • 键盘/桌面:Tab 键在可聚焦控件间跳转,方向键做空间遍历;
  • 无障碍:读屏用户完全依赖焦点顺序理解界面。

新手常见的三类坑,正好是 compose-focus-navigation 技能 要帮你避开的:

  1. 初始焦点落在意料之外的控件上(比如打开页面焦点在角落的按钮);
  2. 重新组合(recomposition)后 FocusRequester 丢失,焦点请求"失灵";
  3. 手工给每个控件硬编码焦点跳转,结果改了一处,整屏焦点图都乱了。

该技能的核心原则一句话概括:焦点是一种有状态的 UI 行为——先明确焦点目标和例外边界,再用用户真实的键盘、D-pad 或遥控器输入去驱动和验证它。

二、按需选型:4 种焦点需求对应 4 种写法 ✅

技能文档中最实用的是一张"需求 → 方案"对照表。不是每个控件都要加焦点代码,先查表再动手:

你的需求 推荐做法
普通按钮 / 文本框 / 可点击组件的默认焦点 什么都不用加,组件本身已可聚焦
程序化设置初始焦点或恢复焦点 FocusRequester + Modifier.focusRequester(...)
根据焦点变化改变外观或状态 Modifier.onFocusChanged { ... }
自定义交互区域(本身不可聚焦) Modifier.focusable(),并按需补充角色/语义信息

💡 技能的评测用例里专门有一个"克制"场景(delegation 负例):一个纯触屏按钮,除非代码证明存在键盘/TV/焦点恢复需求,不应该给它加任何焦点机制。少写代码,也是技能教会的一课。

三、实战步骤 1:让 FocusRequester 存活过重组 🧩

这是新手踩坑率最高的一步。FocusRequester 必须用 remember 持有稳定身份,否则每次重组都会生成新的 requester,焦点自然挂不到控件上。

正确姿势(摘自 SKILL.md):

val initialFocus = remember { FocusRequester() }

LaunchedEffect(initialFocus) {
    initialFocus.requestFocus()
}

两个关键细节:

  • requestFocus() 绝不能直接写在 Composable 函数体里。官方评测用例 compose-focus-navigation-novel 就针对典型的 TV Catalog 反例:
val requester = remember { FocusRequester() }
requester.requestFocus()   // ❌ 在组合期间执行,时机不可靠

正确做法是把请求放进事件或带键的 LaunchedEffect 中,等目标控件真正组合完成后再发起。

  • 目标控件是异步加载出来的? 把 Effect 的键绑定到"目标已出现"的条件上,例如 LaunchedEffect(items.isNotEmpty()),数据到了才请求焦点。

这个"记住 requester"的修复点,也正是评测用例 compose-focus-navigation-direct 的考核内容(评分标准见 expectations.json:必须出现 remember { FocusRequester() })。

四、实战步骤 2:D-pad 焦点遍历,默认优先、例外才覆盖 🎮

Jetpack Compose 默认就提供空间搜索:按 D-pad 某个方向时,自动找该方向上最近的焦点目标。绝大多数界面用默认行为就够好。

技能的建议是:只有当某条边界的默认行为确实"错了"(该跳不跳、跳错地方、需要焦点陷阱)时,才用 focusProperties 编码这条例外:

Modifier.focusProperties {
    up = headerRequester
    down = firstRowRequester
    left = FocusRequester.Cancel
}

反面教训写在技能里非常直白:硬编码的焦点链接太多,会形成"过期的焦点图"——布局一变,手工链接就指向错误的位置。所以只覆盖你确认有问题的方向,其余交给默认遍历。

五、处理特殊按键:只消费你真正处理的事件 ⌨️

D-pad 的上下左右属于"遍历",交给系统;只有非点击、非遍历的特殊行为(例如按返回键触发页面逻辑)才需要自己拦截。技能给出的要点:

  • 用 Modifier.onPreviewKeyEvent 拦截;
  • 只精确消费(consume)你处理的那个事件,其余一律返回 false 交还给系统。

这样既不会吞掉用户的方向键遍历,也不会把一次按键"放大"成全局行为。另外,如果快速连按方向键触发昂贵操作,节流应该做在那个"昂贵操作的拥有者"身上,而不是笼统地限制整屏。

六、像用户一样测试焦点行为 🧪

焦点行为必须用用户真实的输入模型验证,而不是直接改状态假装焦点变了。技能的测试范式只有两行核心:

composeTestRule.onNodeWithTag("screen").performKeyInput {
    pressKey(Key.DirectionDown)
}
composeTestRule.onNodeWithTag("play-button").assertIsFocused()

一次具体的按键交互 + 一条焦点断言,就证明了一条焦点路径。截图测试只用来验证焦点的外观(高亮环、放大效果)。更完整的测试策略可以延伸阅读项目里的 Compose UI 测试模式技能。

七、效果如何?看看官方评测成绩单 📊

skills 项目自带一套评测体系(evals/),对比"无技能基线"与"技能自动激活"两组结果。compose-focus-navigation 的数据相当有代表性(摘自 README.md):

指标 基线 技能自动激活
正确率 33.3% 100.0%
克制性(不画蛇添足) — 100.0%

也就是说,没有这份技能指导时,模型在焦点导航任务上的正确率只有三成;启用后达到满分,并且在"不该改就不改"的克制性检查中同样全部通过。

八、新手速查清单 📝

最后,把整套方法浓缩成 6 步检查清单,写 TV/键盘 UI 前对照一遍:

  1. 默认可聚焦组件不加额外焦点代码;
  2. 初始/恢复焦点用 remember { FocusRequester() } + focusRequester;
  3. requestFocus() 放在 LaunchedEffect 等事件边界里,目标异步出现时按条件加键;
  4. 焦点遍历优先用默认空间搜索,只覆盖确认错误的方向;
  5. 特殊按键只消费被处理的事件;
  6. 用 performKeyInput 模拟真实按键 + assertIsFocused 断言来测试。

完整的规则、示例与评审要点,都沉淀在这份技能文档里:skills/compose-focus-navigation/SKILL.md。按它写、按它审,你的 TV 应用和键盘交互界面就能告别"焦点乱跑"的尴尬。

登录后查看全文
skills