创建并运行电视应用

电视应用与手机和平板电脑应用使用相同的结构。 这种相似性意味着您可以修改现有的应用以在电视设备上运行，或者根据您已经了解的有关构建 Android 应用的知识创建新的应用。

重要提示：您的应用必须满足特定的要求才能在 Google Play 上被视为 Android TV 应用。 有关更多信息，请参阅电视应用质量中列出的要求。

本指南介绍了如何为构建电视应用准备开发环境以及启用应用在电视设备上运行所需的最低更改。

有关为电视设计应用的信息，请参阅为电视设计。 还可以查看Android TV GitHub 存储库中的示例应用。

确定媒体格式支持

有关 Android TV 支持的编解码器、协议和格式的信息，请参阅以下文档

• 支持的媒体格式
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

设置电视项目

本节讨论如何设置电视项目，无论您是修改现有 Android 应用以在电视设备上运行，还是创建新的电视应用。 如果您有现有的 Android 应用，则添加 Android TV 支持可以让您为电视设计用户界面，同时重用现有的应用架构。

在创建在电视设备上运行的应用时，您使用两个主要组件

• 电视活动：在您的应用程序清单中，声明一个旨在在电视设备上运行的活动。

• 电视库： 可选地，包含一个或多个适用于电视设备的 androidx 库，这些库在本指南的另一部分中列出。这些库提供用于构建用户界面的 Widget。

先决条件

在开始构建电视应用之前，您必须执行以下步骤

• 更新您的 SDK 工具 至 24.0.0 或更高版本。
  更新后的 SDK 工具允许您构建和测试电视应用。
• 使用 Android 5.0（API 21）或更高版本更新您的 SDK。
  更新的平台版本提供了用于电视应用的新 API。
• 创建 或更新您的应用项目。
  要访问电视设备的新 API，请创建或修改一个以 Android 5.0（API 级别 21）或更高版本为目标的项目。

声明电视 Activity

旨在在电视设备上运行的应用必须在其清单中声明一个用于电视的启动 Activity。它使用 CATEGORY_LEANBACK_LAUNCHER intent 过滤器来执行此操作。此过滤器将您的应用识别为已启用电视功能，并允许 Google Play 将其识别为电视应用。当用户在他们的电视主屏幕上选择您的应用时，此 intent 会识别要启动的 Activity。

以下代码片段显示了如何在清单中包含此 intent 过滤器

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
  </activity>

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    android:theme="@style/Theme.Leanback">

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>

  </activity>
</application>

此示例中的第二个 Activity 清单条目指定它是要在电视设备上启动的 Activity。

注意： 如果您未在应用中包含 CATEGORY_LEANBACK_LAUNCHER intent 过滤器，则在电视设备上运行 Google Play 的用户将看不到它。此外，如果您在使用开发者工具将应用加载到电视设备时应用没有此过滤器，则该应用不会显示在电视用户界面中。

您的电视应用的用户界面，或您现有应用的电视部分，必须提供一个简单的界面，以便于使用 10 英尺外的遥控器进行导航。如果您要修改现有应用以在电视上使用，请不要对电视使用与手机和平板电脑相同的 Activity 布局。有关设计电视应用的指南，请参阅 电视设计。

声明电视设备支持

通过声明 android.software.leanback 功能，声明您的应用是为 Android TV 构建的。

如果您的应用同时在移动设备和电视上运行，请将 required 属性值设置为 false。如果您将 required 属性值设置为 true，则 Google Play 仅会在 Android TV OS 上提供您的应用。

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

声明触摸屏不是必需的

旨在在电视设备上运行的应用不依赖于触摸屏进行输入。为了明确这一点，您的电视应用清单必须声明 android.hardware.touchscreen 功能不是必需的。此设置将您的应用识别为能够在电视设备上工作，并且是您的应用在 Google Play 中被视为电视应用的必要条件。以下代码示例显示了如何包含此清单声明

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

注意： 在您的应用清单中，您必须声明触摸屏不是必需的，如本代码示例所示。否则，您的应用不会显示在电视设备上的 Google Play 中。

提供主屏幕图标和横幅

Android TV 应用必须为每个本地化提供主屏幕图标和横幅图像。根据 Android TV 设备的不同，图标或横幅将用作出现在应用和游戏行主屏幕上的应用启动点。

要将这些添加到您的应用中，请在清单中按如下方式描述图标和横幅

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

主屏幕图标

