> ## 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 中的鍵盤和滑鼠

> GameInput 中的鍵盤和滑鼠

使用本主題了解鍵盤和滑鼠特有的使用方式。鍵盤和滑鼠是 `GameInput` 的原生輸入。

## 鍵盤輸入

[GetKeyState](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeystate) 方法會擷取鍵盤上每個按下按鍵的掃描碼和虛擬按鍵資料。此輸入資料接著會以 [GameInputKeyState](/zh-TW/reference/input/gameinput/structs/gameinputkeystate) 結構的可變長度陣列傳回。按下的按鍵是指在鍵盤回報輸入時處於按住狀態的按鍵。鍵盤回報輸入的頻率各不相同，通常介於 125 Hz 到 1,000 Hz 之間。鍵盤狀態會針對連接到系統的每個個別鍵盤分別回報。

基本鍵盤狀態用於將鍵盤輸入對應至遊戲動作，例如移動或發射武器。它不適用於一般文字輸入，以及用於該用途的其他 API。

### 讀取按鍵狀態

使用下列程式碼，在您的遊戲中為鍵盤和滑鼠實作 `GameInput`。

```c++ theme={null}
uint32_t GetKeyState(
    uint32_t stateArrayCount,
    GameInputKeyState* stateArray
)

typedef struct  GameInputKeyState
{
    uint32_t scanCode;
    uint32_t codePoint;
    uint8_t virtualKey;
    bool isDeadKey;
} GameInputKeyState;
```

每個按鍵的狀態並非儲存在陣列中的固定索引。相反地，陣列中有效元素的數目會隨著按鍵按下而增加，並隨著按鍵放開而縮減。新按鍵會加入陣列的結尾，而當按鍵放開時，所有項目都會往前移以填補空缺。[GetKeyCount](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeycount) 會傳回按下的按鍵數目，如下列程式碼所示。這可用來判斷應該為 [GetKeyState](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeystate) 配置多大的陣列。如果傳入 [`GetKeyState`](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeystate) 的 `stateArray` 大於按下的按鍵數目，多餘的陣列元素不會被寫入或歸零。反之，如果 `stateArray` 小於按下的按鍵數目，陣列會被填滿，而多出的按下按鍵會遺漏。

```c++ theme={null}
uint32_t GetKeyCount()
```

標準鍵盤一次只能回報四到六個按鍵，即使是高階遊戲鍵盤也很少一次支援超過 12-16 個按鍵。因此，使用 `GetKeyCount` 可讓陣列的大小上限保持很小。大小上限可透過 [IGameInputDevice](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) 介面查詢。

請注意，`codePoint` 成員會根據目前的鍵盤配置，指定系統認為印在相關鍵帽上的字符。其用途是在輸入對應介面中顯示按鍵的表示法，而非用於建立文字輸入的字串。

## 滑鼠輸入

[GetMouseState](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getmousestate) 方法會擷取滑鼠的移動和按鈕狀態，並以單一 [GameInputMouseState](/zh-TW/reference/input/gameinput/structs/gameinputmousestate) 結構傳回，如下列程式碼所示。與鍵盤狀態一樣，滑鼠狀態會針對連接到系統的每個個別滑鼠分別回報。\<!--As with keyboard input, the [CreateAggregateDevice](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_createaggregatedevice) method on the `IGameInput` interface is used to get the combined system mouse state.> -->

```c++ theme={null}
bool GetMouseState(
    GameInputMouseState* state
)

typedef struct GameInputMouseState
{
    GameInputMouseButtons buttons;
    int64_t positionX;
    int64_t positionY;
    int64_t wheelX;
    int64_t wheelY;
} GameInputMouseState;

typedef enum GameInputMouseButtons
{
    GameInputMouseNone          = 0x00000000,
    GameInputMouseLeftButton    = 0x00000001,
    GameInputMouseRightButton   = 0x00000002,
    GameInputMouseMiddleButton  = 0x00000004,
    GameInputMouseButton4       = 0x00000008,
    GameInputMouseButton5       = 0x00000010,
    GameInputMouseWheelTiltLeft = 0x00000020,
    GameInputMouseWhelTiltRight = 0x00000040
} GameInputMouseButtons;
```

### 讀取滑鼠移動

滑鼠移動原生會以一系列差異值回報，而非絕對位置。這與 [`GetCurrentReading`](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) 的輪詢性質不相容，因為定期要求目前的滑鼠讀數很可能會遺漏數個中間差異值。

與其使用 [GetNextReading](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getnextreading) 逐一查看可能數十個歷史滑鼠讀數並加總差異值，這些差異值會累積到虛擬的 `positionX` 和 `positionY` 值中。接著，將 `positionX` 和 `positionY` 值減去先前取得之讀數的值，即可計算差異值。逐一查看所有中間讀數時，可以存取個別差異值；略過中間讀數時，則可透過累積的差異值存取。

`positionX` 和 `positionY` 值是所有移動差異值的總和。這些值與螢幕空間座標沒有任何關聯。累積的差異值僅適用於處理序在具有輸入焦點時所接收的滑鼠事件。

## 使用者關聯

目前鍵盤和滑鼠不支援使用者關聯。沒有任何介面可將這些周邊裝置對應至使用者。

<a id="seeAlsoSection" />

## 參考 API 文件

* [GameInput (API 內容)](/zh-TW/reference/input/gameinput/gameinput_members)
  * 結構
    * [GameInputKeyState](/zh-TW/reference/input/gameinput/structs/gameinputkeystate)
    * [GameInputMouseState](/zh-TW/reference/input/gameinput/structs/gameinputmousestate)

## 另請參閱

[GameInput 讀數](/zh-TW/build/core-features/common/input/overviews/input-readings)

[GameInput 裝置](/zh-TW/build/core-features/common/input/overviews/input-devices)

[進階 GameInput 主題](/zh-TW/build/core-features/common/input/advanced/input-advanced-topics)

[輸入 API 參考](/zh-TW/build/core-features/common/input/gc-input-toc)


## Related topics

- [無障礙功能標籤](/zh-TW/build/game-principles/accessibility/accessibility-feature-tags.md)
- [GameInput 中的传感器](/zh-CN/build/core-features/common/input/hardware/input-hardware-sensors.md)
- [GameInput 中的触觉反馈](/zh-CN/build/core-features/common/input/hardware/input-hardware-haptics.md)
- [GameInput](/zh-CN/reference/input/gameinput/gameinput_members.md)
- [GameInput 常见问题](/zh-CN/build/core-features/common/input/overviews/input-faq.md)