React Native TV 最佳實務 是做什麼的？
概述
針對 Apple TV、Android TV、Fire TV、Amazon Vega/Kepler 以及 Tizen 或 webOS 等基於網路的電視目標，提供 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 或基於網路的電視應用程式上要求 react-native-tvos、tvOS Podfile 或 Android TV 資訊清單，將導致誤判。
| 堆疊 | 如何檢測 | 設定期望 |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" 在 package.json 中 | tvOS Podfile (platform :tvos)；Android TV leanback/LEANBACK_LAUNCHER 資訊清單條目；電視模擬器 |
| Expo + react-native-tvos | 上述條件 加上 @react-native-tvos/config-tv 在 app.json 中 | EXPO_TV=1 prebuild；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 英尺設計、效能、無障礙性和播放器指南適用於所有這些堆疊——只有設定/建置期望是堆疊特定的。
審查規則
- 在提出設定建議之前，先確定目標堆疊。
- 優先使用自然的焦點順序和焦點引導，而不是命令式的焦點呼叫或廣泛的
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 → Native driver |
| "電視上的文字太小" | 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 權杖由伺服器發放。