管理 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 事件。该按钮的预期行为可能是媒体事件(如播放、暂停或停止),也可能是电视类型的事件(如选择或导航)。为了提供良好的用户体验,请为控制器按钮指定一致的行为。

TV 界面事件

将 TV 界面行为分配给生成 KeyEvent 类型的按钮,如下表所示:

KeyEvent行为
KEYCODE_BUTTON_BKEYCODE_BACK返回
KEYCODE_BUTTON_SELECTKEYCODE_BUTTON_AKEYCODE_ENTERKEYCODE_DPAD_CENTERKEYCODE_NUMPAD_ENTER选择
KEYCODE_DPAD_UPKEYCODE_DPAD_DOWNKEYCODE_DPAD_LEFTKEYCODE_DPAD_RIGHT导航

媒体事件

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

KeyEventTransportControls 调用行为
BUTTON_SELECTBUTTON_AENTERDPAD_CENTERKEYCODE_NUMPAD_ENTER play()播放
BUTTON_STARTBUTTON_SELECTBUTTON_AENTERDPAD_CENTERKEYCODE_NUMPAD_ENTER pause()暂停
BUTTON_R1skipToNext()跳到下一个
BUTTON_L1skipToPrevious()跳到上一个
DPAD_RIGHTBUTTON_R2AXIS_RTRIGGERAXIS_THROTTLEfastForward()快进
DPAD_LEFTBUTTON_L2AXIS_LTRIGGERAXIS_BRAKErewind()快退
不适用stop()停止

注意:使用 MediaSession 时,请勿替换媒体专用按钮(例如 KEYCODE_MEDIA_PLAYKEYCODE_MEDIA_PAUSE)的处理方式。 系统会自动触发相应的 MediaSession.Callback 方法。

提供适当的返回按钮行为

返回按钮不得用作切换开关。例如,请勿同时使用它打开和关闭菜单。仅用于以面包屑导航方式向后导航,通过播放器之前访问过的屏幕。

由于返回按钮仅执行线性的向后导航,因此您可以使用该按钮让其他按钮打开的应用内菜单并返回应用。连续按返回按钮最终必须始终转到 Android TV 主屏幕。例如:游戏开始 > 游戏暂停屏幕 > 游戏主屏幕 > Android TV 主屏幕或电视节目播放 > TV 应用主屏幕 > Android TV 主屏幕。

如需详细了解导航设计,请参阅 设计返回和向上导航。如需了解实现方式,请参阅提供正确的返回导航

处理游戏控制器

支持方向键控制

围绕方向键控件规划您的控制方案,因为此控件集是 Android TV 设备的默认控件。玩家需要能够使用方向键来完成游戏的各个方面 - 不仅能够控制核心游戏内容,还能浏览菜单和广告。因此,请确保您的 Android TV 游戏未引用使用“点按此处以继续”等语言的触摸界面。

如何设计玩家与控制器的互动对于实现出色的用户体验至关重要。请考虑以下最佳实践:

  • 提前说明控制器要求:使用 Google Play 说明向玩家告知对控制器的任何预期。如果游戏更适合使用带有操纵杆的游戏手柄,而不是只使用方向键,请明确说明这一点。如果玩家使用不合适的控制器玩游戏,可能会获得糟糕的体验,从而给游戏打分。
  • 使用一致的按钮映射:直观的按钮映射是提供良好用户体验的关键。例如,使用 A 按钮表示接受,使用 B 按钮取消,以遵守接受的海关要求。您还可以通过重新映射提供灵活性。如需详细了解按钮映射,请参阅处理控制器操作
  • 检测控制器功能并相应调整:向控制器查询其功能,以优化控制器与游戏之间的匹配。例如,您可能想让玩家通过在空中挥动控制器来操控某个对象,但如果玩家的控制器缺少加速度计和陀螺仪硬件,挥动就不起作用。 查询控制器,如果不支持移动侦测,则切换到其他可用的控制方案。如需详细了解如何查询控制器功能,请参阅跨 Android 版本支持控制器

使用适当的按钮

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

处理多个控制器

如果多位玩家同时玩一个游戏,且各自都有自己的控制器,请务必映射每一对玩家-控制器。如需了解如何实现控制器编号标识,请参阅 getControllerNumber()

处理控制器断开连接事件

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

同时,在对话框中提供问题排查提示。例如,告诉播放器“检查蓝牙连接”。如需详细了解如何实现输入设备支持,请参阅处理控制器操作蓝牙概览

显示控制器说明

如果您的游戏提供直观的游戏控制说明,请使用不含品牌信息的控制器图片,并且仅包含与 Android 兼容的按钮

如需查看 Android 兼容控制器的图片示例,请下载 Android 电视游戏手柄模板 (ZIP)。它包括一个黑色背景上的白色控制器和一个白色背景上的黑色控制器(如图 1 所示),以 PNG 文件和 Adobe® Illustrator® 文件的形式提供。

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