react-native-tv-best-practices

React Native TV のベストプラクティス

概要

Apple TV、Android TV、Fire TV、Amazon Vega／Kepler、Tizen や webOS などの Web ベースの TV ターゲットで動作する、React Native ベースのアプリ向けの TV 固有のレビューガイダンスです。

このスキルは TV 固有の差分に限って使用してください。対象は、リモート入力、フォーカスエンジン、10 フィート UI、プラットフォームのパッケージング、再生／DRM、低メモリの TV ハードウェア、TV のアクセシビリティです。一般的な React Native のパフォーマンスやアーキテクチャの問題については、react-native-best-practices を使用してください。

スキルの形式

参照ファイルは、トピック別のプレフィックスでグループ化されています。

• focus-*：フォーカスエンジン、フォーカスガイド、フォーカスイベントのパフォーマンス
• nav-*：D-pad ナビゲーション、戻る／メニューの動作、キーボード／検索入力
• design-*：10 フィート向けのタイポグラフィ、レイアウト、色、フォーカスの視認性
• perf-*：TV ハードウェア上の起動、メモリ、リスト、アニメーション、ネットワークの制約
• video-*：再生アーキテクチャ、DRM／プロトコルの選択、デバッグ
• a11y-*：TV のアクセシビリティ実装と監査チェック
• setup-*：スタックの検出、セットアップ、アーキテクチャ、クロスプラットフォームの動作
• test-* および release-*：テストカバレッジ、E2E、CI／リリースのワークフロー

適用する場面

アプリが TV プラットフォームを対象とし、次の作業を行う場合にこのスキルを適用してください。

• フォーカス移動、フォーカスの視認性、フォーカスの復元、リモート／D-pad 入力
• TV レイアウトの読みやすさ、オーバースキャン／セーフエリア、10 フィート UI の情報密度
• TV プレーヤーのコントロール、マニフェスト、DRM、デコーダーのサポート、再生エラー
• 低メモリの TV ハードウェアでのパフォーマンス。特に、動画や大きなカルーセルがある場合
• スクリーンリーダー、字幕、フォーカス順序、リモコンのみでの操作に関する TV アクセシビリティ
• react-native-tvos、Expo TV、Amazon Vega／Kepler、Tizen、webOS のプラットフォームセットアップ

始める前に — TV スタックを特定する

