> ## 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.

# GameInputGamepadInfo

> GameInputGamepadInfo 結構的參考：描述遊戲台配置、各按鈕的實體標籤、額外按鈕數目和額外軸數目。

# GameInputGamepadInfo

描述遊戲台的屬性。

<a id="syntaxSection" />

## 語法

```cpp theme={null}
struct GameInputGamepadInfo
{
    GameInputGamepadButtons supportedLayout;
    GameInputLabel          menuButtonLabel;
    GameInputLabel          viewButtonLabel;
    GameInputLabel          aButtonLabel;
    GameInputLabel          bButtonLabel;
    GameInputLabel          cButtonLabel;
    GameInputLabel          xButtonLabel;
    GameInputLabel          yButtonLabel;
    GameInputLabel          zButtonLabel;
    GameInputLabel          dpadUpLabel;
    GameInputLabel          dpadDownLabel;
    GameInputLabel          dpadLeftLabel;
    GameInputLabel          dpadRightLabel;
    GameInputLabel          leftShoulderButtonLabel;
    GameInputLabel          rightShoulderButtonLabel;
    GameInputLabel          leftThumbstickButtonLabel;
    GameInputLabel          rightThumbstickButtonLabel;
    uint32_t                extraButtonCount;
    uint32_t                extraAxisCount;
};
```

<a id="membersSection" />

### 成員

*supportedLayout*<br />
類型：[GameInputGamepadButtons](/zh-TW/reference/input/gameinput/enums/gameinputgamepadbuttons)

描述遊戲台的配置。由於軸具有按鈕轉譯，因此可以用來判斷遊戲台上有哪些軸。

*menuButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

功能表按鈕的實體標籤。

*viewButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

檢視按鈕的實體標籤。

*aButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**A** 按鈕的實體標籤。

*bButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**B** 按鈕的實體標籤。

*cButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**C** 按鈕的實體標籤。

*xButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**X** 按鈕的實體標籤。

*yButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**Y** 按鈕的實體標籤。

*zButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

**Z** 按鈕的實體標籤。

*dpadUpLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

方向鍵上的實體標籤。

*dpadDownLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

方向鍵下的實體標籤。

*dpadLeftLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

方向鍵左的實體標籤。

*dpadRightLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

方向鍵右的實體標籤。

*leftShoulderButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

左肩按鈕的實體標籤。

*rightShoulderButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

右肩按鈕的實體標籤。

*leftThumbstickButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

左搖桿的實體標籤。

*rightThumbstickButtonLabel*<br />
類型：[GameInputLabel](/zh-TW/reference/input/gameinput/enums/gameinputlabel)

右搖桿的實體標籤。

*extraButtonCount*<br />
類型：uint32\_t

未對應到遊戲台按鈕的裝置按鈕數目。

*extraAxisCount*<br />
類型：uint32\_t

未對應到遊戲台軸的裝置軸數目。

<a id="remarksSection" />

## 備註

此結構用於 [GameInputDeviceInfo](/zh-TW/reference/input/gameinput/structs/gameinputdeviceinfo) 結構中。

`GameInputDeviceInfo` 由 [IGameInputDevice::GetDeviceInfo](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceinfo) 方法使用。

如需詳細資訊，請參閱 [GameInput 裝置](/zh-TW/build/core-features/common/input/overviews/input-devices)。

### 遊戲台配置

