¿Qué hace React Native TV: Mejores Prácticas?
Visión General
Guía de revisión específica para TV en aplicaciones basadas en React Native para Apple TV, Android TV, Fire TV, Amazon Vega/Kepler y destinos TV basados en web como Tizen o webOS.
Usa este skill solo para deltas de TV: entrada remota, motores de foco, diseño a 10 pies, empaquetado de plataforma, reproducción/DRM, hardware de TV con poca memoria y accesibilidad en TV. Para problemas ordinarios de rendimiento o arquitectura de React Native, usa react-native-best-practices.
Formato del Skill
Los archivos de referencia se agrupan por prefijo temático:
focus-*: motores de foco, guías de foco, rendimiento de eventos de foconav-*: navegación por D-pad, comportamiento de Atrás/Menú, entrada de búsqueda/tecladodesign-*: tipografía a 10 pies, diseño, color, visibilidad del focoperf-*: inicio, memoria, listas, animación y restricciones de red en hardware de TVvideo-*: arquitectura de reproducción, selección de DRM/protocolo, depuracióna11y-*: implementación de accesibilidad en TV y comprobaciones de auditoríasetup-*: detección de pila, configuración, arquitectura, comportamiento multiplataformatest-*yrelease-*: cobertura de pruebas, E2E y flujos de trabajo de CI/lanzamiento
Cuándo Aplicar
Aplica este skill cuando la aplicación tenga como objetivo una plataforma TV y el trabajo involucre:
- Movimiento de foco, foco visible, restauración de foco o entrada remota/D-pad
- Legibilidad del diseño TV, áreas de sobreexploración/seguras o densidad de interfaz a 10 pies
- Controles de reproductor TV, manifiestos, DRM, soporte de decodificador o errores de reproducción
- Rendimiento en hardware de TV con poca memoria, especialmente con video o carruseles grandes
- Accesibilidad en TV con lectores de pantalla, subtítulos, orden de foco o interacción solo con control remoto
- Configuración de plataforma para
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen o webOS
Antes de Empezar — Identifica la Pila de TV
Este skill cubre varias pilas de TV. Detecta a cuál apunta la aplicación antes de señalar problemas de configuración — exigir react-native-tvos, un Podfile de tvOS o un manifiesto de Android TV en una aplicación Vega/Kepler o TV basada en web produce falsos positivos.
| Pila | Cómo detectar | Expectativas de configuración |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" en package.json | Podfile de tvOS (platform :tvos); entradas de manifiesto Android TV leanback/LEANBACK_LAUNCHER; emulador/simulador TV |
| Expo + react-native-tvos | lo anterior más @react-native-tvos/config-tv en app.json | prebuild EXPO_TV=1; la versión de react-native-tvos debe coincidir con el SDK de Expo; no todas las funciones/bibliotecas de Expo están disponibles en TV |
| Amazon Vega / Kepler | SDK y herramientas de Vega/Kepler (deps @amazon-devices/*, manifiesto Kepler); sin react-native-tvos | cadena de herramientas de Amazon Vega/Kepler — react-native-tvos, Podfile de tvOS y manifiesto de Android TV no aplican |
| TV basada en web (Tizen, webOS) | bundler web (Rsbuild/webpack) + empaquetado de plataforma; biblioteca de navegación espacial | Empaquetado del SDK de plataforma; @noriginmedia/norigin-spatial-navigation para foco |
Las guías de foco, diseño a 10 pies, rendimiento, accesibilidad y reproductor aplican a todas estas — solo las expectativas de configuración/compilación son específicas de la pila.
Reglas de Revisión
- Resuelve la pila objetivo antes de dar consejos de configuración.
- Prefiere el orden de foco natural y las guías de foco antes que llamadas de foco imperativas o mapas
nextFocus*amplios. - Trata la pérdida de foco, el foco invisible y el comportamiento roto de Atrás/Menú como errores de navegación.
- Verifica la legibilidad, las áreas seguras y los estados de foco a distancia TV antes de ajustar detalles visuales.
- Perfila en el dispositivo TV más débil compatible antes de reportar como completas las correcciones de rendimiento.
- Separa los fallos de reproducción por capa: solicitud de manifiesto, intercambio de licencia DRM, capacidad del decodificador, estado del reproductor y controles de interfaz React.
Guías Priorizadas
| Prioridad | Categoría | Impacto | Prefijo |
|---|---|---|---|
| 1 | Foco y navegación por D-pad | CRÍTICO | focus-*, nav-* |
| 2 | Rendimiento de listas, animación y entrada | CRÍTICO | perf-* |
| 3 | Fallos de reproducción y DRM | ALTO | video-* |
| 4 | Legibilidad y diseño a 10 pies | ALTO | design-* |
| 5 | Accesibilidad en TV | ALTO | a11y-* |
| 6 | Configuración de pila, pruebas y lanzamiento | MEDIO | setup-*, test-*, release-* |
Referencia Rápida
- Detecta la pila de TV a partir de archivos de paquete, manifiestos, carpetas nativas y herramientas de plataforma.
- Reproduce la navegación con el control remoto o la ruta del D-pad, no con suposiciones de ratón/toque.
- Confirma que el elemento enfocado siempre sea visible, alcanzable y restaurado después de modales/rutas.
- Verifica los fallos de reproducción desde la capa de red/DRM hacia arriba antes de cambiar los controles React.
- Mide el trabajo de listas, animación, memoria e inicio en el objetivo TV más débil compatible.
Referencias
Foco y Navegación
| Archivo | Impacto | Descripción |
|---|---|---|
| focus-management.md | CRÍTICO | Motores de foco, guías de foco, nextFocus* y restauración de foco |
| focus-performance.md | CRÍTICO | Evitar caídas de fotogramas por manejo de eventos de foco |
| nav-directional.md | CRÍTICO | Reglas de navegación direccional en plataformas TV |
| nav-patterns.md | CRÍTICO | Navegación global/local, modales, pestañas y comportamiento Atrás |
| nav-keyboard.md | MEDIO | Búsqueda y entrada de texto con controles remotos |
Diseño
| Archivo | Impacto | Descripción |
|---|---|---|
| design-10foot.md | ALTO | Heurísticas de revisión a 10 pies |
| design-typography.md | ALTO | Tamaño de tipografía y legibilidad en TV |
| design-layout.md | ALTO | Áreas seguras, espaciado, carruseles y espacio para foco |
| design-color.md | MEDIO | Restricciones de contraste y color de pantalla TV |
Rendimiento
| Archivo | Impacto | Descripción |
|---|---|---|
| perf-overview.md | ALTO | Objetivos de rendimiento TV y orden de perfilado |
| perf-lists.md | CRÍTICO | Filas virtualizadas y listas con muchos pósters |
| perf-animations.md | CRÍTICO | Rendimiento de animaciones de foco y transición |
| perf-memory.md | ALTO | Fallos de TV con poca memoria y presión de imagen/video |
| perf-network.md | ALTO | Entrada remota, estancamiento de solicitudes y resiliencia de red |
Video, Accesibilidad, Configuración, Pruebas
| Archivo | Impacto | Descripción |
|---|---|---|
| video-streaming.md | ALTO | Selección de protocolo/DRM para plataforma TV |
| video-players.md | ALTO | Opciones de reproductor y controles personalizados |
| video-debugging.md | ALTO | Depuración de manifiesto, DRM, códec y reproducción |
| a11y-overview.md | MEDIO | Diferencias de accesibilidad específicas de TV |
| a11y-implementation.md | ALTO | Etiquetas accesibles, roles, regiones activas y foco |
| a11y-checklist.md | MEDIO | Lista de verificación de auditoría de accesibilidad de lanzamiento |
| setup-getting-started.md | MEDIO | Configuración de react-native-tvos y Expo TV |
| setup-cross-platform.md | MEDIO | Detección de plataforma y advertencias multiplataforma |
| setup-architecture.md | MEDIO | Compartición de código y estructura del proyecto |
| test-strategy.md | MEDIO | Alcance de pruebas TV y división de cobertura |
| test-javascript.md | MEDIO | Ayudantes de prueba de foco/remoto a nivel JS |
| test-e2e.md | MEDIO | Appium y cobertura E2E en TV |
| release-cicd.md | MEDIO | CI, huella de compilación y verificaciones de lanzamiento |
Mapeo de Problema → Recurso
| Síntoma | Empezar Aquí |
|---|---|
| "El foco salta al elemento incorrecto" | focus-management.md → Sección de depuración |
| "La aplicación se congela al desplazar listas" | perf-lists.md → Virtualización |
| "Las animaciones se entrecortan en Fire TV" | perf-animations.md → Controlador nativo |
| "El texto es demasiado pequeño en TV" | design-typography.md → Tamaños mínimos |
| "El video no se reproduce / errores DRM" | video-streaming.md → Sección DRM |
| "El lector de pantalla omite elementos" | a11y-implementation.md → Roles y etiquetas |
| "El botón Atrás no funciona correctamente" | nav-patterns.md → Navegación Atrás |
| "El teclado cubre el contenido" | nav-keyboard.md → Incorporado vs personalizado |
| "La aplicación tarda mucho en iniciar" | perf-overview.md → Tiempo de inicio |
| "Las imágenes causan fallos de memoria" | perf-memory.md → Optimización de imágenes |
| "El pipeline de CI tarda horas" | release-cicd.md → Huella digital |
| "Cómo compartir código entre plataformas" | setup-architecture.md → Compartición de código |
Seguridad (Específica de TV)
La higiene general de dependencias/entrada aplica como en cualquier aplicación RN; los deltas específicos de TV que vale la pena mencionar:
- Nunca incrustes claves FairPlay/Widevine/PlayReady en el código del cliente — trata el servidor de licencias como el límite de confianza y mantén los tokens DRM emitidos por el servidor.