管理电视控制器

电视设备需要一个辅助硬件设备来与应用交互——一个基本的遥控器或游戏控制器。因此，您的应用必须支持方向键（D-pad）输入。此外，您的应用可能需要处理控制器离线以及来自多种类型控制器的输入。

本指南讨论了处理电视设备控制器的要求。

D-pad 最小控件

电视设备的默认控制器是 D-pad。通常情况下，您的应用必须能够通过仅具有上、下、左、右、选择、返回和主页按钮的遥控器进行操作。如果您的应用是一款通常需要带有附加控件的游戏控制器的游戏，请尝试仅使用这些 D-pad 控件来支持游戏玩法。否则，警告用户需要控制器，并允许他们使用 D-pad 控制器优雅地退出游戏。

有关使用电视设备的 D-pad 控制器进行导航的更多信息，请参阅电视导航。

处理控制器断开连接

电视的控制器通常是蓝牙设备，它们可能会尝试通过定期进入睡眠模式并从电视设备断开连接来节省电量。这意味着如果应用未配置为处理这些重新连接事件，则可能会中断或重新启动应用。这些事件可能发生在以下任何情况下：

播放时长几分钟的视频时，D-pad 或游戏控制器可能会进入睡眠模式，与电视设备断开连接，然后稍后重新连接。
在游戏过程中，新玩家可以使用尚未连接的游戏控制器加入游戏。
在游戏过程中，玩家可能会离开游戏并断开游戏控制器的连接。

任何容易发生断开和重新连接事件的电视应用活动都必须配置为在应用清单中处理重新连接事件。以下代码示例演示了如何使活动能够处理配置更改，包括键盘或导航设备的连接、断开连接或重新连接。

<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 框架重新启动，这并非良好的用户体验。

处理 D-pad 输入变化

电视设备用户可能拥有多种类型的控制器，他们可以使用这些控制器与电视互动。例如，用户可能同时拥有基本的 D-pad 控制器和游戏控制器。游戏控制器在用于 D-pad 功能时提供的键码可能与基本 D-pad 发送的键码有所不同。

处理 D-pad 输入的变化，以便用户无需切换控制器即可操作您的应用。有关处理输入变化的更多信息，请参阅处理方向键输入。

处理按钮事件

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

电视 UI 事件

为生成如下表所示的 KeyEvent 类型的按钮分配电视 UI 行为

`KeyEvent`	行为
`KEYCODE_BUTTON_B`，`KEYCODE_BACK`	返回
`KEYCODE_BUTTON_SELECT`，`KEYCODE_BUTTON_A`，`KEYCODE_ENTER`，`KEYCODE_DPAD_CENTER`，`KEYCODE_NUMPAD_ENTER`	选择
`KEYCODE_DPAD_UP`，`KEYCODE_DPAD_DOWN`，`KEYCODE_DPAD_LEFT`，`KEYCODE_DPAD_RIGHT`	导航

媒体事件

当用户观看媒体时，请为生成如下表所示KeyEvent类型的按钮分配行为。如果您的应用正在控制一个MediaSession，请使用MediaControllerAdapter调用表中所示的MediaControllerCompat.TransportControls方法之一。请注意，在此上下文中，选择按钮充当播放或暂停按钮。

`KeyEvent`	TransportControls 调用	行为
`BUTTON_SELECT`、`BUTTON_A`、`ENTER`、`DPAD_CENTER`、`KEYCODE_NUMPAD_ENTER`	`play()`	播放
`BUTTON_START`、`BUTTON_SELECT`、`BUTTON_A`、`ENTER`、`DPAD_CENTER`、`KEYCODE_NUMPAD_ENTER`	`pause()`	暂停
`BUTTON_R1`	`skipToNext()`	跳到下一项
`BUTTON_L1`	`skipToPrevious()`	跳到上一项
`DPAD_RIGHT`、`BUTTON_R2`、`AXIS_RTRIGGER`、`AXIS_THROTTLE`	`fastForward()`	快进
`DPAD_LEFT`、`BUTTON_L2`、`AXIS_LTRIGGER`、`AXIS_BRAKE`	`rewind()`	倒回
N/A	`stop()`	停止

