leanback 使用

添加 TV 库

Jetpack 包含用于 TV 应用的 androidx 软件包库。这些库为 TV 设备提供了 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

管理 TV 控制器

方向键基本控制按钮

处理控制器断开连接事件

处理方向键输入变化

处理按钮事件

TV 设备需要通过基本遥控器或游戏控制器形式的辅助硬件设备与应用进行交互。这意味着您的应用必须支持方向键输入。此外，这还意味着您的应用可能需要处理离线控制器以及来自多种控制器的输入。

本课将介绍处理 TV 设备控制器方面的要求。

方向键基本控制按钮

TV 设备的默认控制器是方向键。一般而言，您的应用应该可以使用仅包含向上、向下、向左、向右、选择、返回和主页按钮的遥控器进行操作。对于游戏而言，通常需要使用带有更多控制按钮的游戏控制器进行操作。如果您的应用是一款游戏，应该尝试允许通过这些方向键控制按钮来操作游戏。在这种情况下，您的应用还应该提醒用户需要使用控制器，并允许他们使用方向键控制器正常退出游戏。

处理控制器断开连接事件

TV 控制器通常是蓝牙设备，这些设备可能会通过间歇性地进入休眠模式并断开与 TV 设备的连接来节省电能。这意味着，如果未将应用配置为处理这些重新连接事件，可能会导致应用中断或重新启动。在以下任何一种情况下都可能发生这些事件：

在观看一段几分钟长的视频时，方向键或游戏控制器进入休眠模式，断开与 TV 设备的连接，稍后又重新连接。

玩游戏时，新加入游戏的玩家所使用的游戏控制器尚未连接。

玩游戏时，玩家离开游戏并断开游戏控制器连接。

对于任何受断开连接和重新连接事件影响的 TV 应用 Activity，必须在应用清单文件中将其配置为处理重新连接事件。以下代码示例展示了如何使 Activity 能够处理配置更改，包括键盘或导航设备的连接、断开连接或重新连接：

<activity android:name="com.example.android.TvActivity" android:label="@string/app_name" android:configChanges="keyboard|keyboardHidden|navigation" 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> 

此配置变更允许应用通过重新连接事件继续运行，而不是由 Android 框架重新启动，后者无法带来良好的用户体验。

处理方向键输入变化

TV 设备用户可能有多种控制器与 TV 配合使用。例如，用户可能既有基本方向键控制器，又有游戏控制器。在用于执行方向键功能时，游戏控制器提供的键控代码可能不同于物理方向键发送的键控代码。

您的应用应该能够处理来自游戏控制器的方向键输入变化，以便无需实际切换控制器就能操作您的应用。如需详细了解如何处理这些输入变化，请参阅处理控制器操作。

处理按钮事件

当用户点击控制器上的按钮时，您的应用会收到 KeyEvent 事件。按钮的预期行为可能是媒体事件（如播放、暂停或停止），也可能是电视类型的事件（如选择或导航）。为了提供良好的用户体验，您的应用应当为控制器按钮分配一致的行为。

电视界面事件

应用应根据下表来处理生成这些 KeyEvent 的按钮。

KeyEvent行为BUTTON_B、BACK返回BUTTON_SELECT、BUTTON_A、ENTER、DPAD_CENTER、KEYCODE_NUMPAD_ENTER选择DPAD_UP、DPAD_DOWN、DPAD_LEFT、DPAD_RIGHT导航

媒体事件

当用户观看媒体内容时，您的应用应根据下表来处理生成这些 KeyEvent 的按钮。如果您的应用正在控制 MediaSession，应使用 MediaControllerAdapter 来调用如下所示的某个 MediaControllerCompat.TransportControls 方法。请注意，在此上下文中，选择按钮将充当播放/暂停按钮。