Android TV 应用，就像所有 Android 应用一样，必须提供主屏幕图标。有关设计应用出色启动点以及详细资产要求的最佳实践，请参阅 Android TV 应用图标和横幅指南。

主屏幕横幅

使用 android:banner 属性与 <application> 标记一起，为所有应用 Activity 提供默认横幅，或与 <activity> 标记一起为特定 Activity 提供横幅。

对于横幅，请使用大小为 320 x 180 px 的 xhdpi 资源。图像中必须包含文本。如果您的应用以多种语言提供，则必须为每种支持的语言提供包含文本的横幅的单独版本。

更改启动器颜色

注意： 在 Android 12 及更高版本中，使用 SplashScreen 平台 API 构建的自定义启动画面动画不受 Android TV 应用支持。

当电视应用启动时，系统会显示一个类似于扩展的填充圆圈的动画。要自定义此动画的颜色，请将电视应用或 Activity 的 android:colorPrimary 属性设置为特定颜色。此外，请将两个转换重叠属性设置为 true，如以下主题资源 XML 文件代码片段所示

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

有关使用主题和样式的更多信息，请参阅 样式和主题。

构建适用于 Android TV OS 的应用

Jetpack 包含用于与电视应用一起使用的 androidx 包库。

适用于电视的 Compose

Compose 是构建 Android TV OS 应用的推荐方式。除了核心 Compose 库之外，适用于电视的 Compose 库还提供了专门为大屏幕设计的专用组件

• androidx.tv.foundation
• androidx.tv.material

在 在 Android TV 上使用 Jetpack Compose 中了解如何使用适用于电视的 Compose 构建电视应用。

Leanback UI 工具包

Leanback UI 工具包提供用于电视设备的 API 和用户界面 Widget

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

在 构建电视播放应用 中了解如何使用 Leanback UI 工具包构建电视应用。

运行电视应用

运行您的应用是开发过程的重要组成部分。您可以在配置为支持 USB 调试的电视设备上运行您的应用，或使用虚拟电视设备。

在物理设备上运行

按如下方式设置您的电视设备

1. 使用 USB 线缆将您的电视设备连接到您的开发机器。如有需要，请参阅设备制造商提供的文档。
2. 在您的电视设备上，导航至设置。
3. 在设备行中，选择关于。
4. 滚动到构建并多次选择构建，直到您收到消息“您现在是开发者！”
5. 返回设置。在首选项行中，选择开发者选项。
6. 选择调试 > USB 调试并选择开启。
7. 导航回电视主屏幕。

要在您的电视设备上测试您的应用

1. 在 Android Studio 中，选择您的项目并单击工具栏中的运行 。
2. 在选择部署目标窗口中，选择您的电视设备并单击确定。

在虚拟设备上运行

Android SDK 中的 AVD 管理器提供设备定义，允许您创建虚拟电视设备以运行和测试您的应用。

要创建虚拟电视设备

1. 启动 AVD 管理器。有关更多信息，请参阅 创建和管理虚拟设备。
2. 在 AVD 管理器对话框中，单击设备定义选项卡。
3. 选择其中一个 Android TV 设备定义并单击创建 AVD。
4. 选择模拟器选项并单击确定以创建 AVD。

   注意： 为了获得电视模拟器设备的最佳性能，请使用 x86 模拟器并启用使用主机 GPU选项。在可用时，也请使用虚拟设备加速。有关模拟器硬件加速的更多信息，请参阅 配置 Android 模拟器的硬件加速。

要在虚拟电视设备上测试您的应用

1. 在 Android Studio 中，选择您的项目并单击工具栏中的运行 。
2. 在选择部署目标窗口中，选择您的虚拟电视设备并单击确定。

有关使用模拟器的更多信息，请参阅 在 Android 模拟器上运行应用。有关从 Android Studio 将应用部署到虚拟设备的更多信息，请参阅 调试您的应用。

启用您的电视应用以作为即时体验运行

即时体验 使用户可以轻松试用您的电视应用，并有助于提高采用率。

要将您的电视应用设置为在 Android TV 设备或模拟器上作为即时应用运行，请首先按照说明 创建启用即时的应用包。

接下来，在电视应用的 MainActivity 的 intent-filter 中，确保 LAUNCHER 和 LEANBACK_LAUNCHER 都已在 AndroidManifest.xml 中声明

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

您的电视应用现已配置为作为即时体验运行。

准备您的电视应用以供发布

查看 电视应用清单，了解准备您的电视应用以供发布和分发的后续步骤。