构建用于电视的 Expo 应用

一份用于构建面向 Android TV 或 Apple TV 目标的 Expo 应用的指南。

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

警告 并非所有 Expo 功能和 SDK 库都可用于 TV。更多详情，请查看 查看支持哪些库。

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

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

前置条件

对原生 Android 和 iOS 文件所需的更改很少，并且如果你使用 prebuild，可以通过 config plugin 自动完成。下面列出了 config plugins 所做的更改，你也可以选择手动应用这些更改：

Android

• 修改 AndroidManifest.xml：
  • 移除默认的手机竖屏方向
  • 添加 TV 应用所需的 intent
• 修改 MainApplication.kt，移除不受支持的 Flipper 调用

iOS

• 修改 ios/Podfile 以将目标设为 tvOS 而不是 iOS
• 修改 Xcode 项目以将目标设为 tvOS 而不是 iOS
• 修改启动画面（SplashScreen.storyboard）以便在 tvOS 上工作

TV 开发的系统要求

Android TV

• macOS 或 Linux 上的 Node.js (LTS)。
• 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

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

快速开始

生成新项目的最快方法在 Expo 示例仓库中的 TV 示例 中有说明：

你也可以从 TV Router 示例 开始：

这会创建一个使用 Expo Router 进行基于文件的导航的新项目，其结构基于 create-expo-app 默认模板。

在现有 Expo 项目中集成

下面的步骤说明了将 Expo 项目修改为支持 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": {}
}

示例与演示项目