KeyEventTransportControls 调用行为BUTTON_SELECT、BUTTON_A、ENTER、DPAD_CENTER、KEYCODE_NUMPAD_ENTERpause()播放BUTTON_START、BUTTON_SELECT、BUTTON_A、ENTER、DPAD_CENTER、KEYCODE_NUMPAD_ENTERpause()暂停BUTTON_R1skipToNext()跳到下一个BUTTON_L1skipToPrevious()跳到上一个DPAD_RIGHT、BUTTON_R2、AXIS_RTRIGGER、AXIS_THROTTLEfastForward()快进DPAD_LEFT、BUTTON_L2、AXIS_LTRIGGER、AXIS_BRAKErewind()快退（没有与“停止”关联的 KeyEvent）stop()停止

处理游戏控制器

支持方向键控制

围绕方向键 (D-pad) 控制规划您的控制方案，因为这组控制是 Android TV 设备的默认设置。玩家必须能在游戏里使用 D-Pad 进行全方位操控 - 不仅能够控制核心游戏内容，还要能够浏览菜单和广告。为此，您还应确保您的 Android 电视游戏不会涉及触控界面。例如，Android TV 游戏不应向玩家显示“点按此处继续”的提示。

如何设计玩家与控制器的互动对于实现卓越的用户体验至关重要：

提前说明控制器要求。利用 Google Play 描述向玩家说明对控制器的要求。如果游戏更适合使用带有操纵杆而不是只有方向键的游戏手柄，请明确说明这一点。如果玩家使用了不适合游戏的控制器，很可能无法享受优质游戏体验，进而对游戏做出不利的评价。

使用一致的按钮映射。直观灵活的按钮映射对于提供良好的用户体验十分关键。例如，您应当遵循已被人们广泛接受的习惯，用 A 按钮表示“同意”，用 B 按钮表示“取消”。此外，您还可以通过允许重新映射来提供灵活性。如需详细了解按钮映射，请参阅处理控制器操作。

检测控制器功能并相应做出调整。查询控制器的功能，以优化控制器与游戏的匹配。例如，您可能想让玩家通过在空中挥动控制器来操控一个物体。但是，如果玩家的控制器缺少加速度计和陀螺仪硬件，挥动就不起作用。因此，您的游戏应查询控制器的功能，如果不支持运动检测，则应切换到其他可用的控制方案。如需详细了解如何查询控制器功能，请参阅跨 Android 版本支持控制器。

提供适当的返回按钮行为

返回按钮不应充当开关按钮。例如，请勿将其用于打开和关闭菜单。它应当仅用于通过面包屑导航方式返回到玩家之前所在的屏幕，例如：游戏过程 > 游戏暂停屏幕 > 游戏主屏幕 > Android 主屏幕。

由于返回按钮只应执行线性（向后）导航，您可以使用返回按钮来退出游戏内菜单（通过其他按钮打开）并返回继续玩游戏。如需详细了解导航设计，请参阅返回和向上导航。如需了解实现方式，请参阅提供正确的返回导航。

使用适当的按钮

并非所有游戏控制器都配备开始、搜索或菜单按钮。请确保您的界面不依赖于使用这些按钮。

处理多个控制器

如果多名玩家同时玩一个游戏，且都使用自己的控制器，在这种情况下匹配每一对玩家与控制器十分重要。如需了解如何实现控制器编号标识，请参阅 getControllerNumber()。

处理控制器断开连接事件

如果控制器在游戏进行过程中断开连接，游戏应暂停并显示对话框来提醒断开连接的玩家重新连接其控制器。

此外，对话框还应显示问题排查提示，例如提醒玩家“检查蓝牙连接”的弹出式对话框。如需详细了解如何实现输入设备支持，请参阅处理控制器操作。如需详细了解蓝牙连接，请参阅蓝牙。

显示控制器说明

如果您的游戏提供图形化游戏控制说明，控制器图片应不含品牌信息，并且仅包含与 Android 兼容的按钮。

如需查看与 Android 兼容的控制器的图片示例，请下载 Android TV 游戏手柄模板 (ZIP)。其中包含一个黑色背景上的白色控制器和一个白色背景上的黑色控制器（如图 1 所示），分别以 PNG 文件和 Adobe Illustrator 文件的形式提供。

构建基本 TV 布局

TV 屏幕的通常观看距离约为 10 英尺，尽管其尺寸比大多数其他 Android 设备的显示屏大得多，但这种屏幕不能提供与小型设备相同程度的精确细节和色彩表现。鉴于这些因素，您在设计应用布局时必须谨记它是用于 TV 设备这一点，才能创造出实用并且令人愉悦的用户体验。

