O que Melhores Práticas React Native para TV faz?
Visão Geral
Orientação de revisão específica para TV para aplicativos baseados em React Native no Apple TV, Android TV, Fire TV, Amazon Vega/Kepler e alvos de TV baseados na web, como Tizen ou webOS.
Use este skill apenas para deltas de TV: entrada remota, motores de foco, layout de 3 metros, empacotamento de plataforma, reprodução/DRM, hardware de TV com pouca memória e acessibilidade para TV. Para problemas comuns de desempenho ou arquitetura do React Native, use react-native-best-practices.
Formato do Skill
Os arquivos de referência são agrupados por prefixo de tópico:
focus-*: motores de foco, guias de foco, desempenho de eventos de foconav-*: navegação por D-pad, comportamento de Voltar/Menu, entrada de teclado/pesquisadesign-*: tipografia de 3 metros, layout, cor, visibilidade do focoperf-*: inicialização, memória, listas, animação e restrições de rede em hardware de TVvideo-*: arquitetura de reprodução, seleção de DRM/protocolo, depuraçãoa11y-*: implementação de acessibilidade para TV e verificações de auditoriasetup-*: detecção de pilha, configuração, arquitetura, comportamento entre plataformastest-*erelease-*: cobertura de testes, E2E e fluxos de CI/release
Quando Aplicar
Aplique este skill quando o aplicativo for direcionado a uma plataforma de TV e o trabalho envolver:
- Movimento de foco, foco visível, restauração de foco ou entrada remota/D-pad
- Legibilidade do layout da TV, overscan/áreas seguras ou densidade da UI de 3 metros
- Controles do player de TV, manifests, DRM, suporte a codecs ou erros de reprodução
- Desempenho em hardware de TV com pouca memória, especialmente com vídeo ou grandes carrosséis
- Acessibilidade para TV com leitores de tela, legendas, ordem de foco ou interação apenas com controle remoto
- Configuração de plataforma para
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen ou webOS
Antes de Começar — Identifique a Pilha de TV
Este skill cobre várias pilhas de TV. Detecte qual delas o aplicativo alvo antes de sinalizar problemas de configuração — exigir react-native-tvos, um Podfile tvOS ou um manifesto Android TV em um aplicativo Vega/Kepler ou baseado na web produz falsos positivos.
| Pilha | Como detectar | Expectativas de configuração |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" no package.json | Podfile tvOS (platform :tvos); entradas de manifesto leanback/LEANBACK_LAUNCHER no Android TV; emulador/simulador de TV |
| Expo + react-native-tvos | acima mais @react-native-tvos/config-tv no app.json | EXPO_TV=1 prebuild; a versão do react-native-tvos deve corresponder ao SDK do Expo; nem todos os recursos/bibliotecas do Expo estão disponíveis na TV |
| Amazon Vega / Kepler | SDK e ferramentas Vega/Kepler (deps @amazon-devices/*, manifesto Kepler); sem react-native-tvos | Toolchain Vega/Kepler da Amazon — react-native-tvos, Podfile tvOS e manifesto Android TV não se aplicam |
| TV baseada na web (Tizen, webOS) | Bundler web (Rsbuild/webpack) + empacotamento de plataforma; biblioteca de navegação espacial | Empacotamento SDK da plataforma; @noriginmedia/norigin-spatial-navigation para foco |
As orientações sobre foco, design de 3 metros, desempenho, acessibilidade e player se aplicam a todas essas pilhas — apenas as expectativas de configuração/build são específicas da pilha.
Regras de Revisão
- Resolva a pilha alvo antes de aconselhar sobre configuração.
- Prefira ordem de foco natural e guias de foco antes de chamadas de foco imperativas ou mapas
nextFocus*extensos. - Trate perda de foco, foco invisível e comportamento quebrado de Voltar/Menu como bugs de navegação.
- Verifique legibilidade, áreas seguras e estados de foco à distância da TV antes de ajustar detalhes visuais.
- Crie perfil no dispositivo de TV mais fraco suportado antes de relatar correções de desempenho como concluídas.
- Separe falhas de reprodução por camada: solicitação de manifesto, troca de licença DRM, capacidade do decodificador, estado do player e controles de UI do React.
Diretrizes Priorizadas
| Prioridade | Categoria | Impacto | Prefixo |
|---|---|---|---|
| 1 | Foco e navegação por D-pad | CRÍTICO | focus-*, nav-* |
| 2 | Desempenho de lista, animação e entrada | CRÍTICO | perf-* |
| 3 | Falhas de reprodução e DRM | ALTO | video-* |
| 4 | Legibilidade e layout de 3 metros | ALTO | design-* |
| 5 | Acessibilidade para TV | ALTO | a11y-* |
| 6 | Configuração, teste e release da pilha | MÉDIO | setup-*, test-*, release-* |
Referência Rápida
- Detecte a pilha de TV a partir de arquivos de pacote, manifests, pastas nativas e ferramentas de plataforma.
- Reproduza a navegação com o controle remoto ou caminho D-pad, não com suposições de mouse/toque.
- Confirme que o elemento focado está sempre visível, acessível e restaurado após modais/rotas.
- Verifique falhas de reprodução da camada de rede/DRM para cima antes de alterar controles React.
- Meça o trabalho de lista, animação, memória e inicialização no alvo de TV mais fraco suportado.
Referências
Foco e Navegação
| Arquivo | Impacto | Descrição |
|---|---|---|
| focus-management.md | CRÍTICO | Motores de foco, guias de foco, nextFocus* e restauração de foco |
| focus-performance.md | CRÍTICO | Evitando quedas de quadros devido ao tratamento de eventos de foco |
| nav-directional.md | CRÍTICO | Regras de navegação direcional entre plataformas de TV |
| nav-patterns.md | CRÍTICO | Navegação global/local, modais, abas e comportamento de Voltar |
| nav-keyboard.md | MÉDIO | Pesquisa e entrada de texto com controles remotos |
Design
| Arquivo | Impacto | Descrição |
|---|---|---|
| design-10foot.md | ALTO | Heurísticas de revisão de 3 metros |
| design-typography.md | ALTO | Dimensionamento e legibilidade de tipo para TV |
| design-layout.md | ALTO | Áreas seguras, espaçamento, carrosséis e espaço para foco |
| design-color.md | MÉDIO | Restrições de contraste e cor para display de TV |
Desempenho
| Arquivo | Impacto | Descrição |
|---|---|---|
| perf-overview.md | ALTO | Metas de desempenho para TV e ordem de criação de perfil |
| perf-lists.md | CRÍTICO | Linhas virtualizadas e listas pesadas em pôsteres |
| perf-animations.md | CRÍTICO | Desempenho de animação de foco e transição |
| perf-memory.md | ALTO | Travamentos por pouca memória na TV e pressão de imagem/vídeo |
| perf-network.md | ALTO | Entrada remota, paradas de solicitação e resiliência de rede |
Vídeo, Acessibilidade, Configuração, Testes
| Arquivo | Impacto | Descrição |
|---|---|---|
| video-streaming.md | ALTO | Seleção de protocolo/DRM para plataforma de TV |
| video-players.md | ALTO | Escolhas de player e controles personalizados |
| video-debugging.md | ALTO | Depuração de manifesto, DRM, codec e reprodução |
| a11y-overview.md | MÉDIO | Diferenças de acessibilidade específicas para TV |
| a11y-implementation.md | ALTO | Rótulos acessíveis, funções, regiões ativas e foco |
| a11y-checklist.md | MÉDIO | Lista de verificação de auditoria de acessibilidade de lançamento |
| setup-getting-started.md | MÉDIO | Configuração de react-native-tvos e Expo TV |
| setup-cross-platform.md | MÉDIO | Detecção de plataforma e ressalvas entre plataformas |
| setup-architecture.md | MÉDIO | Compartilhamento de código e estrutura do projeto |
| test-strategy.md | MÉDIO | Escopo de teste de TV e divisão de cobertura |
| test-javascript.md | MÉDIO | Auxiliares de teste de foco/remoto em nível JS |
| test-e2e.md | MÉDIO | Appium e cobertura E2E de TV |
| release-cicd.md | MÉDIO | CI, fingerprinting de build e verificações de release |
Mapeamento Problema → Skill
| Sintoma | Comece por aqui |
|---|---|
| "O foco pula para o elemento errado" | focus-management.md → Seção de depuração |
| "O aplicativo congela ao rolar listas" | perf-lists.md → Virtualização |
| "Animações travam no Fire TV" | perf-animations.md → Native driver |
| "Texto muito pequeno na TV" | design-typography.md → Tamanhos mínimos |
| "Vídeo não reproduz / erros de DRM" | video-streaming.md → Seção DRM |
| "Leitor de tela pula elementos" | a11y-implementation.md → Funções e rótulos |
| "Botão Voltar não funciona direito" | nav-patterns.md → Navegação Voltar |
| "Teclado cobre o conteúdo" | nav-keyboard.md → Integrado vs personalizado |
| "O aplicativo demora uma eternidade para iniciar" | perf-overview.md → Tempo de inicialização |
| "Imagens causando travamentos de memória" | perf-memory.md → Otimização de imagens |
| "Pipeline de CI leva horas" | release-cicd.md → Fingerprinting |
| "Como compartilhar código entre plataformas" | setup-architecture.md → Compartilhamento de código |
Segurança (Específica para TV)
A higiene geral de dependências/entrada se aplica como em qualquer aplicativo RN; os deltas específicos de TV que merecem destaque:
- Nunca incorpore chaves FairPlay/Widevine/PlayReady no código do cliente — trate o servidor de licenças como o limite de confiança e mantenha os tokens DRM emitidos pelo servidor.