Back to Details

react-native-tv-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

React Native TV Best Practices

React Native TV 最佳实践

Overview

概述

TV-specific review guidance for React Native-backed apps on Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, and web-based TV targets such as Tizen or webOS.
Use this skill only for TV deltas: remote input, focus engines, 10-foot layout, platform packaging, playback/DRM, low-memory TV hardware, and TV accessibility. For ordinary React Native performance or architecture issues, use react-native-best-practices.
针对基于React Native的Apple TV、Android TV、Fire TV、Amazon Vega/Kepler以及基于网页的电视平台（如Tizen或webOS）应用的专属评审指南。
仅在涉及电视特有差异的场景下使用本技能：遥控器输入、焦点引擎、10英尺布局、平台打包、播放/DRM、低内存电视硬件以及电视可访问性。对于普通React Native性能或架构问题，请使用react-native-best-practices。

Skill Format

技能格式

Reference files are grouped by topic prefix:
  • focus-*
    : focus engines, focus guides, focus event performance
  • nav-*
    : D-pad navigation, Back/Menu behavior, keyboard/search input
  • design-*
    : 10-foot typography, layout, color, focus visibility
  • perf-*
    : startup, memory, lists, animation, and network constraints on TV hardware
  • video-*
    : playback architecture, DRM/protocol selection, debugging
  • a11y-*
    : TV accessibility implementation and audit checks
  • setup-*
    : stack detection, setup, architecture, cross-platform behavior
  • test-*
    and 
    release-*
    : test coverage, E2E, and CI/release workflows
参考文件按主题前缀分组：
  • focus-*
    ：焦点引擎、焦点引导、焦点事件性能
  • nav-*
    ：方向键导航、返回/菜单行为、键盘/搜索输入
  • design-*
    ：10英尺排版、布局、颜色、焦点可见性
  • perf-*
    ：电视硬件上的启动、内存、列表、动画及网络限制
  • video-*
    ：播放架构、DRM/协议选择、调试
  • a11y-*
    ：电视可访问性实现及审计检查
  • setup-*
    ：技术栈检测、配置、架构、跨平台行为
  • test-*
    和 
    release-*
    ：测试覆盖、端到端测试、CI/发布流程

When to Apply

适用场景

Apply this skill when the app targets a TV platform and the work involves:
  • Focus movement, visible focus, focus restoration, or remote/D-pad input
  • TV layout readability, overscan/safe areas, or 10-foot UI density
  • TV player controls, manifests, DRM, decoder support, or playback errors
  • Performance on low-memory TV hardware, especially with video or large carousels
  • TV accessibility with screen readers, captions, focus order, or remote-only interaction
  • Platform setup for 
    react-native-tvos
    , Expo TV, Amazon Vega/Kepler, Tizen, or webOS
当应用目标为电视平台且工作涉及以下内容时，应用本技能：
  • 焦点移动、焦点可见性、焦点恢复或遥控器/方向键输入
  • 电视布局可读性、过扫描/安全区域或10英尺UI密度
  • 电视播放器控件、清单、DRM、解码器支持或播放错误
  • 低内存电视硬件上的性能，尤其是涉及视频或大型轮播组件时
  • 带屏幕阅读器、字幕、焦点顺序或仅遥控器交互的电视可访问性
  • react-native-tvos
    、Expo TV、Amazon Vega/Kepler、Tizen或webOS的平台配置

Before You Start — Identify the TV Stack

开始前——识别电视技术栈