GameInput 支援各種遊戲台外型規格，而不是僅限於單一標準配置。這是透過此結構的 `supportedLayout` 成員公開，其為 [GameInputGamepadButtons](/zh-TW/reference/input/gameinput/enums/gameinputgamepadbuttons) 類型的位元欄位。軸也會透過軸到按鈕的轉譯 (例如 `GameInputGamepadLeftTriggerButton`) 出現在此列舉中。如需這些轉譯的詳細資訊，請參閱 [GameInputGamepadButtons](/zh-TW/reference/input/gameinput/enums/gameinputgamepadbuttons#remarks)。

遊戲台沒有最低必要配置，它可以具有支援之軸和按鈕的任意組合。任何不受支援的按鈕或軸都應保留下來，並以額外軸或按鈕的形式存取。

我們已將一些常見的遊戲台元素群組和常見配置定義為常數。這些常數可用來快速識別常見配置、篩選特定輸入，或建立自訂配置。如需詳細資訊，請參閱 [GameInputGamepadButtons](/zh-TW/reference/input/gameinput/enums/gameinputgamepadbuttons#constantsSection)。

由於支援的配置和外型規格範圍沒有限制，因此我們期望對應和遊戲台使用者遵循一小組考量和行為：

* 對於成對的元素 (例如搖桿、肩部按鈕或扳機)，如果中央只有一個，則預設應將其視為左側元素。如果它位於裝置的左側或右側，則應據此對應。

* 為了避免因不同圖示而造成混淆，正面按鈕應依其實體位置對應和讀取，而不論其圖示為何，如下所示：

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/input-gamepad-facebutton-layouts.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=37ae6f7821291d3118275f019d27685d" alt="遊戲台正面按鈕配置指導方針" height="600" data-path="images/input-gamepad-facebutton-layouts.png" />

下列程式碼範例示範如何判斷遊戲台是否支援某個配置或特定輸入或模組。

```cpp theme={null}
bool IsStandardLayout(const GameInputGamepadInfo& gamepadInfo) noexcept
{
    // Supports the standard layout and no more
    return (gamepadInfo.supportedLayout & GameInputGamepadLayoutStandard) == GameInputGamepadLayoutStandard;
}

bool IsDpadSupported(const GameInputGamepadInfo& gamepadInfo) noexcept
{
    // Supports the D-pad module and more
    return gamepadInfo.supportedLayout & GameInputGamepadModuleDpad;
}

bool IsXButtonSupported(const GameInputGamepadInfo& gamepadInfo) noexcept
{
    return gamepadInfo.supportedLayout & GameInputGamepadX;
}
```

下列程式碼範例示範如何建立自訂配置，並判斷遊戲台是否支援該配置。

```cpp theme={null}
bool IsCustomLayoutSupported(const GameInputGamepadInfo& gamepadInfo) noexcept
{
    static const GameInputGamepadButtons customLayout =
        GameInputGamepadA |
        GameInputGamepadB |
        GameInputGamepadC |
        GameInputGamepadX |
        GameInputGamepadY |
        GameInputGamepadZ |
        GameInputGamepadModuleShoulders |
        GameInputGamepadModuleDpad;

    return (gamepadInfo.supportedLayout & customLayout) == GameInputGamepadLayoutCustom;
}
```

<a id="requirementsSection" />

## 需求

**標頭：** GameInput.h

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

<a id="seealsoSection" />

## 另請參閱

[GameInput 概觀](/zh-TW/build/core-features/common/input/overviews/input-overview)\
[GameInput](/zh-TW/reference/input/gameinput/gameinput_members)

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v3** | **新增** `supportedLayout` (GameInputGamepadButtons 位元遮罩)、`cButtonLabel`、`zButtonLabel`、`extraButtonCount`、`extraAxisCount`。 |
| **v0** | 推出。 |

## 附錄：先前版本

### v0、v1、v2

```cpp theme={null}
struct GameInputGamepadInfo
{
    GameInputLabel menuButtonLabel;
    GameInputLabel viewButtonLabel;
    GameInputLabel aButtonLabel;
    GameInputLabel bButtonLabel;
    GameInputLabel xButtonLabel;
    GameInputLabel yButtonLabel;
    GameInputLabel dpadUpLabel;
    GameInputLabel dpadDownLabel;
    GameInputLabel dpadLeftLabel;
    GameInputLabel dpadRightLabel;
    GameInputLabel leftShoulderButtonLabel;
    GameInputLabel rightShoulderButtonLabel;
    GameInputLabel leftThumbstickButtonLabel;
    GameInputLabel rightThumbstickButtonLabel;
};
```


## Related topics

- [GameInputGamepadInfo](/reference/input/gameinput/structs/gameinputgamepadinfo.md)
- [GameInput](/reference/input/gameinput/gameinput_members.md)
- [GameInputDeviceInfo](/reference/input/gameinput/structs/gameinputdeviceinfo.md)
- [GameInputGamepadAxes](/reference/input/gameinput/enums/gameinputgamepadaxes.md)
- [IGameInputMapper::GetGamepadAxisMappingInfo](/reference/input/gameinput/interfaces/igameinputmapper/methods/igameinputmapper_getgamepadaxismappinginfo.md)