> ## 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 開始，v.0 版是 GDK 中可用的預設版本。運用 v1.0+ API 的遊戲可以透過整合 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 套件，在 PC (v1.0+) 和主機 (v2.2+) 上使用這些 API。若要在主機上使用此 NuGet 套件，需要 GDK 2510 或更新版本。PC 應用程式需要在目標電腦上安裝 NuGet 套件中隨附的最新 GameInput 可轉散發套件。主機應用程式必須針對 NuGet 套件中最新的 GameInput 標頭和程式庫進行編譯和連結，但不需要可轉散發套件，因為最新的 GameInput 執行階段已隨附於 XBOX 上的 GDK 映像中。</Note>

GameInput 是一個持續演進的 API，會隨著新增功能以及移除不需要或過時的功能而不斷發展。您可以在官方 [NuGet 套件](/zh-TW/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 標頭 include 之後新增下列程式碼片段。

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

## 僅升級執行階段

<a id="upgradingRuntimeSection" />

GameInput 可讓您取得最新的錯誤修正，而不需強制您更新 API 使用方式。若要取得這些錯誤修正，請安裝最新 [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 套件](/zh-TW/build/core-features/common/input/overviews/input-nuget)安裝最新的可轉散發套件，並在遊戲向終端使用者提供的安裝程序中納入該可轉散發套件 (或更新版本)。此可轉散發套件包含較新的 GameInput 執行階段實作，可為所有 API 版本增強功能，例如擴充的控制器支援、觸控板支援、遠端桌面支援，以及各種其他錯誤修正。

## 另請參閱

<a id="seeAlsoSection" />

[GameInput NuGet 套件](/zh-TW/build/core-features/common/input/overviews/input-nuget)


## Related topics

- [概述](/zh-CN/build/core-features/common/input/overviews/index.md)
- [GameInput API 版本管理](/zh-CN/build/core-features/common/input/overviews/input-versioning.md)
- [已弃用的 GameInput API 成员](/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)
- [GameInput](/zh-CN/reference/input/gameinput/gameinput_members.md)
- [GameInput 概述](/zh-CN/build/core-features/common/input/overviews/input-overview.md)