react-native-tv-best-practices

React Native TV 最佳实践

概述

针对由 React Native 驱动、运行于 Apple TV、Android TV、Fire TV、Amazon Vega/Kepler 以及 Tizen 或 webOS 等基于 Web 的电视平台的应用的电视专属审查指南。

仅在涉及电视特有差异时使用此技能：遥控器输入、焦点引擎、10 英尺布局、平台打包、播放/DRM、低内存电视硬件和电视无障碍功能。对于常规 React Native 性能或架构问题，请使用 react-native-best-practices。

技能格式

参考文件按主题前缀分组：

• focus-*：焦点引擎、焦点引导、焦点事件性能
• nav-*：D-pad 导航、Back/Menu 行为、键盘/搜索输入
• design-*：10 英尺排版、布局、颜色、焦点可见性
• perf-*：电视硬件上的启动、内存、列表、动画和网络限制
• video-*：播放架构、DRM/协议选择、调试
• a11y-*：电视无障碍功能的实现和审查检查
• setup-*：技术栈检测、设置、架构、跨平台行为
• test-* 和 release-*：测试覆盖、E2E 和 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）+ 平台打包；空间导航库	平台 SDK 打包；用于焦点处理的 @noriginmedia/norigin-spatial-navigation

焦点、10 英尺设计、性能、无障碍功能和播放器指南适用于所有这些技术栈——只有设置/构建要求因技术栈而异。

审查规则

• 在提供设置建议前，先确定目标技术栈。
• 优先采用自然的焦点顺序，并优先使用焦点指南，而不是命令式焦点调用或宽泛的 nextFocus* 映射。
• 将焦点丢失、焦点不可见以及返回键／菜单键行为异常视为导航问题。
• 在调整视觉细节前，先从电视观看距离检查可读性、安全区域和焦点状态。
• 在报告性能问题已修复前，先在支持设备中性能最弱的电视上进行分析。
• 按层区分播放故障：清单请求、DRM 许可证交换、解码器能力、播放器状态和 React UI 控件。

按优先级排序的指南

优先级	类别	影响	前缀
1	焦点和方向键导航	严重	focus-*, nav-*
2	列表、动画和输入性能	严重	perf-*
3	播放和 DRM 故障	高	video-*
4	远距离可读性和布局	高	design-*
5	电视无障碍功能	高	a11y-*
6	技术栈设置、测试和发布	中	setup-*, test-*, release-*

快速参考

1. 根据包文件、清单、原生文件夹和平台工具检测电视技术栈。
2. 使用遥控器或方向键操作路径复现导航，不要假设用户使用鼠标或触摸操作。
3. 确认焦点元素始终可见、可到达，并且在模态框／路由切换后能够恢复。
4. 更改 React 控件前，先从网络／DRM 层开始向上检查播放故障。
5. 在支持设备中性能最弱的电视上测量列表、动画、内存和启动相关工作。

参考资料

焦点和导航

文件	影响	描述
focus-management.md	严重	焦点引擎、焦点指南、nextFocus* 和焦点恢复
focus-performance.md	严重	避免焦点事件处理导致帧丢失
nav-directional.md	严重	各电视平台的方向导航规则
nav-patterns.md	严重	全局／局部导航、模态框、标签页和返回行为
nav-keyboard.md	中	使用遥控器进行搜索和文本输入

设计

文件	影响	描述
design-10foot.md	高	远距离审查的启发式原则
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	HIGH	电视平台协议／DRM 选择
video-players.md	HIGH	播放器选择和自定义控件
video-debugging.md	HIGH	清单、DRM、编解码器和播放调试
a11y-overview.md	MEDIUM	电视特有的无障碍差异
a11y-implementation.md	HIGH	无障碍标签、角色、实时区域和焦点
a11y-checklist.md	MEDIUM	发布前无障碍审核清单
setup-getting-started.md	MEDIUM	react-native-tvos 和 Expo TV 设置
setup-cross-platform.md	MEDIUM	平台检测和跨平台注意事项
setup-architecture.md	MEDIUM	代码共享和项目结构
test-strategy.md	MEDIUM	电视测试范围和覆盖划分
test-javascript.md	MEDIUM	JS 级别的遥控器／焦点测试辅助工具
test-e2e.md	MEDIUM	Appium 和电视端 E2E 覆盖
release-cicd.md	MEDIUM	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 → 内置与自定义
“应用启动要等很久”	perf-overview.md → 启动时间
“图像导致内存崩溃”	perf-memory.md → 图像优化
“CI 流水线需要好几个小时”	release-cicd.md → 指纹
“如何跨平台共享代码”	setup-architecture.md → 代码共享

安全（电视特有）

与任何 RN 应用一样，应注意依赖项和输入的卫生；值得特别指出的电视端差异：

• 切勿将 FairPlay／Widevine／PlayReady 密钥嵌入客户端代码——应将许可证服务视为信任边界，并确保 DRM 令牌由服务器签发。