> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GameInput API 成员

> GameInput

# GameInput

GameInput API 用于从各种设备（例如游戏控制器、飞行摇杆、赛车方向盘和触摸输入）捕获人机输入。

> [!NOTE]
>
> 此页面记录当前（最新）的 GameInput API。每个成员的版本历史都记录在各自的参考页面中。仅存在于较旧 API 版本中的成员列在下面的 [已移除的成员](#removed-members) 部分。请注意，API 的较新运行时支持所有可用版本的 API，因此仍可以将已移除的成员与较旧版本的头文件一起使用。

## 接口

| 接口 | 说明 |
| - | - |
| [IGameInputDevice](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice.md) | 定义输入设备。 |
| [IGameInputDispatcher](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/IGameInputDispatcher/igameinputdispatcher.md) | 提供对由 GameInput API 管理的后台任务调度的手动控制。 |
| [IGameInputForceFeedbackEffect](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputforcefeedbackeffect/igameinputforcefeedbackeffect.md) | 描述兼容输入设备上的力反馈效果。 |
| [IGameInputMapper](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputmapper/igameinputmapper.md) | 提供关于 GameInput 如何映射设备的信息。 |
| [IGameInputRawDeviceReport](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputrawdevicereport/igameinputrawdevicereport.md) | 表示传递给输入设备或来自输入设备的原始字节缓冲区。 |
| [IGameInputReading](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md) | 包含单次输入更新的数据。 |
| [IGameInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/igameinput.md) | 提供对设备输入流访问的每进程单例。 |

## 函数

| 函数 | 说明 |
| - | - |
| [GameInputCreate](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputcreate.md) | 检索 IGameInput 接口的实例。 |
| [GameInputDeviceCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputdevicecallback.md) | 定义设备连接和断开事件的回调。 |
| [GameInputKeyboardLayoutCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputkeyboardlayoutcallback.md) | 定义键盘布局更改事件的回调。 |
| [GameInputReadingCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputreadingcallback.md) | 定义新读数到达事件的回调。 |
| [GameInputSystemButtonCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputsystembuttoncallback.md) | 定义 Guide 或 Share 按钮按下和释放事件的回调。 |

## 结构

| 结构 | 说明 |
| - | - |
| [GameInputArcadeStickInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputarcadestickinfo.md) | 详细描述街机摇杆的特性。 |
| [GameInputArcadeStickState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputarcadestickstate.md) | 提供街机摇杆的当前状态。 |
| [GameInputAxisMapping](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputaxismapping.md) | 描述某个轴如何映射到控制器。 |
| [GameInputButtonMapping](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputbuttonmapping.md) | 描述某个按钮如何映射到控制器。 |
| [GameInputControllerInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputcontrollerinfo.md) | 详细描述控制器的特性。 |
| [GameInputControllerSwitchInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputcontrollerswitchinfo.md) | 指定输入设备上的一个开关。 |
| [GameInputDeviceInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputdeviceinfo.md) | 包含有关输入设备的全面信息。 |
| [GameInputFlightStickInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputflightstickinfo.md) | 详细描述飞行摇杆的特性。 |
| [GameInputFlightStickState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputflightstickstate.md) | 提供飞行摇杆的当前状态。 |
| [GameInputForceFeedbackConditionParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackconditionparams.md) | 定义力反馈效果的某些物理方面。 |
| [GameInputForceFeedbackConstantParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackconstantparams.md) | 定义力反馈效果的恒定物理方面。 |
| [GameInputForceFeedbackEnvelope](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackenvelope.md) | 定义修改力反馈效果的包络。 |
| [GameInputForceFeedbackMagnitude](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackmagnitude.md) | 定义力反馈效果施加的力的幅度。 |
| [GameInputForceFeedbackMotorInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackmotorinfo.md) | 提供有关力反馈电机的信息。 |
| [GameInputForceFeedbackParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackparams.md) | 定义力反馈效果的 API 支持属性。 |
| [GameInputForceFeedbackPeriodicParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackperiodicparams.md) | 定义周期性力反馈效果的参数。 |
| [GameInputForceFeedbackRampParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputforcefeedbackrampparams.md) | 定义斜坡力反馈效果的参数。 |
| [GameInputGamepadInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputgamepadinfo.md) | 详细描述游戏手柄的特性。 |
| [GameInputGamepadState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputgamepadstate.md) | 提供游戏手柄输入设备的当前状态。 |
| [GameInputHapticInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputhapticinfo.md) | 详细描述触觉反馈电机的特性。 |
| [GameInputKeyState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputkeystate.md) | 提供键盘上某个按键的当前状态。 |
| [GameInputKeyboardInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputkeyboardinfo.md) | 详细描述键盘的特性。 |
| [GameInputMouseInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputmouseinfo.md) | 详细描述鼠标的特性。 |
| [GameInputMouseState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputmousestate.md) | 提供鼠标的当前状态。 |
| [GameInputRacingWheelInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputracingwheelinfo.md) | 详细描述赛车方向盘的特性。 |
| [GameInputRacingWheelState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputracingwheelstate.md) | 提供赛车方向盘的当前状态。 |
| [GameInputRawDeviceReportInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputrawdevicereportinfo.md) | 描述原始设备报告。 |
| [GameInputRumbleParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputrumbleparams.md) | 描述控制器产生的震动效果。 |
| [GameInputSensorsInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputsensorsinfo.md) | 详细描述可用传感器的特性。 |
| [GameInputSensorsState](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputsensorsstate.md) | 提供设备传感器的当前状态。 |
| [GameInputUsage](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputusage.md) | 描述特定的 HID 用法。 |
| [GameInputVersion](https://docs.xbox.com/zh-CN/reference/input/gameinput/structs/gameinputversion.md) | 描述由四部分组成的版本号。 |

## 枚举

| 枚举 | 说明 |
| - | - |
| [GameInputArcadeStickButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputarcadestickbuttons.md) | 枚举来自街机摇杆的输入。 |
| [GameInputDeviceFamily](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputdevicefamily.md) | 枚举输入设备的系列。 |
| [GameInputDeviceStatus](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputdevicestatus.md) | 枚举输入设备可能处于的状态。 |
| [GameInputElementKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputelementkind.md) | 枚举给定输入的元素类型。 |
| [GameInputEnumerationKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputenumerationkind.md) | 枚举用于枚举输入设备的行为类型。 |
| [GameInputFeedbackAxes](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputfeedbackaxes.md) | 枚举输入设备上可用的力反馈电机的方向类型。 |
| [GameInputFeedbackEffectState](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputfeedbackeffectstate.md) | 枚举力反馈效果的状态。 |
| [GameInputFlightStickAxes](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputflightstickaxes.md) | 枚举飞行摇杆的轴。 |
| [GameInputFlightStickButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputflightstickbuttons.md) | 枚举飞行摇杆按钮。 |
| [GameInputFocusPolicy](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputfocuspolicy.md) | 枚举输入设备的焦点策略。 |
| [GameInputForceFeedbackEffectKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputforcefeedbackeffectkind.md) | 枚举可应用于力反馈效果的“幅度随时间变化”效果类型。 |
| [GameInputGamepadAxes](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputgamepadaxes.md) | 枚举游戏手柄的轴。 |
| [GameInputGamepadButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputgamepadbuttons.md) | 枚举游戏手柄按钮，包括方向键 (D-pad)。 |
| [GameInputKeyboardKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputkeyboardkind.md) | 按键位布局枚举键盘类型。 |
| [GameInputKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputkind.md) | 枚举有效的 GameInput 设备类型。 |
| [GameInputLabel](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputlabel.md) | 枚举支持的按钮标签。 |
| [GameInputMouseButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputmousebuttons.md) | 枚举鼠标按钮。 |
| [GameInputMousePositions](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameInputmousepositions.md) | 枚举鼠标定位模式。 |
| [GameInputRacingWheelAxes](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputracingwheelaxes.md) | 枚举赛车方向盘上的轴。 |
| [GameInputRacingWheelButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputracingwheelbuttons.md) | 枚举赛车方向盘上的按钮。 |
| [GameInputRawDeviceReportKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputrawdevicereportkind.md) | 枚举原始设备报告的类型。 |
| [GameInputRumbleMotors](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputrumblemotors.md) | 枚举输入设备上受 API 支持的震动电机。 |
| [GameInputSensorAccuracy](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsensoraccuracy.md) | 枚举传感器的精度级别。 |
| [GameInputSensorsKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsensorskind.md) | 枚举有效的 GameInput 传感器类型。 |
| [GameInputSwitchKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputswitchkind.md) | 枚举输入设备支持的开关类型。 |
| [GameInputSwitchPosition](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputswitchposition.md) | 枚举输入设备上开关的位置。 |
| [GameInputSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsystembuttons.md) | 枚举用于控制系统的按钮。 |

## 已移除的成员

以下成员存在于较旧的 API 版本中，但已从当前 API 中移除。有关每个已移除成员的完整文档，请参阅 [已弃用的 GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)。

### 已移除的接口

没有接口被永久移除。`IGameInputRawDeviceReport` 在 v1 和 v2 中不存在，但已在当前 API 中重新引入。

### 已移除的函数

| 函数 | 最后版本 | 说明 |
| - | - | - |
| [GameInputGuideButtonCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/functions/gameinputguidebuttoncallback.md) | v0 | 用于 Guide 按钮事件的、由游戏标题定义的回调。已被 `GameInputSystemButtonCallback` 替代。 |

### 已移除的结构

| 结构 | 最后版本 | 说明 |
| - | - | - |
| [GameInputBatteryState](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputbatterystate.md) | v0 | 描述输入设备的电池状态。 |
| [GameInputControllerAxisInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputcontrolleraxisinfo.md) | v2 | 描述输入设备上的轴。已被 `GameInputControllerInfo` 中的字段取代。 |
| [GameInputControllerButtonInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputcontrollerbuttoninfo.md) | v2 | 描述输入设备上的按钮。已被 `GameInputControllerInfo` 中的字段取代。 |
| [GameInputHapticFeedbackMotorInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputhapticfeedbackmotorinfo.md) | v0 | 描述触觉反馈电机。已被 `GameInputHapticInfo` 取代。 |
| [GameInputHapticFeedbackParams](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputhapticfeedbackparams.md) | v0 | 描述触觉反馈效果。 |
| [GameInputHapticWaveformInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputhapticwaveforminfo.md) | v0 | 描述触觉反馈效果的特征。 |
| [GameInputMotionInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputmotioninfo.md) | v0 | 描述启用了动作的输入设备的可测量属性。 |
| [GameInputMotionState](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputmotionstate.md) | v0 | 描述动作输入的状态。 |
| [GameInputRawDeviceItemCollectionInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputrawdeviceitemcollectioninfo.md) | v0 | 描述原始设备项的集合。 |
| [GameInputRawDeviceReportItemInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputrawdevicereportiteminfo.md) | v0 | 描述原始设备报告项。 |
| [GameInputString](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputstring.md) | v0 | 描述包含有关输入设备的信息的字符串。 |
| [GameInputTouchSensorInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputtouchsensorinfo.md) | v0 | 描述输入设备的触摸传感器。 |
| [GameInputTouchState](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputtouchstate.md) | v0 | 描述触摸输入设备的状态。 |
| [GameInputUiNavigationInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputuinavigationinfo.md) | v2 | 指定 UI 中导航按钮的标签。 |
| [GameInputUiNavigationState](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputuinavigationstate.md) | v2 | 提供 UI 导航输入的当前状态。 |

### 已移除的枚举

| 枚举 | 最后版本 | 说明 |
| - | - | - |
| [GameInputBatteryStatus](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputbatterystatus.md) | v0 | 枚举输入设备的电池状态。 |
| [GameInputDeviceCapabilities](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputdevicecapabilities.md) | v0 | 枚举输入设备的某些能力。 |
| [GameInputLocation](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputlocation.md) | v0 | 枚举输入设备的部件。 |
| [GameInputMotionAccuracy](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputmotionaccuracy.md) | v0 | 枚举动作传感器的精度级别。 |
| [GameInputRawDeviceItemCollectionKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputrawdeviceitemcollectionkind.md) | v0 | 枚举原始设备项集合的类型。 |
| [GameInputRawDevicePhysicalUnitKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputrawdevicephysicalunitkind.md) | v0 | 枚举与设备输入关联的物理单位。 |
| [GameInputRawDeviceReportItemFlags](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputrawdevicereportitemflags.md) | v0 | 枚举原始设备报告项的类型。 |
| [GameInputTouchShape](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputtouchshape.md) | v0 | 枚举触摸传感器的形状。 |
| [GameInputUiNavigationButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputuinavigationbuttons.md) | v2 | 枚举 UI 导航按钮。 |

## 版本历史

| 版本 | 变更 |
| - | - |
| **v3** | 新增 `IGameInputMapper` 接口。重新引入 `IGameInputRawDeviceReport` 接口（在 v1/v2 中不存在）。新增 `GameInputAxisMapping`、`GameInputButtonMapping`、`GameInputControllerInfo`、`GameInputHapticInfo` 结构。重新引入 `GameInputRawDeviceReportInfo` 结构和 `GameInputRawDeviceReportKind` 枚举（在 v1/v2 中不存在）。重新引入 `GameInputVersion` 结构（在 v1/v2 中不存在）。新增 `GameInputElementKind`、`GameInputFlightStickAxes`、`GameInputGamepadAxes`、`GameInputRacingWheelAxes` 枚举。移除 `GameInputControllerAxisInfo`、`GameInputControllerButtonInfo`、`GameInputUiNavigationInfo`、`GameInputUiNavigationState` 结构。移除 `GameInputUiNavigationButtons` 枚举。 |
| **v2** | 新增 `GameInputSensorsInfo`、`GameInputSensorsState` 结构。新增 `GameInputSensorsKind`、`GameInputSensorAccuracy` 枚举。新增 `IGameInputDevice::DirectInputEscape`、`IGameInputDevice::GetHapticInfo`。新增 `IGameInputReading::GetSensorsState`。重新引入 `GameInputVersion` 结构（在 v1 中不存在）。 |
| **v1** | 移除 `IGameInputRawDeviceReport` 接口、`GameInputRawDeviceReportInfo` 结构、`GameInputRawDeviceReportKind` 枚举。移除 `GameInputVersion` 结构。新增 `GameInputMousePositions` 枚举。移除仅在 v0 中存在的未实现的触觉、动作和触摸类型（`GameInputBatteryState`、`GameInputHapticFeedbackMotorInfo`、`GameInputHapticFeedbackParams`、`GameInputHapticWaveformInfo`、`GameInputMotionInfo`、`GameInputMotionState`、`GameInputTouchSensorInfo`、`GameInputTouchState`、`GameInputString`、`GameInputRawDeviceItemCollectionInfo`、`GameInputRawDeviceReportItemInfo`）。 |
| **v0** | 引入。 |

## 概念文档

* [输入概述](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-overview.md)
* [输入基础知识](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-fundamentals.md)
* [输入设备](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-devices.md)

## 另请参阅

[输入 API 参考](https://docs.xbox.com/zh-CN/reference/input/gc-reference-input-toc.md)


## Related topics

- [已弃用的 GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)
- [输入 API 参考](https://docs.xbox.com/zh-CN/reference/input/gc-reference-input-toc.md)
- [GameInputString（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputstring.md)
- [GameInputLocation（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputlocation.md)
- [GameInputDeviceCapabilities（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputdevicecapabilities.md)