游戏控制器支持
＃＃ 大纲
在 SDK 提供的 UI 中，您可以使用“游戏控制器”而不是常规鼠标来移动鼠标光标并单击按钮。例如，在SDK公开的webview区域中，用户可以使用游戏控制器移动鼠标光标并单击webview区域内的按钮。
Note
从以下 SDK 版本开始可使用“游戏控制器”功能。
-
Hive SDK v4 Unity Windows 24.1.0 或更高版本
- Hive SDK v4 Android 26.7.0 或更高版本
支持的游戏控制器{ #supported-controller }¶
SDK支持的游戏手柄类型如下，每个SDK可使用的手柄数量**最多1**。
-
微软 Xbox 控制器
-
索尼 PlayStation DualSense、DualShock 控制器
-
任天堂 Switch Pro 控制器
控制器按键映射{ #controller-keymapping }¶
从以下 Hive SDK 版本开始，某些 UI 在使用游戏控制器时支持控制器键映射。
-
Hive SDK v4 Unity Windows 25.0.0 或更高版本
-
Hive SDK v4 Android 26.7.0 或更高版本
Warning
请注意，在支持控制器按键映射的 UI 中，[按键操作方法] (#key) 与现有 UI 中的按键操作方法不同。
Note
在不单独支持控制器键映射的 UI 中，鼠标光标暴露在屏幕上，并且通过移动光标使用游戏控制器控制 UI。
按键操作方法{ #key }¶
检查| 输入设备 | 现有UI按键操作方法 | 控制器按键映射支持UI按键操作方法 |
| 左模拟操纵杆 | 移动鼠标光标 | 移动焦点 |
| 右模拟操纵杆 | 鼠标垂直和水平滚轮滚动 | 鼠标垂直和水平滚轮滚动 |
| A按钮 | 单击鼠标左键 | （用于 Dual Sense 或 Dual Shock 的 X 按钮） |
| B按钮 | 不支持 | 取消（O 按钮用于 Dual Sense 或 Dual Shock） |
| 方向键 | 不支持 | 移动焦点 |
控制器按键映射支持 UI 列表{ #key-mapping-ui-list }¶
以下是支持控制器按键映射功能的 UI 列表：
登录 输入验证码| 支持的 UI | SDK v4 Unity Windows 支持 | SDK v4 Android 支持 | |
| 1 | 应用程序更新 | 支持 | 支持 |
| 2 | 访问限制 | 支持 | 支持 |
| 3 | 服务器检查 | 支持 | 支持 |
| 4 | 等待登录 | 支持 | - |
| 5 | IdP 列表 | 支持 | - |
| 6 | 帐户冲突 | - | 支持 |
| 7 | 促销横幅 | 支持 | 支持（前横幅） |
| 8 | 促销评论弹出窗口 | - | 支持 |
| 9 | 促销结束弹出窗口 | - | 支持 |
| 10 | 检查 Google 付款帐户 | 支持 | - |
| 11 | 付款确认 | 支持 | - |
| 12 | 付款错误 | 支持 | - |
| 13 | 还款 | - | 支持 |
| 14 | Steam 甲板登录 | 支持 | - |
| 15 | 支持 | - | |
| 16 | 查找密码 | 支持 | - |
| 17 | 支持 | - | |
| 18 | 查找电子邮件 | 支持 | - |
| 19 | 休眠账户信息 | 支持 | - |
| 20 | Analytics 同意屏幕 | - | 支持 |
注意事项（平台通用）{ #notes_all_platform }¶
将“游戏控制器”应用到 SDK 时，必须牢记以下几点。
游戏控制器运动范围¶
游戏控制器仅在使用SDK 实现的 UI 中支持。例如，SDK 在游戏中显示的 Web 视图 UI，例如登录屏幕、新闻和促销横幅等。对于非 SDK 实现的 UI，例如外部浏览器窗口，不支持它。游戏中使用游戏控制器的鼠标光标移动必须由开发人员直接实现。
注意（Windows）{ #notes_windows_platform }¶
Steam 集成¶
如果您在连接Steam时设置了“启用Steam输入”，您将无法使用SDK提供的游戏控制器功能。然而，通过改变Steam提供的布局，可以提供类似于SDK提供的游戏控制器功能的环境。欲了解更多信息，请参阅Steamworks官方文档中的[Steam输入页面]（https://partner.steamgames.com/doc/features/steam_controller）。
以传统方式处理控制器输入¶
如果在应用程序调用 SDK 方法之后且在收到响应之前发生游戏控制器输入（包括 Steam Deck 自己的控制器），则应用程序本身不得处理游戏控制器输入。 这是因为 SDK 处理发生在 SDK 实现的 UI 上的游戏控制器输入。
Windows 屏幕键盘¶
在 Windows 屏幕键盘中使用 SDK 提供的游戏控制器支持功能时，必须在 Windows 屏幕键盘“选项”中进行以下设置才能使用游戏控制器功能。
1.勾选**扫描并输入**
- 仅检查**使用操纵杆、游戏手柄或其他游戏设备**
控制器按键映射功能的限制¶
应用了控制器按键映射功能的 UI 仅在 Rog Ally > **游戏手柄模式**下正常工作。
注意（Android）{ #notes_android_platform }¶
Android操作系统虚拟键盘控制限制¶
通过使用游戏控制器在 UI 中选择文本输入字段而暴露的 Android 操作系统虚拟键盘无法使用游戏控制器进行操作。启用虚拟键盘后，您必须直接触摸屏幕才能输入文本。
游戏控制器运动范围¶
Hive SDK 的游戏控制器功能仅在直接使用 SDK 实现的 UI 区域中受支持。
如下所示，通过 Hive SDK 将自身暴露在外部模块和系统区域中的 UI 排除在游戏控制器控制之外。
-
外部库集成UI：外部IdP登录屏幕、支付（IAP）弹出窗口、内容共享弹出窗口等。
-
外部浏览器和网页视图：应用内浏览器和外部系统浏览器
已知问题{ #issues }¶
如果您反复快速尝试重新连接游戏控制器，控制器可能会表现异常。例如，在Switch Pro控制器的情况下，如果在短时间内重复断开和连接，则即使用户不进行操作，鼠标光标也可能会向某个方向移动。这是 Switch Pro 控制器问题，如果出现问题，可以通过按有线连接终端左侧的同步按钮来解决。