React Native TV Best Practices
Überblick
TV-spezifische Überprüfungsrichtlinien für React Native-Apps auf Apple TV, Android TV, Fire TV, Amazon Vega/Kepler und webbasierten TV-Zielen wie Tizen oder webOS.
Verwenden Sie diese Skill nur für TV-Deltas: Fernbedienungseingabe, Fokus-Engines, 10-Fuß-Layout, Plattform-Packaging, Wiedergabe/DRM, leistungsarme TV-Hardware und TV-Barrierefreiheit. Für allgemeine React Native Performance- oder Architekturprobleme verwenden Sie react-native-best-practices.
Skill-Format
Referenzdateien sind nach Themenpräfix gruppiert:
focus-*: Fokus-Engines, Fokus-Guides, Fokus-Ereignis-Performancenav-*: D-Pad-Navigation, Zurück/Menü-Verhalten, Tastatur/Sucheingabedesign-*: 10-Fuß-Typografie, Layout, Farbe, Fokus-Sichtbarkeitperf-*: Startup, Speicher, Listen, Animationen und Netzwerkbeschränkungen auf TV-Hardwarevideo-*: Wiedergabearchitektur, DRM/Protokollauswahl, Debugginga11y-*: TV-Barrierefreiheit Implementierung und Prüfungscheckssetup-*: Stack-Erkennung, Einrichtung, Architektur, plattformübergreifendes Verhaltentest-*undrelease-*: Testabdeckung, E2E und CI/Release-Workflows
Wann anwenden
Wenden Sie diese Skill an, wenn die App auf eine TV-Plattform abzielt und die Arbeit Folgendes umfasst:
- Fokusbewegung, sichtbarer Fokus, Fokus-Wiederherstellung oder Fernbedienung/D-Pad-Eingabe
- TV-Layout-Lesbarkeit, Überabtastung/Sicherheitsbereiche oder 10-Fuß-UI-Dichte
- TV-Player-Steuerung, Manifests, DRM, Decoder-Unterstützung oder Wiedergabefehler
- Performance auf leistungsarmer TV-Hardware, insbesondere mit Video oder großen Karussells
- TV-Barrierefreiheit mit Screenreadern, Untertiteln, Fokus-Reihenfolge oder reiner Fernbedienungsinteraktion
- Plattform-Setup für
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen oder webOS
Bevor Sie beginnen – Identifizieren Sie den TV-Stack
Diese Skill deckt mehrere TV-Stacks ab. Erkennen Sie, auf welchen Stack die App abzielt, bevor Sie Setup-Probleme melden – die Forderung nach react-native-tvos, einem tvOS-Podfile oder einem Android-TV-Manifest bei einer Vega/Kepler- oder webbasierten TV-App führt zu Fehlalarmen.
| Stack | Erkennungsmethode | Setup-Erwartungen |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" in package.json | tvOS-Podfile (platform :tvos); Android TV leanback/LEANBACK_LAUNCHER Manifesteinträge; TV-Emulator/Simulator |
| Expo + react-native-tvos | oben plus @react-native-tvos/config-tv in app.json | EXPO_TV=1 prebuild; react-native-tvos-Version muss mit dem Expo SDK übereinstimmen; nicht alle Expo-Features/Bibliotheken sind auf TV verfügbar |
| Amazon Vega / Kepler | Vega/Kepler SDK & Tooling (@amazon-devices/*-Abhängigkeiten, Kepler-Manifest); kein react-native-tvos | Amazon's Vega/Kepler-Toolchain – react-native-tvos, tvOS-Podfile und Android-TV-Manifest gelten nicht |
| Webbasiertes TV (Tizen, webOS) | Web-Bundler (Rsbuild/webpack) + Plattform-Packaging; spatial-nav-Bibliothek | Plattform-SDK-Packaging; @noriginmedia/norigin-spatial-navigation für Fokus |
Die Anleitung zu Fokus, 10-Fuß-Design, Performance, Barrierefreiheit und Player gilt für alle diese Stacks – nur die Setup-/Build-Erwartungen sind stackspezifisch.
Überprüfungsregeln
- Lösen Sie den Ziel-Stack vor Setup-Ratschlägen auf.
- Bevorzugen Sie natürliche Fokus-Reihenfolge und Fokus-Guides vor imperativen Fokus-Aufrufen oder breiten
nextFocus*-Mappings. - Behandeln Sie Fokusverlust, unsichtbaren Fokus und defektes Zurück/Menü-Verhalten als Navigationsfehler.
- Überprüfen Sie Lesbarkeit, Sicherheitsbereiche und Fokus-Zustände in TV-Entfernung, bevor Sie visuelle Details optimieren.
- Profilen Sie auf dem schwächsten unterstützten TV-Gerät, bevor Sie Performance-Fixes als abgeschlossen melden.
- Trennen Sie Wiedergabefehler nach Schichten: Manifest-Anfrage, DRM-Lizenzaustausch, Decoder-Fähigkeit, Player-Zustand und React-UI-Steuerung.
Prioritätsgeordnete Richtlinien
| Priorität | Kategorie | Auswirkung | Präfix |
|---|---|---|---|
| 1 | Fokus und D-Pad-Navigation | KRITISCH | focus-*, nav-* |
| 2 | Listen-, Animations- und Eingabe-Performance | KRITISCH | perf-* |
| 3 | Wiedergabe- und DRM-Fehler | HOCH | video-* |
| 4 | 10-Fuß-Lesbarkeit und Layout | HOCH | design-* |
| 5 | TV-Barrierefreiheit | HOCH | a11y-* |
| 6 | Stack-Setup, Tests und Release | MITTEL | setup-*, test-*, release-* |
Kurzreferenz
- Erkennen Sie den TV-Stack anhand von Paketdateien, Manifesten, nativen Ordnern und Plattform-Tooling.
- Reproduzieren Sie die Navigation mit der Fernbedienung oder dem D-Pad-Pfad, nicht mit Maus-/Touch-Annahmen.
- Bestätigen Sie, dass das fokussierte Element immer sichtbar, erreichbar und nach Modals/Routen wiederhergestellt ist.
- Überprüfen Sie Wiedergabefehler zuerst von der Netzwerk-/DRM-Ebene nach oben, bevor Sie React-Steuerungen ändern.
- Messen Sie Listen-, Animations-, Speicher- und Startup-Arbeit auf dem schwächsten unterstützten TV-Ziel.
Referenzen
Fokus und Navigation
| Datei | Auswirkung | Beschreibung |
|---|---|---|
| focus-management.md | KRITISCH | Fokus-Engines, Fokus-Guides, nextFocus* und Fokus-Wiederherstellung |
| focus-performance.md | KRITISCH | Vermeidung von Frameeinbrüchen durch Fokus-Ereignisbehandlung |
| nav-directional.md | KRITISCH | Richtungsnavigation über TV-Plattformen hinweg |
| nav-patterns.md | KRITISCH | Globale/lokale Navigation, Modals, Tabs und Zurück-Verhalten |
| nav-keyboard.md | MITTEL | Suche und Texteingabe mit Fernbedienungen |
Design
| Datei | Auswirkung | Beschreibung |
|---|---|---|
| design-10foot.md | HOCH | 10-Fuß-Überprüfungsheuristiken |
| design-typography.md | HOCH | TV-Schriftgrößen und Lesbarkeit |
| design-layout.md | HOCH | Sicherheitsbereiche, Abstände, Karussells und Fokus-Raum |
| design-color.md | MITTEL | Kontrast und TV-Display-Farbbeschränkungen |
Performance
| Datei | Auswirkung | Beschreibung |
|---|---|---|
| perf-overview.md | HOCH | TV-Performance-Ziele und Profiling-Reihenfolge |
| perf-lists.md | KRITISCH | Virtualisierte Zeilen und posterlastige Listen |
| perf-animations.md | KRITISCH | Fokus- und Übergangsanimationsperformance |
| perf-memory.md | HOCH | Speicherknappheit auf TV und Bild-/Videodruck |
| perf-network.md | HOCH | Fernbedienungseingabe, Anfragestaus und Netzwerkwiderstandsfähigkeit |
Video, Barrierefreiheit, Setup, Tests
| Datei | Auswirkung | Beschreibung |
|---|---|---|
| video-streaming.md | HOCH | TV-Plattform-Protokoll-/DRM-Auswahl |
| video-players.md | HOCH | Player-Auswahl und benutzerdefinierte Steuerungen |
| video-debugging.md | HOCH | Manifest-, DRM-, Codec- und Wiedergabe-Debugging |
| a11y-overview.md | MITTEL | TV-spezifische Barrierefreiheitsunterschiede |
| a11y-implementation.md | HOCH | Barrierefreie Labels, Rollen, Live-Regionen und Fokus |
| a11y-checklist.md | MITTEL | Checkliste für Barrierefreiheitsaudit beim Start |
| setup-getting-started.md | MITTEL | react-native-tvos und Expo TV Setup |
| setup-cross-platform.md | MITTEL | Plattformerkennung und plattformübergreifende Besonderheiten |
| setup-architecture.md | MITTEL | Code-Sharing und Projektstruktur |
| test-strategy.md | MITTEL | TV-Testumfang und Coverage-Aufteilung |
| test-javascript.md | MITTEL | JS-Ebene Fernbedienungs-/Fokus-Testhelfer |
| test-e2e.md | MITTEL | Appium und TV-E2E-Abdeckung |
| release-cicd.md | MITTEL | CI, Build-Fingerprinting und Release-Checks |
Problem → Skill-Zuordnung
| Symptom | Hier beginnen |
|---|---|
| "Fokus springt zum falschen Element" | focus-management.md → Abschnitt Fehlerbehebung |
| "App friert beim Scrollen von Listen ein" | perf-lists.md → Virtualisierung |
| "Animationen ruckeln auf Fire TV" | perf-animations.md → Nativer Treiber |
| "Text zu klein auf TV" | design-typography.md → Mindestgrößen |
| "Video wird nicht abgespielt / DRM-Fehler" | video-streaming.md → DRM-Abschnitt |
| "Screenreader überspringt Elemente" | a11y-implementation.md → Rollen & Labels |
| "Zurück-Button funktioniert nicht richtig" | nav-patterns.md → Zurück-Navigation |
| "Tastatur bedeckt Inhalt" | nav-keyboard.md → Eingebaut vs. benutzerdefiniert |
| "App startet ewig" | perf-overview.md → Startup-Zeit |
| "Bilder verursachen Speicher-Crashs" | perf-memory.md → Bildoptimierung |
| "CI-Pipeline dauert Stunden" | release-cicd.md → Fingerprinting |
| "Wie teile ich Code über Plattformen hinweg" | setup-architecture.md → Code-Sharing |
Sicherheit (TV-spezifisch)
Allgemeine Abhängigkeits-/Eingabehygiene gilt wie in jeder RN-App; die TV-spezifischen Unterschiede, die erwähnenswert sind:
- Betten Sie FairPlay-/Widevine-/PlayReady-Schlüssel niemals in Client-Code ein – behandeln Sie den Lizenzserver als Vertrauensgrenze und lassen Sie DRM-Token vom Server ausstellen.