构建电视 Expo 应用

为 Android TV 或 Apple TV 目标构建 Expo 应用的指南。

警告 并非所有 Expo 功能和 SDK 库都可在电视上使用。更多详情，请查看 查看支持的库。

React Native 通过 React Native TV 项目 支持 Android TV 和 Apple TV。这项技术不仅限于电视，还提供了一个全面的核心仓库分支，支持手机和电视平台，包括 Hermes 和 Fabric。

🌐 React Native is supported on Android TV and Apple TV through the React Native TV project. This technology extends beyond TV, offering a comprehensive core repo fork with support for phone and TV targets, including Hermes and Fabric.

在 Expo 项目中使用 React Native TV 库作为 react-native 依赖时，它就能够同时面向移动设备（Android、iOS）和电视设备（Android TV、Apple TV）。

🌐 Using the React Native TV library as the react-native dependency in an Expo project, it becomes capable of targeting both mobile (Android, iOS) and TV (Android TV, Apple TV) devices.

先决条件

🌐 Prerequisites

对本地 Android 和 iOS 文件的必要更改很少，如果使用 prebuild，可以通过 config 插件 自动补齐。以下是 config 插件所做更改的列表，你也可以选择手动应用这些更改：

🌐 The necessary changes to the native Android and iOS files are minimal and can be automated with a config plugin if you use prebuild. Below is a list of changes made by the config plugins, which you can alternatively apply manually:

安卓

🌐 Android

• AndroidManifest.xml 已被修改：
  • 删除默认手机纵向方向
  • 添加了电视应用所需的意图
• MainApplication.kt 已被修改，以移除不支持的 Flipper 调用

iOS

• ios/Podfile 已修改为面向 tvOS，而非 iOS
• Xcode 项目已修改为目标 tvOS 而不是 iOS
• 启动画面（SplashScreen.storyboard）已修改以适用于 tvOS

TV 开发的系统要求

🌐 System requirements for TV development

Android TV

• Node.js（LTS） 在 macOS 或 Linux 上。
• Android Studio（Iguana 或更高版本）。
• 在 Android Studio 的 SDK 管理器中，选择你正在使用的 Android SDK 下拉菜单（API 版本 31 或更高版本），并确保选择了要安装的 Android TV 系统镜像。（对于 Apple Silicon，请选择 ARM 64 镜像；否则，请选择 Intel x86_64 镜像。）
• 安装 Android TV 系统映像后，使用该映像创建 Android TV 模拟器（该过程与创建 Android 手机模拟器相同）。

Apple TV

• Node.js（LTS） 在 macOS 上。
• Xcode 16 或更高版本。
• tvOS SDK 17 或更高版本。（这个不会随 Xcode 自动安装。你可以稍后使用 xcodebuild -downloadAllPlatforms 安装它）。

快速开始

🌐 Quick start

在 Expo 示例仓库中的 TV 示例 中描述了生成新项目的最快方法：

🌐 The fastest way to generate a new project is described in the TV example within the Expo examples repository:

你可以从 电视路由示例 开始：

🌐 You can start with the TV Router example:

这将创建一个新项目，该项目使用 Expo Router 进行基于文件的导航，参考 create-expo-app 默认模板 模式。

🌐 This creates a new project that uses Expo Router for file-based navigation, modeled after the create-expo-app default template.

与现有的 Expo 项目集成

🌐 Integration with an existing Expo project

以下指南描述了修改适用于电视的 Expo 项目所需的步骤。

🌐 The following walkthrough describes the steps required to modify an Expo project for TV.

{
  %%placeholder-start%%... %%placeholder-end%%
  "dependencies": {
    %%placeholder-start%%... %%placeholder-end%%
    "react-native": "npm:react-native-tvos@0.81-stable",
    %%placeholder-start%%... %%placeholder-end%%
  },
  "expo": {
    "install": {
      "exclude": [
        "react-native"
      ]
    }
  }
}

{
  "plugins": ["@react-native-tvos/config-tv"]
}

{
  "cli": {
    "version": ">= 5.2.0"
  },
  "build": {
    "base": {
      "distribution": "internal",
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk",
        "withoutCredentials": true
      },
      "channel": "base"
    },
    "development": {
      "extends": "base",
      "android": {
        "gradleCommand": ":app:assembleDebug"
      },
      "ios": {
        "buildConfiguration": "Debug"
      },
      "channel": "development"
    },
    "development_tv": {
      "extends": "development",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "development"
    },
    "preview": {
      "extends": "base",
      "channel": "preview"
    },
    "preview_tv": {
      "extends": "preview",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "preview"
    }
  },
  "submit": {}
}

示例和演示项目

🌐 Examples and demonstration projects