构建电视 Expo 应用

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

警告 TV 开发仅在 SDK 50 及更高版本中可用。并非所有 Expo 功能和 SDK 模块均可在电视上使用。详细信息请参见 局限性 部分。

¥TV development is available only in SDK 50 and later. Not all Expo features and SDK modules are available on TV. See the Limitations section for details.

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.

支持的模块

¥Supported modules

目前，电视应用可使用我们的 Expo API 文档中列出的以下软件包和 API。

¥At this time, TV applications work with the following packages and APIs listed in our Expo API docs.

• AppleAuthentication

• 应用

  ¥Application

• 声音的

  ¥Audio

• 资源

  ¥Asset

• AsyncStorage

• AV

• BlurView

• BuildProperties

• 常量

  ¥Constants

• 加密

  ¥Crypto

• 设备

  ¥Device

• FileSystem

• FlashList

• 字体

  ¥Font

• 图片

  ¥Image

• KeepAwake

• LinearGradient

• 本土化

  ¥Localization

• 舱单

  ¥Manifests

• NetInfo

• 复活

  ¥Reanimated

• SafeAreaContext

• SplashScreen

• svg

• 更新

  ¥Updates

TV 还可以与 react-navigation、react-native-video 和许多其他常用的第三方 React Native 库配合使用。

¥TV also works with react-navigation, react-native-video, and many other commonly used third-party React Native libraries.

局限性

¥Limitations

• 目前不支持 Expo 开发客户端 包。

  ¥The Expo DevClient package is not supported at this time.

• 目前不支持 Expo 视频 包。电视开发者应继续使用 Expo AV 视频包。

  ¥The Expo Video package is not supported at this time. TV developers should continue to use the Expo AV package for video.

• 仅 SDK 51 及更高版本支持 Expo 路由 包。

  ¥The Expo Router package is only supported in SDK 51 and later.

与现有 Expo 项目集成

¥Integration with an existing Expo project

如果你有使用 SDK 50 或更高版本的现有 Expo 项目，以下演练介绍了修改 TV Expo 项目所需的步骤。

¥If you have an existing Expo project using SDK 50 or later, the following walkthrough describes the steps required to modify an Expo project for TV.

信息 如果你从 SDK 49 项目开始，则需要 升级到 SDK 50 或更高版本，然后才能继续执行以下步骤。

¥If you are starting with an SDK 49 project, you will need to upgrade to SDK 50 or higher before proceeding through the following steps.

{
  %%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": {}
}

更多

¥More