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

# XGameUiShowMessageDialogAsync

> XGameUiShowMessageDialogAsync

# XGameUiShowMessageDialogAsync

显示可自定义消息对话框的 UI。用户按下的按钮的索引包含在结果中。

## 语法

```cpp theme={null}
HRESULT XGameUiShowMessageDialogAsync(  
         XAsyncBlock* async,  
         const char* titleText,  
         const char* contentText,  
         const char* firstButtonText,  
         const char* secondButtonText,  
         const char* thirdButtonText,  
         XGameUiMessageDialogButton defaultButton,  
         XGameUiMessageDialogButton cancelButton  
)  
```

### 参数

*async*   \_In\_<br />类型：[XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock)

指向传递给 [XAsyncRun](/reference/system/xasync/functions/xasyncrun) 的 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock) 的指针。

*titleText*   \_In\_<br />类型：char\*

消息对话框的文本标题。

*contentText*   \_In\_<br />类型：char\*

在消息对话框内显示的文本。

*firstButtonText*   \_In\_opt\_<br />类型：char\*

在消息对话框的第一个按钮上显示的文本。

*secondButtonText*   \_In\_opt\_<br />类型：char\*

在消息对话框的第二个按钮上显示的文本。

*thirdButtonText*   \_In\_opt\_<br />类型：char\*

在消息对话框的第三个按钮上显示的文本。

*defaultButton*   \_In\_<br />类型：[XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton)

指示首次显示消息对话框时默认选择的按钮。

*cancelButton*   \_In\_<br />类型：[XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton)

指示表示取消操作的按钮。

### 返回值

类型：HRESULT

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

若要获取结果，请在 *XAsyncBlock* 回调内或 *XAsyncBlock* 完成后调用 [XGameUiShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult)。

## 备注

与其他 **XGameUI\*** 函数一样，**XGameUiShowMessageDialogAsync** 在游戏分区之外呈现其 UI，结果与游戏的输出合成后再将每帧发送到显示设备。这意味着无论游戏是否正在呈现，都可以使用 **XGameUiShowMessageDialogAsync** 向用户呈现信息。

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

以下示例代码演示如何在开发场景中使用此方法来创建等待输入的阻塞 UI。这在崩溃故障发生的位置暂停当前执行、报告崩溃位置或提示开发人员附加调试器时特别有用。

```cpp theme={null}
if (FAILED(XGameRuntimeInitialize()))  
    return 1;

XTaskQueueHandle queue;
DX::ThrowIfFailed(
    XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Immediate, &queue)  
);

XAsyncBlock* ab = new XAsyncBlock;
ZeroMemory(ab, sizeof(XAsyncBlock));
ab->queue = queue;

// show dialog, wait for completion, get result.

XGameUiMessageDialogButton button;
if (SUCCEEDED(XGameUiShowMessageDialogAsync(ab, u8"Title String", u8"This is content text",
                                            u8"Option #1", u8"Option #2", u8"Option #3",
                                            XGameUiMessageDialogButton::First,
                                            XGameUiMessageDialogButton::Third)) &&
    SUCCEEDED(XAsyncGetStatus(ab, true)) &&
    SUCCEEDED(XGameUiShowMessageDialogResult(ab, &button)))  
{
    DoSomethingWithResponse(button);  // set breakpoint here to investigate
}
```

## 要求

**标头：** XGameUI.h

**库：** xgameruntime.lib

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

## 概念文档

* [异步编程设计目标和改进](/build/core-features/common/async/async-whitepaper)

## 另请参阅

[XGameUI](/reference/system/xgameui/xgameui_members)<br />[XGameUIShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult)<br />[XBOX 游戏生命周期（NDA 主题）](/build/console-features/console-workflows/xbox-game-life-cycle)


## Related topics

- [XGameUiShowMessageDialogResult](/zh-CN/reference/system/xgameui/functions/xgameuishowmessagedialogresult.md)
- [XGameUiMessageDialogButton](/zh-CN/reference/system/xgameui/enums/xgameuimessagedialogbutton.md)
- [XGameUiShowMessageDialogUiCallback](/zh-CN/reference/system/xgameui/functions/xgameuishowmessagedialoguicallback.md)
- [XGameUiSetMessageDialogUiResponse](/zh-CN/reference/system/xgameui/functions/xgameuisetmessagedialoguiresponse.md)
- [XGameUiUiCallbacks](/zh-CN/reference/system/xgameui/structs/xgameuiuicallbacks.md)