This skill covers several TV stacks. Detect which one the app targets before flagging setup issues — demanding 
react-native-tvos
, a tvOS Podfile, or an Android TV manifest on a Vega/Kepler or web-based TV app produces false positives.
StackHow to detectSetup expectations
react-native-tvos (Apple TV, Android TV, Fire TV)
"react-native": "npm:react-native-tvos@…"
in package.json		tvOS Podfile (
platform :tvos
); Android TV 
leanback
/
LEANBACK_LAUNCHER
manifest entries; TV emulator/simulator
Expo + react-native-tvosabove plus 
@react-native-tvos/config-tv
in app.json
EXPO_TV=1
prebuild; 
react-native-tvos
version must match the Expo SDK; not all Expo features/libraries are available on TV
Amazon Vega / KeplerVega/Kepler SDK & tooling (
@amazon-devices/*
deps, Kepler manifest); no 
react-native-tvos
Amazon's Vega/Kepler toolchain — 
react-native-tvos
, tvOS Podfile, and Android TV manifest do not apply
Web-based TV (Tizen, webOS)web bundler (Rsbuild/webpack) + platform packaging; spatial-nav libraryPlatform SDK packaging; 
@noriginmedia/norigin-spatial-navigation
for focus
The focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the setup/build expectations are stack-specific.
本技能覆盖多种电视技术栈。在标记配置问题前，先检测应用目标技术栈——在Vega/Kepler或网页端电视应用中要求使用
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清单文件均不适用
网页端电视（Tizen、webOS）使用网页打包工具（Rsbuild/webpack）+ 平台打包工具；包含空间导航库平台SDK打包；使用
@noriginmedia/norigin-spatial-navigation
处理焦点
焦点、10英尺设计、性能、可访问性及播放器指南适用于所有这些技术栈——仅配置/构建预期因技术栈而异。

Review Rules

评审规则

  • Resolve the target stack before setup advice.
  • Prefer natural focus order and focus guides before imperative focus calls or broad 
    nextFocus*
    maps.
  • Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.
  • Check readability, safe areas, and focus states at TV distance before tuning visual details.
  • Profile on the weakest supported TV device before reporting performance fixes as complete.
  • Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.
  • 给出配置建议前先明确目标技术栈。
  • 优先使用自然焦点顺序和焦点引导，而非强制焦点调用或宽泛的
    nextFocus*
    映射。
  • 将焦点丢失、焦点不可见及返回/菜单行为异常视为导航Bug。
  • 在调整视觉细节前，先检查电视距离下的可读性、安全区域和焦点状态。
  • 在报告性能修复完成前，先在最弱的支持电视设备上进行性能分析。
  • 按层级区分播放故障：清单请求、DRM许可证交换、解码器能力、播放器状态及React UI控件。

Priority-Ordered Guidelines

优先级排序指南

PriorityCategoryImpactPrefix
1Focus and D-pad navigationCRITICAL
focus-*
, 
nav-*
2List, animation, and input performanceCRITICAL
perf-*
3Playback and DRM failuresHIGH
video-*
410-foot readability and layoutHIGH
design-*
5TV accessibilityHIGH
a11y-*
6Stack setup, testing, and releaseMEDIUM
setup-*
, 
test-*
, 
release-*
优先级分类影响程度前缀
1焦点与方向键导航关键
focus-*
, 
nav-*
2列表、动画与输入性能关键
perf-*
3播放与DRM故障高
video-*
410英尺可读性与布局高
design-*
5电视可访问性高
a11y-*
6技术栈配置、测试与发布中
setup-*
, 
test-*
, 
release-*

Quick Reference

快速参考

  1. Detect the TV stack from package files, manifests, native folders, and platform tooling.
  2. Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.
  3. Confirm the focused element is always visible, reachable, and restored after modals/routes.
  4. Check playback failures from the network/DRM layer upward before changing React controls.
  5. Measure list, animation, memory, and startup work on the weakest supported TV target.
  1. 从包文件、清单文件、原生文件夹及平台工具中检测电视技术栈。
  2. 使用遥控器或方向键路径复现导航问题，而非基于鼠标/触摸的假设。
  3. 确认聚焦元素始终可见、可访问，且在模态框/路由切换后能恢复焦点。
  4. 在修改React控件前，先从网络/DRM层向上排查播放故障。
  5. 在最弱的支持电视目标设备上测试列表、动画、内存及启动性能。

References

参考资料

Focus and Navigation

焦点与导航

FileImpactDescription
focus-management.mdCRITICALFocus engines, focus guides, 
nextFocus*
, and focus restoration
focus-performance.mdCRITICALAvoiding frame drops from focus event handling
nav-directional.mdCRITICALDirectional navigation rules across TV platforms
nav-patterns.mdCRITICALGlobal/local navigation, modals, tabs, and Back behavior
nav-keyboard.mdMEDIUMSearch and text input with remotes
文件影响程度描述
focus-management.md关键焦点引擎、焦点引导、
nextFocus*
及焦点恢复
focus-performance.md关键避免焦点事件处理导致的掉帧
nav-directional.md关键跨电视平台的方向导航规则
nav-patterns.md关键全局/局部导航、模态框、标签页及返回行为
nav-keyboard.md中使用遥控器进行搜索和文本输入

Design

设计

FileImpactDescription
design-10foot.mdHIGH10-foot review heuristics
design-typography.mdHIGHTV type sizing and readability
design-layout.mdHIGHSafe areas, spacing, carousels, and focus room
design-color.mdMEDIUMContrast and TV display color constraints
文件影响程度描述
design-10foot.md高10英尺评审启发式规则
design-typography.md高电视字体大小与可读性
design-layout.md高安全区域、间距、轮播组件及焦点空间
design-color.md中对比度与电视显示颜色限制

Performance

性能

FileImpactDescription
perf-overview.mdHIGHTV performance targets and profiling order
perf-lists.mdCRITICALVirtualized rows and poster-heavy lists
perf-animations.mdCRITICALFocus and transition animation performance
perf-memory.mdHIGHLow-memory TV crashes and image/video pressure
perf-network.mdHIGHRemote input, request stalls, and network resilience
文件影响程度描述
perf-overview.md高电视性能目标与分析顺序
perf-lists.md关键虚拟化行与海报密集型列表
perf-animations.md关键焦点与过渡动画性能
perf-memory.md高低内存电视崩溃及图片/视频内存压力
perf-network.md高遥控器输入、请求停滞及网络韧性

Video, Accessibility, Setup, Testing

视频、可访问性、配置、测试

FileImpactDescription
video-streaming.mdHIGHTV platform protocol/DRM selection
video-players.mdHIGHPlayer choices and custom controls
video-debugging.mdHIGHManifest, DRM, codec, and playback debugging
a11y-overview.mdMEDIUMTV-specific accessibility differences
a11y-implementation.mdHIGHAccessible labels, roles, live regions, and focus
a11y-checklist.mdMEDIUMLaunch accessibility audit checklist
setup-getting-started.mdMEDIUM
react-native-tvos
and Expo TV setup
setup-cross-platform.mdMEDIUMPlatform detection and cross-platform caveats
setup-architecture.mdMEDIUMCode sharing and project structure
test-strategy.mdMEDIUMTV testing scope and coverage split
test-javascript.mdMEDIUMJS-level remote/focus test helpers
test-e2e.mdMEDIUMAppium and TV E2E coverage
release-cicd.mdMEDIUMCI, build fingerprinting, and release checks
文件影响程度描述
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、构建指纹及发布检查

Problem → Skill Mapping

问题→技能映射

SymptomStart Here
"Focus jumps to wrong element"focus-management.md → Debugging section
"App freezes when scrolling lists"perf-lists.md → Virtualization
"Animations stutter on Fire TV"perf-animations.md → Native driver
"Text too small on TV"design-typography.md → Minimum sizes
"Video won't play / DRM errors"video-streaming.md → DRM section
"Screen reader skips elements"a11y-implementation.md → Roles & labels
"Back button doesn't work right"nav-patterns.md → Back navigation
"Keyboard covers content"nav-keyboard.md → Built-in vs custom
"App takes forever to start"perf-overview.md → Startup time
"Images causing memory crashes"perf-memory.md → Image optimization
"CI pipeline takes hours"release-cicd.md → Fingerprinting
"How to share code across platforms"setup-architecture.md → Code sharing
症状起始参考文档
"焦点跳转到错误元素"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 → 代码共享

Security (TV-Specific)

安全（电视专属）

General dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:
  • Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.
通用依赖/输入安全规范适用于所有RN应用；以下是需要特别注意的电视专属差异：
  • 切勿在客户端代码中嵌入FairPlay/Widevine/PlayReady密钥——将许可证服务器视为信任边界，保持DRM令牌由服务器颁发。",