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

# GameInput API 版本管理

> GameInput API 版本管理

<a id="introductionSection" />

<Note>如果你在为 XBOX 开发，自 2510 GDK 起，GDK 中默认可用的版本是 v.0。使用 v1.0+ API 的游戏可通过集成 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包在 PC (v1.0+) 和主机 (v2.2+) 上都实现。在主机上使用此 NuGet 包需要 GDK 2510 或更高版本。PC 应用需要在目标计算机上安装最新的 GameInput 可再发行组件（已包含在 NuGet 包中）。主机应用必须针对 NuGet 包中最新的 GameInput 头文件和库进行编译与链接，但无需可再发行组件，因为最新的 GameInput 运行时已随附于 XBOX 上的 GDK 镜像。</Note>

GameInput 是一款持续演进的 API，随着新功能的加入以及不再需要或过时功能的移除而不断发展。你可以在官方 [NuGet 包](/build/core-features/common/input/overviews/input-nuget)中找到最新版本的 GameInput。该包还包含最新的[版本历史](https://www.nuget.org/packages/Microsoft.GameInput)。该包始终包含最新的 GameInput 头文件、二进制文件以及要与游戏一起分发的可再发行组件。

升级到较新版本的 GameInput 快捷且无痛。此外，无论最新 GameInput 头文件中描述的是哪一版本的 API，针对早期版本 GameInput 编译的应用程序仍保持二进制和功能兼容。在此模式下，已发布的游戏可享受 GameInput 的改进，并在必要时切换到最新版本的 GameInput 以利用新功能。

## 升级运行时和 API 版本

<a id="upgradingRuntimeAndApiVersionSection" />

不同版本的 GameInput 名称和方法相似，但通过不同的 UUID 进行明确的版本区分。自 GameInput API v.1 起，每个版本都在唯一的命名空间中定义（例如 `GameInput::v1`）。GameInput 中相同的底层对象实现这些接口。你可以[QueryInterface](https://learn.microsoft.com/cpp/atl/queryinterface) 在版本之间切换，这意味着你可以在游戏中混合使用 API。

如果你从 API 定义在全局命名空间中的 GameInput v.0 升级，可能会发现添加一条 `using namespace GameInput::v1` 语句有助于减少为采用 v.1 及后续 API 修订版而需要更新的 GameInput 调用点数量。

除了运行时版本检查之外，你还可以通过检查 `GAMEINPUT_API_VERSION` 预处理器宏进行条件编译。该宏对应当前使用的 GameInput API 版本以及 GameInput 主版本号。v.0 API 没有此定义，因此如果你想对该版本进行条件测试，可以在包含 GameInput 头文件后添加以下代码片段。

```cpp theme={null}
#ifndef GAMEINPUT_API_VERSION
#define GAMEINPUT_API_VERSION 0
#endif
```

## 仅升级运行时

<a id="upgradingRuntimeSection" />

GameInput 允许你在不强制更新 API 用法的情况下获取最新的 bug 修复。为获取这些修复，请安装最新 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包中随附的 GameInput 可再发行组件。因为 GameInput 与旧版 API 保持二进制兼容，你可以继续使用现有头文件搭配新运行时。请务必与游戏一起分发最新的 GameInput 二进制文件，以确保测试环境中的功能与生产环境一致。

## GameInput v.1 更改

如果你在使用较早版本的 GameInput，请注意，许多未实现的函数以及对应的枚举和常量已自 v.1 起从 API 中移除。此外，API 被放入 `GameInput::v1` 命名空间以便版本管理。由于这些更改，你在使用此版本（及后续版本）构建旧代码时可能会遇到编译错误。值得注意的更改包括：

1. `IGameInputDevice::GetDeviceInfo` 之前将生成的 `IGameInputDeviceInfo` 结构体作为函数返回值返回。此结构体现在通过函数的输出参数返回，函数的返回值改为 `HRESULT`。

2. `IGameInput::UnregisterCallback` 之前将超时值作为其第二个参数，此参数已被移除。

3. `IGameInputReading::GetSequenceNumber` 已被移除。请改用 `IGameInputReading::GetTimestamp`。

## 版本管理提示

* v.0 与 v.1 之间可用 API 表面的变化很小，主要是移除了从未实现的功能，以及前文所述的函数签名更改。
* 原始 `GameInput.h` 头文件中的原 v.0 API 仍受支持，但该 API 保持静态。此情况下，你继续按原样使用来自 GDK、较早 NuGet 包或 Windows SDK 中的头文件。
* 无论你使用哪个版本的 API，在开发期间都必须安装 [NuGet 包](/build/core-features/common/input/overviews/input-nuget)中的最新可再发行组件，并将该可再发行组件（或更新版本）作为面向最终用户的游戏安装过程的一部分。此可再发行组件是较新的 GameInput 运行时实现所在之处，它使所有版本的 API 都能获得例如更广的控制器支持、触控板支持、远程桌面支持以及各种其他 bug 修复等增强。

## 另请参阅

<a id="seeAlsoSection" />

[GameInput NuGet 包](/build/core-features/common/input/overviews/input-nuget)


## Related topics

- [GameInput 常见问题](/zh-CN/build/core-features/common/input/overviews/input-faq.md)
- [已弃用的 GameInput API 成员](/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)
- [输入](/zh-CN/build/core-features/common/input/gc-input-toc.md)
- [GameInput 概述](/zh-CN/build/core-features/common/input/overviews/input-overview.md)
- [GameInput](/zh-CN/reference/input/gameinput/gameinput_members.md)