管理电视控制器

电视设备需要辅助硬件设备才能与应用交互,例如基本遥控器或游戏控制器。因此,您的应用必须支持方向键 (D-pad) 输入。此外,您的应用可能还需要处理控制器离线和来自多种类型控制器的输入。

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

方向键 (D-pad) 最低控制要求

电视设备的默认控制器是方向键 (D-pad)。通常,您的应用必须可以通过仅包含上、下、左、右、选择、返回和主页按钮的遥控器进行操作。如果您的应用是一款通常需要额外控制的游戏控制器才能玩的游戏,请尝试仅使用这些方向键控件来支持游戏玩法。否则,请警告用户需要控制器,并允许他们使用方向键控制器正常退出游戏。

有关使用方向键控制器进行电视设备导航的更多信息,请参阅电视导航

处理控制器断开连接

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

  • 当播放数分钟长的视频时,方向键或游戏控制器可能会进入睡眠模式,与电视设备断开连接,稍后又重新连接。
  • 在游戏过程中,新玩家可能会使用尚未连接的游戏控制器加入游戏。
  • 在游戏过程中,玩家可能会退出游戏并断开游戏控制器。

任何受断开连接和重新连接事件影响的电视应用 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 框架重启,后者会影响用户体验。

处理方向键 (D-pad) 输入变化

电视设备用户可能会拥有不止一种用于电视的控制器。例如,用户可能同时拥有基本方向键控制器和游戏控制器。游戏控制器在用于方向键功能时提供的按键代码可能与基本方向键发送的按键代码不同。

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

处理按钮事件

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

电视 UI 事件

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

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 主屏幕,或者电视节目播放 > 电视应用主屏幕 > Android TV 主屏幕。

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

处理游戏控制器

支持方向键 (D-pad) 控制

围绕方向键 (D-pad) 控制规划您的控制方案,因为此控制集是 Android TV 设备的默认设置。玩家需要能够使用方向键来控制游戏的所有方面,不仅包括核心游戏玩法,还包括导航菜单和广告。因此,请确保您的 Android TV 游戏不要使用诸如“轻触此处以继续”之类的语言来指代触控界面。

您如何塑造玩家与控制器的交互是实现卓越用户体验的关键。请考虑以下最佳实践

  • 提前说明控制器要求:使用您的 Google Play 说明,向玩家说明对控制器的任何预期。如果游戏更适合带摇杆的游戏手柄,而不是仅带方向键的游戏手柄,请务必明确说明。使用不适合游戏的控制器的玩家可能会获得糟糕的体验,并给您的游戏差评。
  • 使用一致的按钮映射:直观的按钮映射是良好用户体验的关键。例如,遵循公认的习惯,使用 A 按钮表示接受,使用 B 按钮表示取消。您还可以通过可重新映射的形式提供灵活性。有关按钮映射的更多信息,请参阅处理控制器操作
  • 检测控制器功能并进行相应调整:查询控制器的功能,以优化控制器和游戏之间的匹配。例如,您可能希望玩家通过在空中挥舞控制器来控制物体,但如果玩家的控制器缺乏加速度计和陀螺仪硬件,则挥舞将不起作用。查询控制器,如果不支持运动检测,则切换到替代的可用控制方案。有关查询控制器功能的更多信息,请参阅支持跨 Android 版本的控制器

使用适当的按钮

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

处理多个控制器

当多个玩家玩游戏时,每个玩家都有自己的控制器,重要的是要映射每个玩家-控制器对。有关如何实现控制器编号识别的信息,请参阅 getControllerNumber()

处理控制器断开连接

当控制器在游戏过程中断开连接时,暂停游戏并显示对话框,提示断开连接的玩家重新连接他们的控制器。

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

显示控制器说明

如果您的游戏提供视觉游戏控制说明,请使用无品牌标识的控制器图像,并且只包含与 Android 兼容的按钮

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

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