React Native TV Bonnes Pratiques
Aperçu
Guide de revue spécifique aux téléviseurs pour les applications basées sur React Native sur Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, et les cibles TV web telles que Tizen ou webOS.
Utilisez cette compétence uniquement pour les spécificités TV : saisie à distance, moteurs de focus, mise en page 10 pieds, packaging de plateforme, lecture/DRM, matériel TV à mémoire limitée, et accessibilité TV. Pour les problèmes ordinaires de performances ou d'architecture React Native, utilisez react-native-best-practices.
Format de la compétence
Les fichiers de référence sont regroupés par préfixe de sujet :
focus-*: moteurs de focus, guides de focus, performance des événements de focusnav-*: navigation au D-pad, comportement Retour/Menu, saisie clavier/recherchedesign-*: typographie 10 pieds, mise en page, couleur, visibilité du focusperf-*: démarrage, mémoire, listes, animation et contraintes réseau sur matériel TVvideo-*: architecture de lecture, sélection DRM/protocole, débogagea11y-*: implémentation et audit de l'accessibilité TVsetup-*: détection de pile, configuration, architecture, comportement multiplateformetest-*etrelease-*: couverture de test, E2E, et workflows CI/livraison
Quand l'appliquer
Appliquez cette compétence lorsque l'application cible une plateforme TV et que le travail implique :
- Mouvement de focus, focus visible, restauration de focus, ou saisie à distance/D-pad
- Lisibilité de la mise en page TV, zones de surbalayage/sécurisées, ou densité d'interface 10 pieds
- Contrôles de lecteur TV, manifests, DRM, support de décodeur, ou erreurs de lecture
- Performances sur matériel TV à mémoire limitée, surtout avec vidéo ou grands carrousels
- Accessibilité TV avec lecteurs d'écran, sous-titres, ordre de focus, ou interaction uniquement par télécommande
- Configuration de plateforme pour
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen, ou webOS
Avant de commencer — Identifiez la pile TV
Cette compétence couvre plusieurs piles TV. Détectez celle que l'application cible avant de signaler des problèmes de configuration — exiger react-native-tvos, un Podfile tvOS ou un manifest Android TV sur une application Vega/Kepler ou web TV 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 de manifest Android TV leanback/LEANBACK_LAUNCHER ; émulateur/simulateur TV |
| Expo + react-native-tvos | ci-dessus plus @react-native-tvos/config-tv dans app.json | EXPO_TV=1 prebuild ; la version de react-native-tvos doit correspondre au SDK Expo ; toutes les fonctionnalités/bibliothèques Expo ne sont pas disponibles sur TV |
| Amazon Vega / Kepler | SDK & outils Vega/Kepler (dépendances @amazon-devices/*, manifest Kepler) ; pas de react-native-tvos | Chaîne d'outils Amazon Vega/Kepler — react-native-tvos, Podfile tvOS et manifest Android TV ne s'appliquent pas |
| Web TV (Tizen, webOS) | Bundler web (Rsbuild/webpack) + packaging de plateforme ; bibliothèque spatial-nav | Packaging SDK de plateforme ; @noriginmedia/norigin-spatial-navigation pour le focus |
Les conseils sur le focus, le design 10 pieds, les performances, l'accessibilité et le lecteur s'appliquent à toutes ces piles — seules les attentes de configuration/build sont spécifiques à la pile.
Règles de revue
- Résolvez la pile cible avant de donner des conseils de configuration.
- Préférez l'ordre de focus naturel et les guides de focus avant les appels de focus impératifs ou les grandes cartes
nextFocus*. - Considérez la perte de focus, le focus invisible et le comportement cassé de Retour/Menu comme des bugs de navigation.
- Vérifiez la lisibilité, les zones sécurisées et les états de focus à distance TV avant d'ajuster les détails visuels.
- Profilez sur l'appareil TV le plus faible pris en charge avant de déclarer les correctifs de performances comme terminés.
- Séparez les échecs de lecture par couche : requête de manifest, échange de licence DRM, capacité du décodeur, état du lecteur et contrôles d'interface React.
Directives par ordre de priorité
| Priorité | Catégorie | Impact | Préfixe |
|---|---|---|---|
| 1 | Focus et navigation au D-pad | CRITIQUE | focus-*, nav-* |
| 2 | Performances des listes, animations et saisie | CRITIQUE | perf-* |
| 3 | Échecs de lecture et DRM | ÉLEVÉ | video-* |
| 4 | Lisibilité et mise en page 10 pieds | ÉLEVÉ | design-* |
| 5 | Accessibilité TV | ÉLEVÉ | a11y-* |
| 6 | Configuration de pile, tests et livraison | MOYEN | setup-*, test-*, release-* |
Référence rapide
- Détectez la pile TV à partir des fichiers package, des manifests, des dossiers natifs et des outils de plateforme.
- Reproduisez la navigation avec la télécommande ou le chemin D-pad, pas les hypothèses de souris/toucher.
- Confirmez que l'élément focalisé est toujours visible, accessible et restauré après des 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 le travail des listes, animations, mémoire et démarrage sur la cible TV la plus faible.
Références
Focus et Navigation
| Fichier | Impact | Description |
|---|---|---|
| focus-management.md | CRITIQUE | Moteurs de focus, guides de focus, nextFocus* et restauration de focus |
| focus-performance.md | CRITIQUE | Éviter les chutes d'images dues à la gestion des événements de focus |
| nav-directional.md | CRITIQUE | Règles de navigation directionnelle sur les plateformes TV |
| nav-patterns.md | CRITIQUE | Navigation globale/locale, modales, onglets et comportement Retour |
| nav-keyboard.md | MOYEN | Recherche et saisie de texte avec télécommandes |
Design
| Fichier | Impact | Description |
|---|---|---|
| design-10foot.md | ÉLEVÉ | Heuristiques de revue 10 pieds |
| design-typography.md | ÉLEVÉ | Dimensionnement et lisibilité de la typographie TV |
| design-layout.md | ÉLEVÉ | Zones sécurisées, espacement, carrousels et espace de focus |
| design-color.md | MOYEN | Contraste et contraintes de couleur d'affichage TV |
Performances
| Fichier | Impact | Description |
|---|---|---|
| perf-overview.md | ÉLEVÉ | Cibles de performance TV et ordre de profilage |
| perf-lists.md | CRITIQUE | Lignes virtualisées et listes lourdes en posters |
| perf-animations.md | CRITIQUE | Performances des animations de focus et de transition |
| perf-memory.md | ÉLEVÉ | Plantages TV à mémoire limitée et pression image/vidéo |
| perf-network.md | ÉLEVÉ | Saisie à distance, blocages de requêtes et résilience réseau |
Vidéo, Accessibilité, Configuration, Tests
| Fichier | Impact | Description |
|---|---|---|
| video-streaming.md | ÉLEVÉ | Sélection de protocole/DRM pour plateforme TV |
| video-players.md | ÉLEVÉ | Choix de lecteurs et contrôles personnalisés |
| video-debugging.md | ÉLEVÉ | Débogage du manifest, DRM, codec et lecture |
| a11y-overview.md | MOYEN | Différences d'accessibilité spécifiques à la TV |
| a11y-implementation.md | ÉLEVÉ | Étiquettes accessibles, rôles, régions live et focus |
| a11y-checklist.md | MOYEN | Checklist d'audit d'accessibilité au lancement |
| setup-getting-started.md | MOYEN | Configuration de react-native-tvos et Expo TV |
| setup-cross-platform.md | MOYEN | Détection de plateforme et astuces multiplateforme |
| setup-architecture.md | MOYEN | Partage de code et structure de projet |
| test-strategy.md | MOYEN | Périmètre de test TV et répartition de la couverture |
| test-javascript.md | MOYEN | Aides de test JS pour la télécommande/le focus |
| test-e2e.md | MOYEN | Appium et couverture E2E TV |
| release-cicd.md | MOYEN | CI, empreinte de build et vérifications de livraison |
Problème → Correspondance de compétence
| Symptôme | Commencez ici |
|---|---|
| "Le focus saute sur le mauvais élément" | focus-management.md → Section Débogage |
| "L'application se fige lors du défilement des listes" | perf-lists.md → Virtualisation |
| "Les animations saccadent sur Fire TV" | perf-animations.md → Pilote natif |
| "Texte trop petit sur la TV" | design-typography.md → Tailles minimales |
| "La vidéo ne se lit pas / erreurs DRM" | video-streaming.md → Section DRM |
| "Le lecteur d'écran saute des éléments" | a11y-implementation.md → Rôles et étiquettes |
| "Le bouton Retour ne fonctionne pas correctement" | nav-patterns.md → Navigation Retour |
| "Le clavier couvre le contenu" | nav-keyboard.md → Intégré vs personnalisé |
| "L'application met une éternité à démarrer" | perf-overview.md → Temps de démarrage |
| "Les images provoquent des plantages mémoire" | perf-memory.md → Optimisation des images |
| "Le pipeline CI prend des heures" | release-cicd.md → Empreinte |
| "Comment partager du code entre les plateformes" | setup-architecture.md → Partage de code |
Sécurité (Spécifique à la TV)
L'hygiène générale des dépendances/saisies s'applique comme dans toute application RN ; les spécificités TV à souligner :
- N'intégrez jamais les clés FairPlay/Widevine/PlayReady dans le code client — considérez le serveur de licences comme la limite de confiance et faites en sorte que les jetons DRM soient émis par le serveur.