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

# IGameInputReading::GetKeyState

> IGameInputReading::GetKeyState

# IGameInputReading::GetKeyState

擷取鍵盤輸入上作用中按鍵的狀態。

## 語法

```cpp theme={null}
uint32_t GetKeyState(
    uint32_t stateArrayCount,
    GameInputKeyState* stateArray
);
```

### 參數

*stateArrayCount*   \_In\_\
類型：uint32\_t

傳回鍵盤上作用中的按鍵數目。此值可藉由呼叫 [IGameInputReading::GetKeyCount](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeycount) 方法取得。

*stateArray*   \_Out\_writes\_(stateArrayCount)
類型：[GameInputKeyState\*](/zh-TW/reference/input/gameinput/structs/gameinputkeystate)

指向 [GameInputKeyState\*](/zh-TW/reference/input/gameinput/structs/gameinputkeystate) 結構的指標。

### 傳回值

類型：uint32\_t

有效的緩衝區項目數目。

## 備註

`IGameInputReading::GetKeyState` 方法會擷取遊戲控制器輸入上作用中按鍵的狀態。基本鍵盤狀態僅用於將鍵盤輸入對應至遊戲動作，例如移動或開火。它並非用於一般文字輸入。遊戲需要在此狀態之上撰寫大量程式碼，才能實作像文字方塊這樣簡單的功能 (更別提 IME 等複雜功能)。若需要該功能，應使用其他 API。

每個按鍵的狀態並不會儲存在陣列中的固定索引位置。相反地，陣列中的有效元素數目會隨著按鍵按下而增加，並隨著按鍵放開而減少。新的按鍵會新增至陣列的結尾，而當按鍵放開時，所有項目都會向前移動以填補空缺。第一個 `scancode` 和 `vkey` 值皆為零的陣列元素，表示陣列中有效資料的結尾。標準鍵盤一次只能回報四到六個按鍵按下，即使是高階遊戲鍵盤也很少一次支援超過 12 到 16 個按鍵。因此，這種方式通常能讓陣列的最大大小維持在較小的範圍 (最大大小可透過 `IGameInputDevice` 介面查詢)。這比讓應用程式每次檢查鍵盤狀態時都逐一查看 256 個值的陣列要有效率得多。

## 需求

**標頭：** GameInput.h

[進階 GameInput 主題](/zh-TW/build/core-features/common/input/advanced/input-advanced-topics)\
[GameInput 概觀](/zh-TW/build/core-features/common/input/overviews/input-overview)\
[IGameInputReading](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/igameinputreading)

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v0** | 推出。 |


## Related topics

- [IGameInputReading::GetKeyState](/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeystate.md)
- [IGameInputReading::GetKeyCount](/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getkeycount.md)
- [GameInputKeyState](/reference/input/gameinput/structs/gameinputkeystate.md)