Bonnes pratiques React Native TV
Vue d'ensemble
Conseils d'examen spécifiques à la TV pour les applications soutenues par React Native sur Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, et cibles TV basées sur le web comme Tizen ou webOS.
Utilisez cette compétence uniquement pour les différences TV : entrée distante, moteurs de focus, disposition 10-pieds, empaquetage de plateforme, lecture/DRM, matériel TV à faible mémoire, et accessibilité TV. Pour les problèmes ordinaires de performance ou d'architecture React Native, utilisez react-native-best-practices.
Format de la compétence
Les fichiers de référence sont groupés par préfixe de sujet :
focus-*: moteurs de focus, guides de focus, performance des événements de focusnav-*: navigation D-pad, comportement Retour/Menu, saisie clavier/recherchedesign-*: typographie 10-pieds, disposition, couleur, visibilité du focusperf-*: démarrage, mémoire, listes, animation, et contraintes de réseau sur matériel TVvideo-*: architecture de lecture, sélection DRM/protocole, débogagea11y-*: implémentation et vérifications d'audit d'accessibilité TVsetup-*: détection de pile, configuration, architecture, comportement multi-plateformetest-*etrelease-*: couverture de test, E2E, et workflows CI/release
Quand l'appliquer
Appliquez cette compétence quand l'app vise une plateforme TV et que le travail implique :
- Mouvement du focus, visibilité du focus, restauration du focus, ou entrée distante/D-pad
- Lisibilité de la disposition TV, zones de overscan/sûres, ou densité UI 10-pieds
- Contrôles de lecteur TV, manifests, DRM, support du décodeur, ou erreurs de lecture
- Performance sur matériel TV à faible mémoire, surtout avec vidéo ou grand carousels
- Accessibilité TV avec lecteurs d'écran, sous-titres, ordre du focus, ou interaction distance-seulement
- Configuration de plateforme pour
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen, ou webOS
Avant de commencer — Identifier la pile TV
Cette compétence couvre plusieurs piles TV. Détectez laquelle l'app vise avant de signaler des problèmes de configuration — exiger react-native-tvos, un Podfile tvOS, ou un manifest Android TV sur une app Vega/Kepler ou TV basée sur le web produit des faux positifs.
| Pile | Comment détecter | Attentes de configuration |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" dans package.json |
Podfile tvOS (platform :tvos); entrées manifest Android TV leanback/LEANBACK_LAUNCHER; émulateur/simulateur TV |
| Expo + react-native-tvos | ci-dessus plus @react-native-tvos/config-tv dans app.json |
prebuild EXPO_TV=1; la version react-native-tvos doit correspondre au SDK Expo; pas toutes les features/librairies Expo sont disponibles sur TV |
| Amazon Vega / Kepler | SDK & outillage Vega/Kepler (@amazon-devices/* deps, manifest Kepler); pas de react-native-tvos |
Chaîne d'outils Vega/Kepler d'Amazon — react-native-tvos, Podfile tvOS, et manifest Android TV ne s'appliquent pas |
| Web-based TV (Tizen, webOS) | bundler web (Rsbuild/webpack) + empaquetage de plateforme; librairie spatial-nav | Empaquetage SDK de plateforme; @noriginmedia/norigin-spatial-navigation pour le focus |
Le focus, la conception 10-pieds, la performance, l'accessibilité, et la guidance du lecteur s'appliquent à travers tous ceux-ci — seules les attentes de configuration/construction sont spécifiques à la pile.
Règles de révision
- Résolvez la pile cible avant les conseils de configuration.
- Préférez l'ordre naturel du focus et les guides de focus avant les appels de focus impératifs ou les cartes
nextFocus*larges. - Traitez la perte de focus, le focus invisible, et le comportement Retour/Menu cassé comme des bugs de navigation.
- Vérifiez la lisibilité, les zones sûres, et les états du focus à distance TV avant d'affiner les détails visuels.
- Profilez sur l'appareil TV le plus faible supporté avant de signaler les correctifs de performance comme complets.
- Séparez les échecs de lecture par couche : demande de manifest, échange de licence DRM, capacité du décodeur, état du lecteur, et contrôles UI React.
Directives ordonnées par priorité
| Priorité | Catégorie | Impact | Préfixe |
|---|---|---|---|
| 1 | Focus et navigation D-pad | CRITIQUE | focus-*, nav-* |
| 2 | Liste, animation, et performance d'entrée | CRITIQUE | perf-* |
| 3 | Échecs de lecture et DRM | ÉLEVÉ | video-* |
| 4 | Lisibilité et disposition 10-pieds | ÉLEVÉ | design-* |
| 5 | Accessibilité TV | ÉLEVÉ | a11y-* |
| 6 | Configuration de pile, test, et release | MOYEN | setup-*, test-*, release-* |
Référence rapide
- Détectez la pile TV à partir des fichiers de package, manifests, dossiers natifs, et outillage de plateforme.
- Reproduisez la navigation avec le chemin distance ou D-pad, pas les hypothèses souris/tactile.
- Confirmez que l'élément focalisé est toujours visible, accessible, et restauré après modales/routes.
- Vérifiez les échecs de lecture depuis la couche réseau/DRM vers le haut avant de modifier les contrôles React.
- Mesurez la liste, animation, mémoire, et travail de démarrage sur la cible TV la plus faible supportée.
Références
Focus et Navigation
| Fichier | Impact | Description |
|---|---|---|
| focus-management.md | CRITIQUE | Moteurs de focus, guides de focus, nextFocus*, et restauration du focus |
| focus-performance.md | CRITIQUE | Éviter les chutes d'images du traitement d'événements de focus |
| nav-directional.md | CRITIQUE | Règles de navigation directionnelle sur plateformes TV |
| nav-patterns.md | CRITIQUE | Navigation globale/locale, modales, onglets, et comportement Retour |
| nav-keyboard.md | MOYEN | Recherche et saisie de texte avec distances |
Conception
| Fichier | Impact | Description |
|---|---|---|
| design-10foot.md | ÉLEVÉ | Heuristiques d'examen 10-pieds |
| design-typography.md | ÉLEVÉ | Dimensionnement et lisibilité de type TV |
| design-layout.md | ÉLEVÉ | Zones sûres, espacement, carousels, et espace du focus |
| design-color.md | MOYEN | Contraste et contraintes de couleur d'affichage TV |
Performance
| Fichier | Impact | Description |
|---|---|---|
| perf-overview.md | ÉLEVÉ | Cibles de performance TV et ordre de profilage |
| perf-lists.md | CRITIQUE | Lignes virtualisées et listes chargées de posters |
| perf-animations.md | CRITIQUE | Performance d'animation de focus et de transition |
| perf-memory.md | ÉLEVÉ | Crashes TV à faible mémoire et pression image/vidéo |
| perf-network.md | ÉLEVÉ | Entrée distance, blocages de requête, et résilience réseau |
Vidéo, Accessibilité, Configuration, Test
| Fichier | Impact | Description |
|---|---|---|
| video-streaming.md | ÉLEVÉ | Sélection protocole/DRM de plateforme TV |
| video-players.md | ÉLEVÉ | Choix de lecteur et contrôles personnalisés |
| video-debugging.md | ÉLEVÉ | Manifest, DRM, codec, et débogage de lecture |
| a11y-overview.md | MOYEN | Différences d'accessibilité spécifiques à TV |
| a11y-implementation.md | ÉLEVÉ | Labels accessibles, rôles, régions dynamiques, et focus |
| a11y-checklist.md | MOYEN | Liste de vérification d'audit d'accessibilité au lancement |
| setup-getting-started.md | MOYEN | Configuration react-native-tvos et Expo TV |
| setup-cross-platform.md | MOYEN | Détection de plateforme et réserves multi-plateforme |
| setup-architecture.md | MOYEN | Partage de code et structure de projet |
| test-strategy.md | MOYEN | Portée de test TV et split de couverture |
| test-javascript.md | MOYEN | Aides de test distance/focus au niveau JS |
| test-e2e.md | MOYEN | Couverture Appium et E2E TV |
| release-cicd.md | MOYEN | CI, fingerprinting de build, et vérifications de release |
Mappage Problème → Compétence
| Symptôme | Commencer ici |
|---|---|
| « Le focus saute au mauvais élément » | focus-management.md → Section Débogage |
| « L'app gèle quand on scroll les listes » | perf-lists.md → Virtualisation |
| « Les animations saccadent sur Fire TV » | perf-animations.md → Native driver |
| « Le texte trop petit sur TV » | design-typography.md → Tailles minimales |
| « La vidéo ne joue pas / Erreurs DRM » | video-streaming.md → Section DRM |
| « Le lecteur d'écran saute les éléments » | a11y-implementation.md → Rôles & labels |
| « Le bouton Retour ne fonctionne pas bien » | nav-patterns.md → Navigation Retour |
| « Le clavier couvre le contenu » | nav-keyboard.md → Intégré vs personnalisé |
| « L'app met une éternité à démarrer » | perf-overview.md → Temps de démarrage |
| « Les images causent des crashes mémoire » | perf-memory.md → Optimisation d'image |
| « Le pipeline CI prend des heures » | release-cicd.md → Fingerprinting |
| « Comment partager du code entre plateformes » | setup-architecture.md → Partage de code |
Sécurité (Spécifique à TV)
L'hygiène générale de dépendance/entrée s'applique comme dans n'importe quelle app RN ; les différences spécifiques à TV qui valent le coup d'être signalées :
- Ne jamais intégrer les clés FairPlay/Widevine/PlayReady dans le code client — traitez le serveur de licence comme la limite de confiance et gardez les tokens DRM émis par le serveur.