このスキルは複数の TV スタックを対象としています。セットアップの問題を指摘する前に、アプリがどのスタックを対象としているか検出してください。 Vega／Kepler や Web ベースの TV アプリに 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 マニフェストエントリー；TV エミュレーター／シミュレーター
Expo + react-native-tvos	上記に加えて、app.json に @react-native-tvos/config-tv	EXPO_TV=1 での prebuild；react-native-tvos のバージョンは Expo SDK と一致している必要があります；TV では利用できない Expo の機能／ライブラリもあります
Amazon Vega／Kepler	Vega／Kepler SDK とツール（@amazon-devices/* の依存関係、Kepler マニフェスト）；react-native-tvos はなし	Amazon の Vega／Kepler ツールチェーン。react-native-tvos、tvOS Podfile、Android TV マニフェストは適用されません
Web ベースの TV（Tizen、webOS）	Web バンドラー（Rsbuild／webpack）とプラットフォームパッケージング；空間ナビゲーションライブラリ	プラットフォーム SDK によるパッケージング；フォーカス制御には @noriginmedia/norigin-spatial-navigation を使用

フォーカス、10 フィート向けデザイン、パフォーマンス、アクセシビリティ、プレーヤーに関するガイダンスは、これらすべてに適用されます。スタックごとに異なるのは、セットアップ／ビルドの要件だけです。

レビュールール

• セットアップに関するアドバイスの前に、対象のスタックを特定します。
• 命令的なフォーカス呼び出しや広範な nextFocus* マップよりも、自然なフォーカス順序とフォーカスガイドを優先します。
• フォーカスの喪失、フォーカスが見えない状態、戻る／メニュー操作の不具合は、ナビゲーションのバグとして扱います。
• 視覚的な細部を調整する前に、テレビから離れた距離での読みやすさ、安全領域、フォーカス状態を確認します。
• パフォーマンス改善の完了を報告する前に、サポート対象の中で最も性能の低いテレビデバイスでプロファイリングします。
• 再生の失敗は、マニフェスト要求、DRMライセンス交換、デコーダーの機能、プレーヤーの状態、React UI コントロールの各レイヤーに分けて調査します。

優先度順のガイドライン

優先度	カテゴリー	影響度	プレフィックス
1	フォーカスとDパッドナビゲーション	CRITICAL	focus-*, nav-*
2	リスト、アニメーション、入力のパフォーマンス	CRITICAL	perf-*
3	再生とDRMの失敗	HIGH	video-*
4	画面から離れた距離での読みやすさとレイアウト	HIGH	design-*
5	テレビのアクセシビリティ	HIGH	a11y-*
6	スタックのセットアップ、テスト、リリース	MEDIUM	setup-*, test-*, release-*

クイックリファレンス

1. パッケージファイル、マニフェスト、ネイティブフォルダー、プラットフォームツールからテレビのスタックを特定します。
2. マウスやタッチ操作を前提とせず、リモコンまたはDパッドでの操作経路を使ってナビゲーションを再現します。
3. フォーカスされた要素が常に表示され、到達可能であり、モーダルやルートの切り替え後に復元されることを確認します。
4. React コントロールを変更する前に、ネットワーク／DRMレイヤーから上位に向かって再生の失敗を確認します。
5. サポート対象の中で最も性能の低いテレビを使って、リスト、アニメーション、メモリー、起動時の処理を測定します。

参考資料

フォーカスとナビゲーション

ファイル	影響度	説明
focus-management.md	CRITICAL	フォーカスエンジン、フォーカスガイド、nextFocus*、フォーカスの復元
focus-performance.md	CRITICAL	フォーカスイベント処理によるフレーム落ちの回避
nav-directional.md	CRITICAL	テレビプラットフォーム全般における方向ナビゲーションのルール
nav-patterns.md	CRITICAL	グローバル／ローカルナビゲーション、モーダル、タブ、戻る操作
nav-keyboard.md	MEDIUM	リモコンでの検索とテキスト入力

デザイン

ファイル	影響度	説明
design-10foot.md	HIGH	画面から離れた距離でのレビューのヒューリスティクス
design-typography.md	HIGH	テレビ向けの文字サイズと読みやすさ
design-layout.md	HIGH	安全領域、間隔、カルーセル、フォーカス用の余白
design-color.md	MEDIUM	コントラストとテレビディスプレイの色に関する制約

パフォーマンス

ファイル	影響度	説明
perf-overview.md	HIGH	テレビのパフォーマンス目標とプロファイリングの順序
perf-lists.md	CRITICAL	仮想化された行とポスター画像の多いリスト
perf-animations.md	CRITICAL	フォーカスとトランジションのアニメーション性能
perf-memory.md	HIGH	メモリーの少ないテレビでのクラッシュと画像／動画による負荷
perf-network.md	HIGH	リモート入力、リクエストの停止、ネットワークの耐障害性

動画、アクセシビリティ、セットアップ、テスト

ファイル	影響度	説明
video-streaming.md	HIGH	TV プラットフォームのプロトコル／DRM の選択
video-players.md	HIGH	プレーヤーの選択肢とカスタムコントロール
video-debugging.md	HIGH	マニフェスト、DRM、コーデック、再生のデバッグ
a11y-overview.md	MEDIUM	TV 固有のアクセシビリティの違い
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	TV テストの範囲とカバレッジの分担
test-javascript.md	MEDIUM	JS レベルのリモート／フォーカステストヘルパー
test-e2e.md	MEDIUM	Appium と TV の E2E カバレッジ
release-cicd.md	MEDIUM	CI、ビルドフィンガープリント、リリースチェック

問題 → スキルの対応表

症状	まず確認する場所
"フォーカスが誤った要素に移動する"	focus-management.md → デバッグセクション
"リストをスクロールするとアプリがフリーズする"	perf-lists.md → 仮想化
"Fire TV でアニメーションがカクつく"	perf-animations.md → ネイティブドライバー
"TV で文字が小さすぎる"	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 → コード共有

セキュリティ（TV 固有）

一般的な依存関係／入力の衛生管理は、他の RN アプリと同様に適用されます。TV 固有の違いとして、特に注意すべき点は次のとおりです。

• FairPlay／Widevine／PlayReady のキーをクライアントコードに埋め込まないでください。ライセンスサーバーを信頼境界として扱い、DRM トークンはサーバーから発行してください。