创建和运行电视应用

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

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

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

有关设计电视应用的信息，请参阅电视设计。另请参阅Android TV GitHub 代码库中的示例应用。

确定媒体格式支持

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

设置电视项目

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

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

  • 电视 Activity：在您的应用清单中，声明一个要在电视设备上运行的 Activity。
  • 电视库：可选地，包含一个或多个适用于电视设备的androidx 库（在本指南的另一部分列出）。这些库提供用于构建用户界面的窗口小部件。

先决条件

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

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

声明电视 Activity

旨在在电视设备上运行的应用程序必须在其清单中声明一个用于电视的启动器活动。它使用CATEGORY_LEANBACK_LAUNCHER意图过滤器来实现这一点。此过滤器将您的应用识别为已启用电视功能，并允许 Google Play 将其识别为电视应用。当用户在其电视主屏幕上选择您的应用时，此意图将识别要启动的活动。

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

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

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

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

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

声明电视设备支持

通过声明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 应用图标和横幅指南。

使用带有<application>标签的android:banner属性为所有应用程序活动提供默认横幅，或使用<activity>标签为特定活动提供横幅。

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

更改启动器颜色

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

启动电视应用时，系统会显示一个类似于膨胀的填充圆圈的动画。要自定义此动画的颜色，请将电视应用或活动的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 操作系统的应用

Jetpack 包含可用于电视应用的androidx包库。

适用于电视的 Compose

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

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

Leanback UI 工具包

Leanback UI 工具包为电视设备提供 API 和用户界面小部件。

在构建电视播放应用中了解如何使用 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中，请确保在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>

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

准备发布您的电视应用

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

下一步
处理电视硬件