处理电视硬件

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

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

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

确定媒体格式支持

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

支持的媒体格式

• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer
• 设置电视项目

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

注意：我们建议您有一个同时支持移动设备和电视设备的单一应用。如果您需要针对移动设备和电视设备使用单独的应用，可以通过多 APK 支持在 Google Play 的同一商品详情下发布多个应用。如需了解更多信息，请参阅多 APK 支持。

电视 Activity：在您的应用清单中，声明一个旨在在电视设备上运行的 Activity。

• 电视库：（可选）包含本指南另一部分中列出的适用于电视设备的一个或多个androidx 库。这些库提供了用于构建用户界面的小部件。
• 前提条件

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

将您的 SDK 工具更新到 24.0.0 或更高版本。

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

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

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

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

<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 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 中被视为电视应用，则此设置是必需的。以下代码示例展示了如何包含此清单声明：

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

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

提供主屏幕图标和横幅

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 像素的 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 for TV 构建电视应用。

Leanback UI 工具包

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

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 调试的电视设备上运行应用，也可以使用虚拟电视设备。

在物理设备上运行

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

使用 USB 数据线将您的电视设备连接到开发机器。如果需要，请参阅设备制造商提供的文档。

1. 在您的电视设备上，导航到设置。
2. 在设备行中，选择关于。
3. 滚动到版本号并多次选择版本号，直到您收到“您现在是开发者！”的消息。
4. 返回设置。在偏好设置行中，选择开发者选项。
5. 选择调试 > USB 调试并选择开启。
6. 返回电视主屏幕。
7. 要在电视设备上测试您的应用：

在 Android Studio 中，选择您的项目，然后点击工具栏中的运行 。

1. 在选择部署目标窗口中，选择您的电视设备，然后点击确定。
2. 在虚拟设备上运行

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

要创建虚拟电视设备：

启动 AVD Manager。如需了解更多信息，请参阅创建和管理虚拟设备。

1. 在 AVD Manager 对话框中，点击设备定义标签页。
2. 选择其中一个 Android TV 设备定义，然后点击创建 AVD。
3. 选择模拟器选项，然后点击确定以创建 AVD。
4. 注意：为了获得最佳电视模拟器设备性能，请使用 x86 模拟器并启用使用主机 GPU 选项。在可用时，也请使用虚拟设备加速。有关模拟器硬件加速的更多信息，请参阅配置 Android 模拟器的硬件加速。

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

在选择部署目标窗口中，选择您的虚拟电视设备，然后点击确定。

1. 在选择部署目标窗口中，选择您的电视设备，然后点击确定。
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>

准备发布您的电视应用

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

下一步