本课介绍了构建有效 TV 应用布局的最低要求和实现细节。

您还应该阅读 Android TV 设计。

使用 TV 布局主题背景

Android 主题背景可以为 TV 应用的布局提供基础。您应使用主题背景来修改想要在 TV 设备上运行的应用 Activity 的显示。本部分说明了您应使用哪些主题背景。

Leanback 主题背景

Leanback androidx 库包含 Theme.Leanback，它是 TV Activity 的主题背景，可提供一致的视觉风格。我们强烈建议您将此主题背景用于使用 androidx leanback 类构建的任何 TV 应用。以下代码示例展示了如何将此主题背景应用于 Activity：

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

注意：leanback 主题背景不包含操作栏，因为 Android TV 应用中没有操作栏。如果您的应用使用 BrowseSupportFragment 之类的 Support Fragment，您的 Activity 必须扩展 FragmentActivity。请勿使用 AppCompatActivity，它会尝试设置操作栏的主题背景并产生以下错误：

java.lang.RuntimeException: Unable to start activity ComponentInfo{...} : java.lang.IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity.

NoTitleBar 主题背景

标题栏是手机和平板电脑上 Android 应用的标准界面元素，但它并不适合 TV 应用。如果您未使用 androidx leanback 类，则应将此主题背景应用于您的 TV Activity，以禁止显示标题栏。以下代码示例来自一个 TV 应用清单，演示了如何应用此主题背景来移除标题栏的显示：

    <application>
      ...

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

      </activity>
    </application>
    

构建基本 TV 布局

TV 设备的布局应遵循一些基本准则，以确保其在大屏幕上的易用性和有效性。请按照以下提示来构建针对 TV 屏幕优化的横向布局：

构建屏幕方向为横向的布局。TV 屏幕始终以横屏模式显示。

将屏幕导航控件置于屏幕的左侧或右侧，将节省下的垂直空间留给内容。

利用 Fragment 创建划分为若干部分的界面，并使用 GridView（而非 ListView）等视图组，以更充分地利用屏幕的水平空间。

利用 RelativeLayout 或 LinearLayout 等视图组来布置视图。此方法让系统能够根据 TV 屏幕的尺寸、对齐、宽高比和像素密度来调整视图的位置。

在布局控件之间添加足够的外边距，以避免造成界面杂乱无章。

过扫描

TV 布局有一些独特的要求，因为 TV 标准不断发展演变，并且用户希望 TV 能够始终向观众呈现全屏画面。为此，TV 设备可能会裁剪应用布局的外边缘以确保填满整个显示屏。此行为通常称为“过扫描”。

必须始终对用户可见的屏幕元素应放置在过扫描安全区域内。应在布局的左右边缘添加 48dp 的外边距 (5%)，并在上下边缘添加 27dp 的外边距，这样可确保该布局中的屏幕元素位于过扫描安全区域内。

不应将用户不直接与之交互的背景屏幕元素调整或裁剪到过扫描安全区域。此方法可确保背景屏幕元素在所有屏幕上看起来都正确。

以下示例显示了一个根布局，它可以包含背景元素，还有一个嵌套子布局，它具有 5% 的外边距，并且可以包含过扫描安全区域内的元素：

    <?xml version="1.0" encoding="utf-8"?>
    <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       >

       <!-- Screen elements that can render outside the overscan safe area go here -->

       <!-- Nested RelativeLayout with overscan-safe margin -->
       <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_height="match_parent"
           android:layout_marginTop="27dp"
           android:layout_marginBottom="27dp"
           android:layout_marginLeft="48dp"
           android:layout_marginRight="48dp">

          <!-- Screen elements that need to be within the overscan safe area go here -->

       </RelativeLayout>
    </RelativeLayout>
    

注意：如果您使用 androidx leanback 类（如 BrowseFragment 或相关微件），请勿对布局应用过扫描外边距，因为这些布局已经纳入了过扫描安全外边距。

构建易用的文本和控件