注意：使用MediaSession时，请不要覆盖媒体专用按钮（例如KEYCODE_MEDIA_PLAY或KEYCODE_MEDIA_PAUSE）的处理。系统会自动触发相应的MediaSession.Callback方法。

提供合适的返回按钮行为

返回按钮绝不能充当切换按钮。例如，不要使用它同时打开和关闭菜单。仅使用它以面包屑式的方式向后浏览播放器之前所在的屏幕。

由于返回按钮仅执行线性的向后导航，因此您可以使用它离开由其他按钮打开的应用内菜单并返回应用。连续按下返回按钮最终必须始终导向 Android TV 主屏幕。例如：游戏画面 > 游戏暂停屏幕 > 游戏主屏幕 > Android TV 主屏幕，或电视剧播放 > 电视应用主屏幕 > Android TV 主屏幕。

有关导航设计的更多信息，请参阅设计返回和向上导航。要了解实现方法，请参阅提供正确的返回导航。

处理游戏控制器

支持方向键控制

请围绕方向键控制规划您的控制方案，因为这是 Android TV 设备的默认控制设置。玩家需要能够使用方向键控制游戏的各个方面，不仅包括核心游戏玩法，还包括导航菜单和广告。因此，请确保您的 Android TV 游戏不会使用“点击此处继续”之类的语言来提及触摸界面。

您塑造玩家与控制器的交互方式可能是获得出色用户体验的关键。请考虑以下最佳实践

提前沟通控制器要求：使用您的 Google Play 说明向玩家传达对控制器的任何期望。如果游戏更适合使用带操纵杆的游戏手柄而不是仅带方向键的游戏手柄，请明确说明这一点。使用不合适的控制器玩游戏的玩家可能会体验不佳，并给您的游戏打低分。
使用一致的按钮映射：直观的按钮映射是良好用户体验的关键。例如，请遵守公认的习惯，使用 A 按钮“确认”，使用 B 按钮“取消”。您还可以通过可重新映射性来提供灵活性。有关按钮映射的更多信息，请参阅处理控制器操作。
检测控制器功能并相应调整：查询控制器的功能以优化控制器和游戏之间的匹配。例如，您可能打算让玩家通过在空中挥动控制器来操纵物体，但是如果玩家的控制器缺少加速度计和陀螺仪硬件，则挥动不起作用。查询控制器，如果不支持运动检测，则切换到可用的替代控制方案。有关查询控制器功能的更多信息，请参阅跨 Android 版本支持控制器。

使用合适的按钮

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

处理多个控制器

当多名玩家使用各自的控制器玩游戏时，务必映射每个玩家-控制器对。有关如何实现控制器编号识别的信息，请参阅 getControllerNumber()。

处理控制器断开连接

当控制器在游戏过程中断开连接时，请暂停游戏并显示一个对话框，提示断开连接的玩家重新连接其控制器。

此外，在对话框中提供故障排除提示。例如，告诉玩家“检查您的蓝牙连接”。有关实现输入设备支持的更多信息，请参阅处理控制器操作和蓝牙概述。

显示控制器说明

如果您的游戏提供视觉游戏控制说明，请使用不含品牌标识的控制器图片，并且仅包含与 Android 兼容的按钮。

要获取与 Android 兼容的控制器的示例图片，请下载Android TV 游戏手柄模板 (ZIP)。它包含黑色背景上的白色控制器和白色背景上的黑色控制器（如图 1 所示），以 PNG 文件和 Adobe® Illustrator® 文件的形式提供。

图 1. 使用 Android TV 游戏手柄模板的控制器说明示例。

处理电视硬件

屏幕键盘