TV 应用开发入门

TV 应用使用的结构与手机和平板电脑应用相同。这种相似性意味着，您可以修改现有应用，使其同样可以在 TV 设备上运行，也可以基于已掌握的 Android 应用构建知识创建新应用。

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

本指南介绍如何准备用于构建 TV 应用的开发环境，以及至少需要做出哪些更改才能让应用能够在 TV 设备上运行。

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

确定媒体格式支持

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

设置 TV 项目

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

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

  • TV 的 Activity：在您的应用清单中，声明一个打算在 TV 设备上运行的 Activity。
  • TV 库：（可选）添加适用于 TV 设备的一个或多个 androidx 库，本指南的另一部分已列出这些库。 这些库提供了用于构建界面的微件。

前提条件

在开始构建 TV 应用之前，您必须按以下步骤操作：

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

声明 TV Activity

旨在于 TV 设备上运行的应用必须在其清单中声明 TV 的启动器 Activity。它使用 CATEGORY_LEANBACK_LAUNCHER intent 过滤器来执行此操作。此过滤器会将您的应用标识为支持 TV，并让 Google Play 能够将其识别为 TV 应用。当用户在其 TV 主屏幕上选择您的应用时，此 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 清单条目指定它是要在 TV 设备上启动的 activity。

注意：如果您不在应用中添加 CATEGORY_LEANBACK_LAUNCHER intent 过滤器，则在 TV 设备上运行 Google Play 的用户看不到您的应用。此外，如果您的应用没有此过滤器，那么当您使用开发者工具将其加载到 TV 设备上时，该应用不会出现在 TV 界面中。

您的 TV 应用界面或现有应用的 TV 部分必须提供简单的界面，以便用户使用距离 10 英尺远的遥控器轻松导航。如果您想将现有应用修改为在电视上使用，请不要对 TV 使用与手机和平板电脑相同的 activity 布局。如需了解有关设计 TV 应用的准则，请参阅设计 TV 应用。如需详细了解 TV 界面布局的最低实现要求，请参阅构建 TV 布局。

声明 TV 设备支持

通过声明 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>

将触摸屏声明为非必备条件

旨在于 TV 设备上运行的应用不依赖于触摸屏进行输入。为明确这一点，您必须在 TV 应用的清单中声明 android.hardware.touchscreen 功能并非必需功能。此设置会将您的应用标识为能够在 TV 设备上运行，并且您的应用只有在 Google Play 中才能被视为 TV 应用。以下代码示例展示了如何添加此清单声明： 

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

注意：您必须在应用清单中声明触摸屏并非必需，如以下示例代码所示。否则，您的应用不会出现在 TV 设备上的 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 构建的自定义启动画面动画。

当 TV 应用启动时，系统会显示一个动画，类似于一个不断膨胀的实心圆。如需自定义此动画的颜色，请将 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 包含用于 TV 应用的 androidx 软件包库。

Compose for TV

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

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

Leanback 界面工具包

Leanback 界面工具包为 TV 设备提供了 API 和界面 widget：

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

运行 TV 应用

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

在实体设备上运行

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

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

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

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

在虚拟设备上运行

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

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

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

    注意：为使 TV 模拟器设备达到最佳性能，请使用 x86 模拟器并启用 Use Host GPU 选项。此外，还要使用虚拟设备加速（如果可用）。如需详细了解模拟器的硬件加速，请参阅为 Android 模拟器配置硬件加速。

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

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

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

让您的 TV 应用提供免安装体验

免安装体验可让用户轻松试用您的 TV 应用，并且有助于提高采用率。

如需将您的 TV 应用设置为在 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 应用以供发布

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

下一页
AndroidX TV 库