TV 应用布局中的文本和控件应便于从一定距离处进行查看和导航。请按照以下提示让您的界面元素更易于从一定距离处进行查看：

将文本拆分为可让用户快速浏览的小片段。

在深色背景上使用浅色文本。此风格更便于用户查看 TV 上的内容。

避免使用轻量级字体，或者很细的笔划和很粗的笔划兼有的字体。使用简单的 sans-serif 字体和抗锯齿处理来提高可读性。

使用 Android 的标准字号：    <TextView
          android:id="@+id/atext"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:gravity="center_vertical"
          android:singleLine="true"
          android:textAppearance="?android:attr/textAppearanceMedium"/>
    

确保所有视图微件都足够大，对坐在距屏幕 10 英尺远的观众清晰可见（对于尺寸很大的屏幕，这个距离会更远）。实现这一目的的最佳方法是使用布局相对尺寸调整而非绝对尺寸调整，并且使用密度无关像素 (dip) 单位而非绝对像素单位。例如，如需设置微件的宽度，请使用 wrap_content 而非像素度量单位；如需为微件设置边距，请使用 dip 值而非 px 值。

如需详细了解密度无关像素以及如何构建布局来适应更大的屏幕尺寸，请参阅支持多种屏幕。

管理 TV 布局资源

常见的高清 TV 显示屏分辨率为 720p、1080i 和 1080p。您的 TV 布局应以 1920 x 1080 像素的屏幕尺寸为目标，然后允许 Android 系统在必要时将布局元素分辨率缩小到 720p。一般而言，缩小（移除像素）并不会降低布局的呈现质量。不过，放大却可能会导致显示伪影，导致布局质量下降，对应用的用户体验造成不良影响。

如需获得最佳图片缩放效果，请尽可能以九宫格图片元素的形式提供图片。如果您在布局中提供低质量或小尺寸图片，它们将呈现为像素化、失真或颗粒化，给用户带来不良体验。请改用高质量图片。

如需详细了解如何针对大屏幕优化布局和资源，请参阅面向多种屏幕设计。

避免布局反模式

在构建布局时有几种方法应予以避免，因为这些方法在 TV 设备上效果不佳，并且会造成不良用户体验。具体来讲，在开发 TV 布局时，切勿使用下面这些界面开发方法。

重用手机或平板电脑布局 - 请勿不加修改地重用手机或平板电脑应用的布局。专为其他 Android 设备类型构建的布局不太适合 TV 设备，应针对 TV 操作进行相应的简化。

ActionBar - 虽然推荐在手机和平板电脑上使用此常规界面控件，但它并不适合 TV 界面。特别是，我们强烈建议不要使用操作栏选项菜单（或任何作该用途的下拉菜单），因为使用遥控器在此类菜单中进行导航很困难。

ViewPager - 滑动切换屏幕在手机或平板电脑上可能效果极佳，但切勿在 TV 上做此尝试！

如需详细了解如何设计适合 TV 的布局，请参阅 TV 设计指南。

处理大尺寸位图

与其他任何 Android 设备一样，TV 设备的内存也有限。如果您在构建应用布局时使用了分辨率很高的图片，或者在应用的操作方面使用了许多高分辨率图片，可能很快就会遭遇内存限制，并引发内存不足错误。在大多数情况下，我们建议您使用 Glide 库来获取、解码和显示应用中的位图。如需详细了解如何在使用位图时获得最佳性能，请参阅普遍适用的 Android 图形最佳做法。

提供有效广告

对于起居室环境，我们建议您使用全屏且可在 30 秒内关闭的视频广告解决方案。Android TV 上的广告功能（如关闭按钮和点进次数）必须能使用方向键而非通过触摸进行访问。

Android TV 不提供网络浏览器。您的广告不得试图启动网络浏览器或者重定向到未经批准用于 Android TV 设备的 Google Play 商店内容。

创建 TV 导航

TV 设备为应用提供了一组有限的导航控件。能否为您的 TV 应用创建有效的导航架构取决于对这些有限控件的了解，以及用户在操作您的应用时的感知极限。在构建 Android TV 应用时，请特别注意用户实际如何使用遥控器按钮（而非触摸屏）在您的应用内导航。

