React Native TV 最佳实践
概述
针对 Apple TV、Android TV、Fire TV、Amazon Vega/Kepler 以及 Tizen 或 webOS 等 Web 电视目标的 React Native 应用的电视特定审查指导。
仅在涉及电视差异时使用此技能：遥控输入、焦点引擎、10 英尺布局、平台打包、播放/DRM、低内存电视硬件以及电视可访问性。对于普通的 React Native 性能或架构问题，请使用 react-native-best-practices。
技能格式
参考文件按主题前缀分组：
focus-*：焦点引擎、焦点指南、焦点事件性能nav-*：D-pad 导航、返回/菜单行为、键盘/搜索输入design-*：10 英尺排版、布局、色彩、焦点可见性perf-*：启动、内存、列表、动画以及在电视硬件上的网络约束video-*：播放架构、DRM/协议选择、调试a11y-*：电视可访问性实现和审计检查setup-*：堆栈检测、设置、架构、跨平台行为test-*和release-*：测试覆盖率、端到端测试以及 CI/发布工作流
何时应用
当应用针对电视平台且工作涉及以下内容时，应用此技能：
- 焦点移动、可见焦点、焦点恢复或遥控/D-pad 输入
- 电视布局可读性、过扫描/安全区域或 10 英尺 UI 密度
- 电视播放器控件、清单、DRM、解码器支持或播放错误
- 低内存电视硬件上的性能，尤其是涉及视频或大型轮播时
- 使用屏幕阅读器、字幕、焦点顺序或仅遥控交互的电视可访问性
react-native-tvos、Expo TV、Amazon Vega/Kepler、Tizen 或 webOS 的平台设置
开始前 — 识别电视堆栈
本技能涵盖多个电视堆栈。在标记设置问题前，先检测应用针对的是哪个堆栈 — 在 Vega/Kepler 或基于 Web 的电视应用上要求 react-native-tvos、tvOS Podfile 或 Android TV 清单会产生误报。
| 堆栈 | 如何检测 | 设置期望 |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | 在 package.json 中 "react-native": "npm:react-native-tvos@…" | tvOS Podfile (platform :tvos)；Android TV leanback/LEANBACK_LAUNCHER 清单条目；电视模拟器/仿真器 |
| Expo + react-native-tvos | 以上条件 加上 在 app.json 中的 @react-native-tvos/config-tv | EXPO_TV=1 预构建；react-native-tvos 版本必须与 Expo SDK 匹配；并非所有 Expo 特性/库在电视上可用 |
| Amazon Vega / Kepler | Vega/Kepler SDK 和工具链（@amazon-devices/* 依赖、Kepler 清单）；不包含 react-native-tvos | Amazon 的 Vega/Kepler 工具链 — react-native-tvos、tvOS Podfile 和 Android TV 清单 不适用 |
| 基于 Web 的电视 (Tizen, webOS) | Web 打包工具（Rsbuild/webpack）+ 平台打包；spatial-nav 库 | 平台 SDK 打包；使用 @noriginmedia/norigin-spatial-navigation 处理焦点 |
焦点、10 英尺设计、性能、可访问性和播放器指导适用于所有这些堆栈 — 只有 设置/构建 期望是堆栈特定的。
审查规则
- 在给出设置建议前，先确定目标堆栈。
- 优先使用自然焦点顺序和焦点指南，而不是命令式焦点调用或广泛的
nextFocus*映射。 - 将焦点丢失、焦点不可见以及返回/菜单行为异常视为导航错误。
- 在调整视觉细节前，先检查电视距离下的可读性、安全区域和焦点状态。
- 在报告性能修复完成前，先在支持的最弱电视设备上进行性能分析。
- 按层级分离播放失败：清单请求、DRM 许可证交换、解码器能力、播放器状态和 React UI 控件。
优先级排序指南
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 焦点和 D-pad 导航 | 关键 | focus-*、nav-* |
| 2 | 列表、动画和输入性能 | 关键 | perf-* |
| 3 | 播放和 DRM 失败 | 高 | video-* |
| 4 | 10 英尺可读性和布局 | 高 | design-* |
| 5 | 电视可访问性 | 高 | a11y-* |
| 6 | 堆栈设置、测试和发布 | 中 | setup-*、test-*、release-* |
快速参考
- 从包文件、清单、原生文件夹和平台工具中检测电视堆栈。
- 使用遥控或 D-pad 路径（而非鼠标/触摸假设）复现导航。
- 确认焦点元素始终可见、可到达，并在模态框/路由后恢复。
- 在更改 React 控件之前，先从网络/DRM 层向上检查播放失败。
- 在支持的最弱电视目标上测量列表、动画、内存和启动工作。
参考
焦点和导航
| 文件 | 影响 | 描述 |
|---|---|---|
| focus-management.md | 关键 | 焦点引擎、焦点指南、nextFocus* 和焦点恢复 |
| focus-performance.md | 关键 | 避免因焦点事件处理导致的帧丢失 |
| nav-directional.md | 关键 | 跨电视平台的定向导航规则 |
| nav-patterns.md | 关键 | 全局/局部导航、模态框、选项卡和返回行为 |
| nav-keyboard.md | 中 | 使用遥控器进行搜索和文本输入 |
设计
| 文件 | 影响 | 描述 |
|---|---|---|
| design-10foot.md | 高 | 10 英尺审查启发式方法 |
| design-typography.md | 高 | 电视字体大小和可读性 |
| design-layout.md | 高 | 安全区域、间距、轮播和焦点空间 |
| design-color.md | 中 | 对比度和电视显示色彩约束 |
性能
| 文件 | 影响 | 描述 |
|---|---|---|
| perf-overview.md | 高 | 电视性能目标和性能分析顺序 |
| perf-lists.md | 关键 | 虚拟化行和海报密集型列表 |
| perf-animations.md | 关键 | 焦点和过渡动画性能 |
| perf-memory.md | 高 | 低内存电视崩溃和图像/视频压力 |
| perf-network.md | 高 | 遥控输入、请求停滞和网络弹性 |
视频、可访问性、设置、测试
| 文件 | 影响 | 描述 |
|---|---|---|
| video-streaming.md | 高 | 电视平台协议/DRM 选择 |
| video-players.md | 高 | 播放器选择和自定义控件 |
| video-debugging.md | 高 | 清单、DRM、编解码器和播放调试 |
| a11y-overview.md | 中 | 电视特定的可访问性差异 |
| a11y-implementation.md | 高 | 可访问标签、角色、活动区域和焦点 |
| a11y-checklist.md | 中 | 发布可访问性审计清单 |
| setup-getting-started.md | 中 | react-native-tvos 和 Expo TV 设置 |
| setup-cross-platform.md | 中 | 平台检测和跨平台注意事项 |
| setup-architecture.md | 中 | 代码共享和项目结构 |
| test-strategy.md | 中 | 电视测试范围和覆盖率划分 |
| test-javascript.md | 中 | JS 层遥控/焦点测试辅助工具 |
| test-e2e.md | 中 | Appium 和电视端到端测试覆盖率 |
| release-cicd.md | 中 | CI、构建指纹识别和发布检查 |
问题 → 技能映射
| 症状 | 从这里开始 |
|---|---|
| "焦点跳到错误元素" | focus-management.md → 调试部分 |
| "滚动列表时应用卡死" | perf-lists.md → 虚拟化 |
| "Fire TV 上动画卡顿" | perf-animations.md → 原生驱动 |
| "电视上文字太小" | design-typography.md → 最小尺寸 |
| "视频无法播放 / DRM 错误" | video-streaming.md → DRM 部分 |
| "屏幕阅读器跳过元素" | a11y-implementation.md → 角色和标签 |
| "返回按钮工作不正常" | nav-patterns.md → 返回导航 |
| "键盘遮挡内容" | nav-keyboard.md → 内置 vs 自定义 |
| "应用启动非常慢" | perf-overview.md → 启动时间 |
| "图像导致内存崩溃" | perf-memory.md → 图像优化 |
| "CI 流水线需要数小时" | release-cicd.md → 指纹识别 |
| "如何在平台间共享代码" | setup-architecture.md → 代码共享 |
安全（电视特定）
与任何 RN 应用一样，通用的依赖/输入卫生规则适用；以下是值得指出的电视特定差异：
- 切勿将 FairPlay/Widevine/PlayReady 密钥嵌入客户端代码 — 将许可证服务器视为信任边界，并保持 DRM 令牌由服务器颁发。