TV 设备需要使用辅助硬件设备（基本遥控器、指针遥控器或游戏控制器）与应用进行交互。 为了提供一致的用户体验，您的应用必须支持方向键 (D-pad) 输入、处理控制器离线的情况，并支持多种控制器类型（包括指针遥控器）的输入。
方向键基本控制按钮
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 框架重启，从而提供良好的用户体验。
处理方向键输入变化
电视设备用户可能会使用多种类型的控制器来控制电视。例如，用户可能拥有基本方向键控制器、指针遥控器或游戏控制器。游戏控制器用于方向键功能时提供的按键代码可能与基本方向键发送的按键代码不同。
处理方向键输入的变化，让用户无需切换控制器即可操作您的应用。如需详细了解如何处理输入变化，请参阅处理方向键输入。
支持指针遥控器
某些电视设备支持指针遥控器，例如空中鼠标或带有触控方向键（触控板）的遥控器。支持指针遥控器后，用户可以使用指向并点击、悬停、滑动和拖动手势与您的应用互动，从而在兼容的硬件上提供更流畅的体验，同时保持与方向键的完全兼容。
在清单中声明指针遥控器支持
如需指明您的应用可通过指针和触控输入进行导航，请在应用清单中将 <application> 元素（或各个 <activity> 元素，以便为每个 activity 配置支持）内的 android.software.leanback.supports_touch
<property> 设置为 true：
<manifest ...>
<!-- Signal whether the app is adaptive or built just for TV -->
<uses-feature
android:name="android.software.leanback"
android:required="true|false" />
<!-- Ensure the app can be installed on conventional TVs -->
<uses-feature
android:name="android.hardware.touchscreen"
android:required="false" />
<application ...>
<!-- Signal whether the app supports pointer remotes -->
<property
android:name="android.software.leanback.supports_touch"
android:value="true" />
...
</application>
</manifest>
支持点击、悬停和滚动互动
支持指针遥控器时，请确保界面组件在以下互动中对光标和触控输入做出适当响应：
- 点击和选择：所有可聚焦、可选择的界面元素都必须可通过指针遥控器点击，这与方向键选择 (
KEYCODE_DPAD_CENTER) 的行为一致。 - 视觉悬停状态：提供清晰的视觉悬停效果，以指示指针光标何时位于可选项上。
- 滑动和快速滑动滚动：在触敏式方向键中心按钮上通过滑动或快速滑动触发的水平和垂直滚动必须在所有可滚动内容中顺畅运行。
- 拖动滚动：用户必须能够通过拖动在可滚动容器中垂直（上下）或水平（左右）滚动。
- Jetpack Compose：标准可滚动容器默认支持指针和触控滚动。如需了解自定义实现，请参阅 Compose 中的指针输入。
- 视图：标准可滚动视图默认支持触控滚动。如需了解自定义输入处理，请参阅轻触和输入。
- 媒体播放拖动：在媒体播放（例如电视节目和电影）期间，用户必须能够与播放进度条（拖动条）互动，通过指向并点击来跳转到过去或未来的时间戳，以及沿着进度条拖动（拖动）以跳转到特定时间。
处理按钮事件
当用户点击控制器上的按钮时，您的应用会收到一个包含 KeyEvent 的事件。按钮的预期行为可能是媒体事件（例如播放、暂停或停止），也可能是电视类型事件（例如选择或导航）。为了提供良好的用户体验，请为控制器按钮分配一致的行为。
TV 界面事件
为生成 KeyEvent 类型的按钮分配 TV 界面行为，如下表所示：
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() |
快退 |
| 不适用 | stop() |
停止 |
提供适当的返回按钮行为
返回按钮绝不能用作切换开关。例如，请勿同时使用它来打开和关闭菜单。仅用于以面包屑导航的方式向后导航，浏览玩家之前访问过的屏幕。
由于“返回”按钮仅执行线性向后导航，因此您可以使用它退出由其他按钮打开的应用内菜单，并返回到应用。连续按“返回”按钮最终必须始终返回到 Android TV 主屏幕。例如：游戏内容 > 游戏暂停界面 > 游戏主界面 > Android TV 主屏幕，或电视节目播放 > TV 应用主界面
Android TV 主屏幕。
如需详细了解导航设计，请参阅设计“返回”和“向上”导航。如需了解实现，请参阅提供正确的返回导航。
处理游戏控制器
为 Android TV 构建游戏时，请设计可同时与标准电视遥控器和专用游戏控制器搭配使用的控制方案。
支持方向键控制
请围绕方向键控件规划控制方案，因为此控件集是 Android TV 设备的默认控件。玩家需要能够使用方向键来控制游戏的所有方面，不仅包括控制核心游戏内容，还包括浏览菜单和广告。因此，请确保您的 Android TV 游戏不会使用“点按此处继续”等语言来指代触摸界面。
如何塑造玩家与控制器的互动，可能是实现出色用户体验的关键。不妨参考下面的最佳实践：
- 提前告知控制器要求：使用 Google Play 说明向玩家告知有关控制器的任何预期。如果游戏更适合使用带摇杆的游戏手柄，而不是仅带方向键的游戏手柄，请明确说明。如果玩家在游戏中使用不合适的控制器，可能会获得糟糕的体验，并给您的游戏差评。
- 使用一致的按键映射：直观的按键映射是提供良好用户体验的关键。例如，遵循公认的习惯，使用 A 按钮接受，使用 B 按钮取消。您还可以允许用户重新映射按钮，从而提供灵活性。如需详细了解按钮映射，请参阅处理控制器操作。
- 检测控制器功能并进行相应调整：查询控制器的功能，以优化控制器与游戏之间的匹配。例如，您可能希望玩家通过在空中挥动手柄来控制物体，但如果玩家的手柄缺少加速度计和陀螺仪硬件，挥动操作就无法生效。查询控制器，如果不支持移动侦测，请切换到其他可用的控制方案。如需详细了解如何查询控制器功能，请参阅支持各种 Android 版本的控制器。
使用适当的按钮
并非所有游戏控制器都配备开始、搜索或菜单按钮。请确保您的界面不依赖于这些按钮的使用。
处理多个控制器
当多个玩家玩游戏时，每个玩家都有自己的控制器，因此请务必映射每个玩家-控制器对。如需了解如何实现控制器编号标识，请参阅 getControllerNumber()。
处理控制器断开连接事件
当控制器在游戏过程中断开连接时，请暂停游戏并显示一个对话框，提示断开连接的玩家重新连接其控制器。
此外，还应在对话框中提供问题排查提示。例如，告知玩家“检查蓝牙连接”。如需详细了解如何实现输入设备支持，请参阅处理控制器操作和蓝牙概览。
显示控制器说明
如果您的游戏提供直观的游戏控制说明，请使用不含品牌标识且仅包含与 Android 兼容的按钮的控制器图片。
如需查看与 Android 兼容的控制器的示例图片，请下载 Android TV 游戏手柄模板 (ZIP)。它包含黑色背景上的白色控制器和白色背景上的黑色控制器（如图 1 所示），并提供 PNG 文件和 Adobe® Illustrator® 文件。