本节课介绍创建有效 TV 应用导航架构的最低要求，以及如何将这些要求应用于您的应用。

启用方向键导航

在 TV 设备上，用户通过遥控器设备上的控件进行导航，即使用方向键或箭头键来导航。这种类型的控件将移动限定在上、下、左、右四个方向。如需构建一款针对 TV 优化的出色应用，您提供的导航架构必须能让用户快速学会如何利用这些有限的控件在您的应用内导航。

Android 框架会自动处理布局元素之间的方向导航，因此您通常无需对应用执行任何额外的操作。不过，您应该对通过方向键控制器导航进行全面测试，以发现任何导航问题。请遵循以下准则来测试您应用的导航系统是否能够在 TV 设备上与方向键很好地搭配使用：

确保用户可使用方向键控制器导航到屏幕上的所有可见控件。

对于获得焦点的滚动列表，请确保可使用方向键的向上键和向下键滚动列表，并可使用 Enter 键选择列表中的项目。验证用户是否可选择列表中的元素，以及选择元素时是否列表仍会滚动。

确保控件间的切换简单明了并且可以预测。

修改方向导航

Android 框架会根据布局中可聚焦元素的相对位置自动应用方向导航架构。您应使用方向键控制器在您的应用内测试生成的导航架构。测试后，如果您决定希望用户以特定方式在布局中导航，可以为控件设置显式方向导航。

注意：只有在系统应用的默认顺序不太奏效时，才应使用这些属性来修改导航顺序。

以下代码示例展示了如何定义下一个获得 TextView 布局对象焦点的控件：

<TextView android:id="@+id/Category1" android:nextFocusDown="@+id/Category2"\> 

下表列出了 Android 界面微件的所有可用导航属性：

属性功能nextFocusDown定义当用户向下导航时下一个获得焦点的视图。nextFocusLeft定义当用户向左导航时下一个获得焦点的视图。nextFocusRight定义当用户向右导航时下一个获得焦点的视图。nextFocusUp定义当用户向上导航时下一个获得焦点的视图。

如需使用其中一个显式导航属性，请将值设为布局中另一个微件的 ID（android:id 值）。您应将导航顺序设为循环，以便最后一个控件能够指引焦点回到第一个控件。

提供明确的焦点和选择

应用的导航架构能否在 TV 设备上发挥作用取决于用户判定屏幕上获得焦点的界面元素方面的便利性。如果您不能明确指示获得焦点的项目（因此也就无法明确指示用户可以采取操作的项目），用户可能很快就会因失望而退出您的应用。出于同一原因，在您的应用启动后或者处于闲置状态的任何时间，必须始终有获得焦点的项目可供用户采取操作。

您的应用布局和实现应使用颜色、尺寸和动画其中之一或组合使用这些属性来帮助用户轻松判定他们接下来可以采取的操作。应使用统一方案在整个应用内指示焦点。

Android 提供了可绘制对象状态列表资源来实现针对获得焦点的控件和选定控件的突出显示。以下代码示例演示了如何通过为按钮启用视觉行为来指示用户已导航到该控件而且随后还选择了它：

<!-- res/drawable/button.xml --> <?xml version="1.0" encoding="utf-8"?> <selector xmlns:android="http://schemas.android.com/apk/res/android"> <item android:state_pressed="true" android:drawable="@drawable/button_pressed" /> <!-- pressed --> <item android:state_focused="true" android:drawable="@drawable/button_focused" /> <!-- focused --> <item android:state_hovered="true" android:drawable="@drawable/button_focused" /> <!-- hovered --> <item android:drawable="@drawable/button_normal" /> <!-- default --> </selector> 

以下布局 XML 示例代码会将上一状态列表可绘制对象应用于 Button：

<Button android:layout_height="wrap_content" android:layout_width="wrap_content" android:background="@drawable/button" /> 

请务必在可聚焦控件和可选择控件内提供足够的内边距，以使其周围的突出显示元素清晰可见。

如需了解有关为 TV 应用设计有效选择和焦点的更多建议，请参阅适用于 Android TV 的设计。