电视设备需要一个辅助硬件设备（基本遥控器、指针遥控器或游戏控制器）来与应用互动。为了提供一致的用户体验，您的应用必须支持方向键 (D-pad) 输入、处理控制器离线情况，并支持来自多种控制器类型（包括指针遥控器）的输入。
方向键基本控制按钮
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 框架重新启动，这样可带来更好的用户体验。
处理方向键输入变化
电视设备用户可能会使用多种类型的控制器来控制电视。例如，用户可能拥有基本方向键控制器、指针遥控器或游戏控制器。游戏控制器用于方向键功能时提供的键码可能与基本方向键发送的键码不同。
处理方向键输入的变化，以便用户无需切换控制器即可操作您的应用。如需详细了解如何处理输入变化，请参阅处理方向键输入。
支持指针遥控器
某些电视设备支持指针遥控器，例如空中鼠标或带有触控式方向键（触控板）的遥控器。支持指针遥控器后，用户可以使用点击、悬停、滑动和拖动手势与应用互动，从而在兼容的硬件上获得更流畅的体验，同时保持完整的方向键兼容性。
在清单中声明指针遥控器支持
如需表明您的应用可通过指针和触控输入进行导航，请将应用清单配置为 android.software.leanback.supports_touch 元数据设置为 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" />
<!-- Signal whether the app supports pointer remotes -->
<meta-data
android:name="android.software.leanback.supports_touch"
android:value="true" />
<application ...>
...
</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 主屏幕；或电视节目播放 > 电视应用主界面
Android TV 主屏幕。
如需详细了解导航设计，请参阅设计“返回”和“向上”导航。如需了解实现，请参阅提供适当的返回导航。
处理游戏控制器
为 Android TV 构建游戏时，请设计可同时使用标准电视遥控器和专用游戏控制器的控制方案。
支持方向键控制
围绕方向键控制方案规划您的控制方案，因为此控制方案是 Android TV 设备的默认控制方案。玩家需要能够使用方向键来完成游戏的所有操作，不仅包括控制核心游戏内容，还包括浏览菜单和广告。因此，请确保您的 Android TV 游戏不会使用“点按此处继续”之类的语言来指代触摸界面。
您如何塑造玩家与控制器的互动对于实现出色的用户体验至关重要。不妨参考下面的最佳实践：
- 提前说明控制器要求：使用 Google Play 说明向玩家说明对控制器的任何预期。如果某款游戏更适合使用带操纵杆的游戏手柄，而不是只带方向键的游戏手柄，请明确说明这一点。如果玩家使用的控制器不适合某款游戏，可能会获得糟糕的体验，并给您的游戏打低分。
- 使用一致的按钮映射：直观的按钮映射是良好用户体验的关键。例如，遵循公认的惯例，使用 A 按钮接受，使用 B 按钮取消。您还可以允许用户重新映射按钮，从而提供灵活性。如需详细了解按钮映射，请参阅处理控制器操作。
- 检测控制器功能并进行相应调整：查询控制器的功能，以优化控制器与游戏之间的匹配。例如，您可能希望玩家通过在空中挥动手柄来操控对象，但如果玩家的手柄缺少加速度计和陀螺仪硬件，挥动手柄就无法实现操控。查询控制器，如果不支持移动侦测，则切换到可用的替代控制方案。如需详细了解如何查询控制器功能，请参阅支持各种 Android 版本的控制器。
使用适当的按钮
并非所有游戏控制器都配备开始、搜索或菜单按钮。请确保您的界面不依赖于这些按钮的使用。
处理多个控制器
当多位玩家使用各自的控制器玩游戏时，务必要为每位玩家-控制器对进行映射。如需了解如何实现控制器编号识别，请参阅 getControllerNumber()。
处理控制器断开连接事件
当控制器在游戏过程中断开连接时，暂停游戏并显示一个对话框，提示断开连接的玩家重新连接控制器。
此外，还会在对话框中提供问题排查提示。例如，让播放器“检查蓝牙连接”。如需详细了解如何实现输入设备支持，请参阅处理控制器操作和 Bluetooth 概览。
显示控制器说明
如果游戏提供直观的游戏控制说明，请使用不含品牌信息的控制器图片，并且仅包含与 Android 兼容的按钮。
如需查看与 Android 兼容的控制器的示例图片，请下载 Android TV 游戏手柄模板 (ZIP)。它包含一个黑色背景上的白色控制器和一个白色背景上的黑色控制器（如图 1 所示），以 PNG 文件和 Adobe® Illustrator® 文件的形式提供。
