创建和运行电视应用

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

重要提示：您的应用必须符合特定要求，才有资格作为 Android TV 应用显示在 Google Play 上。如需了解详情，请参阅 TV 应用质量中列出的要求。

本指南介绍了如何准备开发环境以构建 TV 应用，以及为使应用能够在 TV 设备上运行而必须进行的最低限度的更改。

如需了解如何设计 TV 应用，请参阅为电视设计。另请参阅 Android TV GitHub 代码库中的示例应用。

确定媒体格式支持

如需了解 Android TV 支持的编解码器、协议和格式，请参阅以下文档：

设置 TV 项目

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

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

  • TV activity：在应用清单中，声明一个旨在 TV 设备上运行的 activity。
  • TV 库：可以选择性地包含一个或多个适用于 TV 设备的 androidx 库，这些库已在本指南的另一部分中列出。 这些库提供用于构建用户界面的 widget。

前提条件

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

  • 将您的 SDK 工具更新到 24.0.0 或更高版本。
    借助更新后的 SDK 工具，您可以构建和测试电视应用。
  • 将您的 SDK 更新为 Android 5.0（API 21）或更高版本。
    更新后的平台版本为 TV 应用提供了新的 API。
  • 创建或更新应用项目。
    如需访问适用于电视设备的新 API，请创建以 Android 5.0（API 级别 21）或更高版本为目标平台的项目，或修改现有项目。

声明 TV 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 布局。如需查看有关设计 TV 应用的准则，请参阅为电视设计。

声明电视设备支持

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

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

<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 应用一样，Android TV 应用必须提供主屏幕图标。如需了解有关为应用设计出色启动点的最佳实践和详细的资源要求，请参阅 Android TV 应用图标和横幅指南。

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

对于横幅，请使用尺寸为 320 x 180 像素的 xhdpi 资源。图片中必须包含文字。如果您的应用有多个语言版本，您必须为每种支持的语言提供单独的含文字的横幅版本。

更改启动器颜色

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

当电视应用启动时，系统会显示一个类似于不断扩大的实心圆的动画。如需自定义此动画的颜色，请将电视应用或 activity 的 android:colorPrimary 属性设置为特定颜色。此外，将两个过渡重叠属性设置为 true，如以下主题资源 XML 文件中的代码段所示：

<resources>
    <style name="MyTheme">
      <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 for TV

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

如需了解如何使用 Compose for TV 构建 TV 应用，请参阅在 Android TV 上使用 Jetpack Compose。

Leanback 界面工具包

Leanback 界面工具包为电视设备提供 API 和界面 widget：

如需了解如何使用 Leanback 界面工具包构建 TV 应用，请参阅构建 TV 播放应用。

运行 TV 应用

运行您的应用是开发过程的一个重要环节。您可以在配置为支持 USB 调试的电视设备上运行应用，也可以使用虚拟电视设备。

在实体设备上运行

按照以下步骤设置您的 TV 设备：

  1. 使用 USB 数据线将您的 TV 设备连接到开发计算机。如有需要，请参阅设备制造商提供的文档。
  2. 在您的 TV 设备上，转到设置。
  3. 在设备行中，选择关于。
  4. 滚动到 Build，然后多次选择 Build，直到您收到“您现在处于开发者模式！”消息。
  5. 返回设置。在偏好设置行中，选择开发者选项。
  6. 依次选择调试 > USB 调试，然后选择开启。
  7. 返回 TV 主屏幕。

要在 TV 设备上测试您的应用，请执行以下操作：

  1. 在 Android Studio 中，选择您的项目，然后点击工具栏中的 Run 图标 。
  2. 在 Select Deployment Target 窗口中，选择您的电视设备，然后点击 OK。

在虚拟设备上运行

Android SDK 中的 AVD 管理器提供了一些设备定义，可让您创建虚拟电视设备来运行和测试应用。

如需创建虚拟 TV 设备，请执行以下操作：

  1. 启动 AVD 管理器。如需了解详情，请参阅创建和管理虚拟设备。
  2. 在 AVD Manager 对话框中，点击 Device Definitions 标签。
  3. 选择其中一个 Android TV 设备定义，然后点击 Create AVD。
  4. 选择模拟器选项，然后点击 OK 以创建 AVD。

    注意：为获得最佳电视模拟器设备性能，请使用 x86 模拟器并启用使用主机 GPU 选项。还会在可用时使用虚拟设备加速。如需详细了解模拟器的硬件加速，请参阅为 Android 模拟器配置硬件加速。

要在虚拟 TV 设备上测试您的应用，请执行以下操作：

  1. 在 Android Studio 中，选择您的项目，然后点击工具栏中的 Run 图标 。
  2. 在 Select Deployment Target 窗口中，选择您的虚拟电视设备，然后点击 OK。

如需详细了解如何使用模拟器，请参阅 在 Android 模拟器上运行应用。如需详细了解如何将应用从 Android Studio 部署到虚拟设备，请参阅调试您的应用。

让电视应用以免安装应用的形式运行

免安装体验可让用户无需安装即可试用您的电视应用，有助于提高应用采用率。

如需将电视应用设置为在 Android TV 设备或模拟器上以免安装应用的形式运行，请先按照说明创建支持免安装体验的 app bundle。

接下来，在 TV 应用的 MainActivity 的 intent-filter 中，确保在 AndroidManifest.xml 中声明了 LAUNCHER 和 LEANBACK_LAUNCHER： 

<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>

您的电视应用现已配置为作为免安装体验运行。

准备发布电视应用

查看 TV 应用核对清单，了解准备发布和分发 TV 应用的后续步骤。

下一页
构建自适应应用