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

# XGameUiShowTextEntryAsync

> XGameUiShowTextEntryAsync

# XGameUiShowTextEntryAsync

显示一个文本输入 UI，供用户输入信息。

## 语法

```cpp theme={null}
HRESULT XGameUiShowTextEntryAsync(  
         XAsyncBlock* async,  
         const char* titleText,  
         const char* descriptionText,  
         const char* defaultText,  
         XGameUiTextEntryInputScope inputScope,  
         uint32_t maxTextLength  
)  
```

### 参数

*async*   \_In\_\
类型：[XAsyncBlock\*](https://docs.xbox.com/zh-CN/reference/system/xasync/structs/xasyncblock.md)

指向传递给 [XAsyncRun](https://docs.xbox.com/zh-CN/reference/system/xasync/functions/xasyncrun.md) 的 [XAsyncBlock](https://docs.xbox.com/zh-CN/reference/system/xasync/structs/xasyncblock.md) 的指针。

*titleText*   \_In\_opt\_z\_\
类型：char\*

文本输入 UI 的文本标题。

*descriptionText*   \_In\_opt\_z\_\
类型：char\*

文本输入 UI 的文本说明。

*defaultText*   \_In\_opt\_z\_\
类型：char\*

在文本输入 UI 中初始填充的默认文本。

*inputScope*   \_In\_\
类型：[XGameUiTextEntryInputScope](https://docs.xbox.com/zh-CN/reference/system/xgameui/enums/xgameuitextentryinputscope.md)

指定文本输入的输入范围，用于表示允许的信息类型。此范围为游戏所需的文本提供了提示。游戏仍需对从键盘返回的文本进行验证。

*maxTextLength*   \_In\_\
类型：uint32\_t

用户在文本输入 UI 中可输入的最大字符数。在主机上，最大字符数为 1024。在 PC 上，没有限制。如果传入值 0，将按最大字符长度 1024 处理。此外，如果 *inputScope* 为 XGameUiTextEntryInputScope::Password，则最大长度始终为 1024，并且 *maxTextLength* 值将被忽略。

### 返回值

类型：HRESULT

异步调用的 HRESULT 成功或错误代码。

若要获取结果，请在 *AsyncBlock* 回调中或 *AsyncBlock* 完成后调用 [XGameUiShowTextEntryResultSize](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresultsize.md) 和 [XGameUiShowTextEntryResult](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresult.md)。

## 备注

在主机上，这将同时提供一个文本输入字段和一个屏幕虚拟键盘 (OSK)。在 Windows 上，这将提供一个包含文本输入字段的新窗口。仅当用户配置为使用屏幕键盘（例如处于平板模式），而非使用物理键盘时，Windows 上才会显示虚拟键盘。

调用 UI 会使你的游戏进入 *受限模式*。在受限模式下，你的游戏在处于所调用 UI 的后台时将获得较少的系统资源。若要详细了解受限模式以及游戏的其他运行模式，请阅读 [XBOX 游戏生命周期（NDA 主题）](https://docs.xbox.com/zh-CN/build/console-features/console-workflows/xbox-game-life-cycle.md)。

## 要求

**标头：** XGameUI.h

**库：** xgameruntime.lib

**支持的平台：** Windows、Steam Deck、XBOX One 系列主机和 XBOX Series 主机

## 请参阅

[XGameUI](https://docs.xbox.com/zh-CN/reference/system/xgameui/xgameui_members.md)\
[虚拟键盘支持](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/virtualkeyboardsupport.md) [XGameUIShowTextEntryResult](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresult.md)\
[XGameUIShowTextEntryResultSize](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresultsize.md)\
[XBOX 游戏生命周期（NDA 主题）](https://docs.xbox.com/zh-CN/build/console-features/console-workflows/xbox-game-life-cycle.md)


## Related topics

- [XGameUiShowTextEntryResult](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresult.md)
- [XGameUiShowTextEntryUiCallback](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryuicallback.md)
- [XGameUiShowTextEntryResultSize](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuishowtextentryresultsize.md)
- [XGameUiSetTextEntryUiResponse](https://docs.xbox.com/zh-CN/reference/system/xgameui/functions/xgameuisettextentryuiresponse.md)
- [XGameUiTextEntryInputScope](https://docs.xbox.com/zh-CN/reference/system/xgameui/enums/xgameuitextentryinputscope.md)