Readest 的 D-pad 空间导航架构:Android TV / 蓝牙遥控器与桌面键盘的无障碍导航实现
Readest 的 D-pad 空间导航架构:Android TV / 蓝牙遥控器与桌面键盘的无障碍导航实现
本篇技术指南围绕 Readest 中 D-pad(方向键/十字键)空间导航的实现展开,介绍其在 Android TV 蓝牙遥控器与桌面键盘场景下的架构设计、关键文件、核心实现原理,以及开发过程中踩过的 7 类典型坑位。读完本文,你将掌握 Readest 如何在"零第三方依赖"前提下,用两个同名 useSpatialNavigation Hook 分别支撑阅读器工具栏与书架网格的空间导航,理解 focus-probe 可见性探测、eventDispatcher 短路由、WebView 内建空间导航冲突等底层机制,并能直接复用这些方案解决自己项目中的电视端/键盘端焦点管理问题。
D-pad 空间导航的背景与目标
Readest 作为一款跨平台电子书阅读器,需要在 Android TV 这类"无鼠标、只有蓝牙遥控器"的设备上提供可用的操作路径。遥控器通过 D-pad 输出方向键(ArrowLeft/ArrowRight/ArrowUp/ArrowDown)与确认键(Enter),这些按键事件在 Web 技术栈中恰好与桌面键盘的方向键一致——因此 D-pad 支持天然复用了键盘方向键导航,这也让桌面端读者获得了一致的体验。
依据仓库中的设计文档 dpad-navigation.md,D-pad 支持实现了两大核心目标:
- Android TV 场景:支持蓝牙遥控器的空间导航,让用户不借助触摸屏即可在书架、阅读器工具栏之间移动焦点;
- 桌面场景:方向键在阅读器工具栏与书架网格中同样生效,与既有快捷键系统协作。
整个实现建立在两个核心 Hook 之上:阅读器工具栏导航与图书馆网格导航。它们的导航模式不同,但共享同一套"空间导航"概念。
架构总览:两个同名的 useSpatialNavigation Hook
Readest 刻意让两个 Hook 同名、放置在不同目录,各自承担不同的导航模式:
| Hook 文件 | 导航对象 | 导航模式 |
|---|---|---|
| src/app/reader/hooks/useSpatialNavigation.ts | 阅读器顶栏(header-bar)与底栏(footer-bar) | 工具栏按钮间的线性移动:左/右在按钮间移动,上/下在顶栏↔底栏之间切换 |
| src/app/library/hooks/useSpatialNavigation.ts | 图书馆书架网格(BookshelfItem) | 二维网格移动:方向键按列/行移动焦点,支持从网格外部(如顶栏)通过 ArrowDown 进入 |
两个 Hook 都平台无关——不仅服务于 Android TV,桌面浏览器与 Tauri 桌面端同样生效。
围绕这两个 Hook,还有一组关键配套文件:
- src/helpers/shortcuts.ts ——
onToggleToolbar绑定Enter键,用于切换阅读器工具栏可见性; - src/app/reader/hooks/useBookShortcuts.ts ——
toggleToolbar处理器负责显示/隐藏 header + footer 两栏,且在<button>聚焦时跳过拦截,让原生 click 事件自然触发; - src/tests/hooks/useSpatialNavigation.test.tsx —— 阅读器工具栏导航的单元测试。
阅读器工具栏的 D-pad 导航实现
自动聚焦与键盘激活判定
阅读器工具栏在 isVisible 变为 true 时自动聚焦第一个可用按钮。但一个关键细节是:只有"键盘激活"才自动聚焦,鼠标悬停触发的显示不抢焦点。实现通过模块级变量 lastKeyboardTime 记录最近一次键盘活动时间(在 document 上以捕获阶段监听 keydown 更新),当工具栏显示时判断 Date.now() - lastKeyboardTime < 200 来判定是否为键盘激活,见 useSpatialNavigation.ts#L6-L19。
之所以引入这个判定,是因为 iframe 内的 pointer 事件不会冒泡到主文档,而键盘事件总是能通过 window 上的 useShortcuts 到达——用键盘时间戳区分"键盘唤出"与"鼠标唤出"是可靠且廉价的手段。判定为键盘激活后,通过 setTimeout(..., 100) 延迟执行 focusFirstButton,给渲染留出时间窗。
左/右在按钮间移动,上/下切换顶栏↔底栏
工具栏容器上的 keydown 监听器(useSpatialNavigation.ts#L80-L108)处理两类按键:
- ArrowLeft / ArrowRight:在容器内"可聚焦按钮"列表中定位当前焦点索引,向相邻方向移动一格;到达首尾边界时保持原地不动;
- ArrowDown / ArrowUp:通过
document.querySelector('.footer-bar')/'.header-bar'找到对向工具栏,并对其执行focusFirstButton,实现顶栏↔底栏的焦点跳转。
Focus-probe:可靠的可见性探测技术
这是本实现中最具技术含量的设计。初始版本想用 offsetParent 判断按钮是否可见,但在移动端发现 position: fixed 容器(.footer-bar)内所有子按钮的 offsetParent === null,导致可见性判断彻底失效——display:none、visibility:hidden、fixed 定位三种隐藏方式对 offsetParent 的干扰各不相同,无法统一处理。
Readest 的解法是"focus-probe":依次对每个按钮调用 btn.focus(),然后检查 document.activeElement === btn。能真正获得焦点的按钮即为可见、可聚焦按钮(见 getFocusableButtons)。该方法对所有隐藏方式都正确,代价是需要短暂的焦点转移(探测完会恢复原焦点)。配合 button:not([disabled]) 选择器先过滤禁用按钮,再以 focus-probe 二次过滤,得到干净的"可导航按钮"列表。
图书馆书架网格的 D-pad 导航实现
书架网格导航位于 src/app/library/hooks/useSpatialNavigation.ts,与工具栏导航是两套独立的移动逻辑。
动态列数计算
网格是响应式布局,列数不固定。实现通过 getGridColumnCount 读取所有网格项(<a href="https://link.gitcode.com/i/9a11cf429a61842957dfecf9badee179" target="_blank">role="button"][tabindex="0"])的 getBoundingClientRect().top,统计与首项处于同一水平线的数量作为列数(容差 5px),见 [useSpatialNavigation.ts#L5-L12。列数确定后,上/下移动按 currentIndex ± cols 计算目标,左/右按 currentIndex ± 1 计算,配合边界检查与 scrollIntoView({ block: 'nearest' }) 保证移动项始终可见。
窗口级监听:从网格外部进入
书架容器自身的 keydown 处理器只在焦点位于容器内部时才会触发。因此实现额外注册了一个 window 级 keydown 监听器:当焦点在书架之外(如顶栏导航区)时按下 ArrowDown,且 !container.contains(document.activeElement),则把焦点送入网格第一个项。这保证了用户从任何外层元素都能一步进入书架网格,而非被"焦点隔离"在外。
与快捷键系统、手柄输入的协同
方向键与翻页快捷键的冲突与化解
在阅读器页面,裸的方向键本身被 shortcuts.ts 绑定为翻页/滚动操作(onGoLeft/onGoRight/onGoUp/onGoDown),这些监听器挂在 window 上。因此工具栏的 keydown 处理器必须同时调用 e.stopPropagation() 和 e.preventDefault(),阻止方向键冒泡到 window 触发翻页——这是坑 #4 的核心。单元测试中专门断言了 stopPropagation 被调用(useSpatialNavigation.test.tsx#L145-L153)。
Enter 键与 toggleToolbar 的交互
工具栏的显隐由 onToggleToolbar(Enter)驱动。toggleToolbar 处理器(useBookShortcuts.ts#L371-L379)有一个关键保护:当 document.activeElement.tagName === 'BUTTON' 时直接返回 false,不拦截 Enter——这样遥控器在某个按钮聚焦时按确认键,会让原生 click 触发按钮动作,而不是意外收起工具栏。
手柄输入:D-pad 与按键的统一映射
对于真实游戏手柄(含 Android TV 遥控器的"手柄模式"),src/hooks/useGamepad.ts 提供了标准 Gamepad API 到键盘事件的映射层,默认映射表(DEFAULT_BUTTON_MAP)包括:
| 手柄按钮 | 索引 | 映射键盘事件 |
|---|---|---|
| A | 0 | Enter |
| B | 1 | Escape |
| X / Y | 2 / 3 | x / y |
| LB / RB | 4 / 5 | ArrowLeft / ArrowRight |
| D-pad Up | 12 | ArrowUp |
| D-pad Down | 13 | ArrowDown |
| D-pad Left | 14 | ArrowLeft |
| D-pad Right | 15 | ArrowRight |
实现通过 requestAnimationFrame 轮询 navigator.getGamepads(),在按键边沿(按下/松开)派发对应的 keydown/keyup 键盘事件,左右摇杆轴同样按阈值(默认 0.5)映射为方向键。这意味着手柄/遥控器的 D-pad 最终被归一化为标准箭头键事件,从而被上述空间导航 Hook 无差别消费。
Android 端连接状态由 useAndroidGamepadConnection.ts 通过 Tauri 插件的 native-bridge 事件监听 gamepad-connection 驱动,避免直接依赖 WebView 的 Gamepad 轮询线程。
关键设计决策
- 不引入第三方空间导航库。曾尝试
@noriginmedia/norigin-spatial-navigation,但失败于两个原因:其初始化时序问题(React 子组件 effect 先于父组件 effect 执行)与既有useShortcuts系统冲突。自研方案更简单、更可控。 - 两个同名 Hook 各自为政。网格导航与工具栏按钮导航的模式差异较大,拆成两个文件避免相互耦合,但对外保持统一命名,语义清晰。
- 平台无关。Hook 不判断运行平台,Android TV、桌面 Web、Tauri 桌面端共享同一套导航逻辑。
- focus-probe 替代
offsetParent。如前述,这是处理各种隐藏方式(display:none、visibility:hidden、fixed 定位)的统一可靠方案。
实现过程中总结的 7 类坑位
设计文档 dpad-navigation.md 详细记录了开发过程中总结的 7 类典型坑位,这里逐一展开:
坑 1:Android WebView 内建空间导航的焦点劫持
Android WebView 自带空间导航能力,会拦截 D-pad 方向键并在 tabIndex >= 0 的 DOM 元素之间移动焦点。这会导致焦点被"偷"到非交互性覆盖层元素上。Readest 的解法是为非交互覆盖元素显式设置 tabIndex={-1},将其移出 WebView 的焦点候选集。在源码中可以看到这一模式:HeaderBar 触发器(HeaderBar.tsx#L200)、FooterBar 触发器(FooterBar.tsx#L243)、SectionInfo(SectionInfo.tsx#L104)、进度条等元素均带 tabIndex={-1};工具栏容器本身(如 FootnotePopup.tsx#L705)也以 tabIndex={-1} 承载键盘监听。
坑 2:eventDispatcher.dispatchSync 的短路语义
事件分发器 src/utils/event.ts 的同步分发会按注册顺序(逆序)执行监听器,第一个返回 true 的监听器即终止后续调用。当多个处理器同时注册 native-key-down 时,FooterBar 的 Back 处理器可能先于 Reader 的处理器执行——因此两个处理器必须各自独立调用 blur(),不能指望"Reader 的处理器会兜底执行"。
坑 3:工具栏关闭时必须 blur
当 Back/Escape 关闭工具栏时,若不对当前聚焦按钮调用 blur(),document.activeElement 会一直停留在已隐藏的按钮上。由于 toggleToolbar 在 activeElement.tagName === 'BUTTON' 时跳过拦截,这个残留焦点会让下一次 Enter 键"失灵"(既不被拦截为工具栏切换,按钮又不可见无法点击)。因此 blur() 同时出现在 FooterBar 的 handleKeyDown(处理 Back 与 Escape)与 Reader 的 handleKeyDown 中。
坑 4:方向键必须 stopPropagation
方向键若不拦截会冒泡到 window,被 useShortcuts 当作翻页处理。工具栏容器 div 上的 keydown 处理器必须同时调用 e.stopPropagation() + e.preventDefault()。这一点已由 useSpatialNavigation.test.tsx 中的 pressKey 辅助函数与 stopPropagationCalled 断言覆盖验证。
坑 5:书架网格需要窗口级监听器
书架容器 keydown 处理器只在焦点位于容器内部时触发;从外部(如 header)进入网格需要单独的 window 级监听处理 ArrowDown(仅当焦点不在容器内时生效),这正是前述"从外部进入网格"的实现动机。
坑 6:工具栏自动聚焦的竞态
顶栏与底栏在 isVisible 同时变为 true 时会各自自动聚焦第一个按钮,最后一个执行的 effect 获胜。这是可接受的——用户可通过上/下方向键在两栏之间切换,不会造成功能损失。
坑 7:offsetParent 在 fixed 容器中恒为 null
移动端 .footer-bar 使用 position: fixed,其子按钮 offsetParent 全部为 null,基于 offsetParent 的可见性判断彻底失效。focus-probe 方案(尝试聚焦并检查 document.activeElement)是唯一可靠替代——这也是本文反复强调的核心技巧。
测试验证
阅读器工具栏导航由 useSpatialNavigation.test.tsx 提供覆盖,测试分三组:
- 自动聚焦:键盘激活时聚焦首个可用按钮;不可见时不聚焦;鼠标激活(无近期键盘事件)时不聚焦;
- 左/右导航:ArrowRight 聚焦下一按钮、ArrowLeft 聚焦上一按钮、到达首尾边界不越界、移动时调用
stopPropagation; - 上/下导航:从顶栏 ArrowDown 聚焦底栏首按钮、从底栏 ArrowUp 聚焦顶栏首按钮、调用
stopPropagation。
测试通过 _resetLastKeyboardTime() 重置模块级键盘时间戳、simulateKeyboardActivation() 派发 Enter 模拟键盘激活、fake timers 推进 150ms 等待自动聚焦,覆盖了本文描述的核心行为路径。
小结
Readest 的 D-pad 空间导航是一套"小而美"的工程实践:不依赖第三方库,用两个同名 Hook 分别处理工具栏线性导航与书架网格导航;以 focus-probe 技术统一解决各种隐藏方式下的可见性判定;通过 tabIndex={-1} 规避 WebView 焦点劫持;用 stopPropagation 化解与全局翻页快捷键的冲突。其 7 类坑位总结(见 dpad-navigation.md)对任何需要在 Android TV / 遥控器 / 键盘场景下实现焦点导航的应用都极具参考价值——尤其是"键盘事件经 window 统一收口、再由空间导航层与快捷键层协作分配"的整体思路,值得在类似项目中直接借鉴。