构建电视 Expo 应用

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

警告 电视开发仅在 SDK 50 及以上版本中可用。并非所有 Expo 功能和 SDK 库都可在 TV 上使用。有关更多详细信息，请查看 查看支持哪些库。

¥TV development is available only in SDK 50 and above. Not all Expo features and SDK libraries are available on TV. For more details, check the See which libraries are supported.

Android TV 和 Apple TV 通过 React Native 电视项目 支持 React Native。这项技术超越了电视，提供了全面的核心存储库分支，支持手机和电视目标，包括 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.

使用 React Native TV 库作为 Expo 项目中的 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，则可以使用 配置插件 实现自动化。以下是配置插件所做的更改列表，你也可以手动应用这些更改：

¥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 修改为：

  ¥AndroidManifest.xml is modified:

  • 删除默认手机纵向方向

    ¥The default phone portrait orientation is removed

  • 添加了电视应用所需的意图

    ¥The required intent for TV apps is added

• 修改 MainApplication.kt 以删除不支持的 Flipper 调用

  ¥MainApplication.kt is modified to remove unsupported Flipper invocations

iOS 系统

¥iOS

• ios/Podfile 已修改为目标 tvOS 而不是 iOS

  ¥ios/Podfile is modified to target tvOS instead of iOS

• Xcode 项目已修改为目标 tvOS 而不是 iOS

  ¥The Xcode project is modified to target tvOS instead of iOS

• 启动画面 (SplashScreen.storyboard) 已修改以在 tvOS 上运行

  ¥The splash screen (SplashScreen.storyboard) is modified to work on tvOS

TV 开发的系统要求

¥System requirements for TV development

Android TV

• macOS 或 Linux 上的 Node.js (LTS)。

  ¥Node.js (LTS) on macOS or Linux.

• Android Studio（Iguana 或更高版本）。

  ¥Android Studio (Iguana or later).

• 在 Android Studio SDK 管理器中，选择你正在使用的 Android SDK（API 版本 31 或更高版本）的下拉列表，并确保选择安装 Android TV 系统映像。（对于 Apple 芯片，请选择 ARM 64 映像。否则，请选择 Intel x86_64 映像）。

  ¥In the Android Studio SDK manager, select the dropdown for the Android SDK you are using (API version 31 or later), and make sure an Android TV system image is selected for installation. (For Apple silicon, choose the ARM 64 image. Otherwise, choose the Intel x86_64 image).

• 安装 Android TV 系统映像后，使用该映像创建 Android TV 模拟器（该过程与创建 Android 手机模拟器相同）。

  ¥After installing the Android TV system image, create an Android TV emulator using that image (the process is the same as creating an Android phone emulator).

Apple TV

• macOS 上的 Node.js (LTS)。

  ¥Node.js (LTS) on macOS.

• Xcode 15 或更高版本。

  ¥Xcode 15 or later.

• tvOS SDK 17 或更高版本。（这不会随 Xcode 自动安装。你可以稍后使用 xcodebuild -downloadAllPlatforms 安装它）。

  ¥tvOS SDK 17 or later. (This is not installed automatically with Xcode. You can install it later with xcodebuild -downloadAllPlatforms).

快速开始

¥Quick start

Expo 示例存储库中的 电视示例 描述了生成新项目的最快方法：

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

对于 SDK 51 及更高版本，你可以从 电视路由示例 开始：

¥For SDK 51 and later, you can start with the TV Router example:

这将创建一个新项目，该项目使用 Expo 路由 进行基于文件的导航，以 create-expo-app 默认模板 为模型。

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

Integration with an existing Expo project

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",
    %%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