> ## 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\*](/zh-TW/reference/system/xasync/structs/xasyncblock)

傳遞至 [XAsyncRun](/zh-TW/reference/system/xasync/functions/xasyncrun) 之 [XAsyncBlock](/zh-TW/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](/zh-TW/reference/system/xgameui/enums/xgameuimessagedialogbutton)

表示訊息對話方塊第一次顯示時預設選取的按鈕。

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

表示代表取消動作的按鈕。

### 傳回值

類型：HRESULT

非同步呼叫的 HRESULT 成功或錯誤碼。

若要取得結果，請在 *XAsyncBlock* 回呼內或 *XAsyncBlock* 完成後呼叫 [XGameUiShowMessageDialogResult](/zh-TW/reference/system/xgameui/functions/xgameuishowmessagedialogresult)。

## 備註

與其他 **XGameUI\*** 函式一樣，**XGameUiShowMessageDialogAsync** 會在遊戲分割區之外轉譯其 UI，並在每個畫面傳送至顯示裝置之前，將結果與遊戲的輸出進行合成。這表示無論遊戲是否正在轉譯，都可以使用 **XGameUiShowMessageDialogAsync** 向使用者呈現資訊。

呼叫 UI 會導致您的遊戲進入\_受限模式\_。在受限模式下，您的遊戲位於所呼叫 UI 的背景時，將會獲得較少的系統資源。若要深入了解受限模式及遊戲的其他作業模式，請參閱 [XBOX 遊戲生命週期 (NDA 主題)](/zh-TW/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 主機

## 概念文件

* [非同步程式設計設計目標與改進](/zh-TW/build/core-features/common/async/async-whitepaper)

## 另請參閱

[XGameUI](/zh-TW/reference/system/xgameui/xgameui_members)<br />[XGameUIShowMessageDialogResult](/zh-TW/reference/system/xgameui/functions/xgameuishowmessagedialogresult)<br />[XBOX 遊戲生命週期 (NDA 主題)](/zh-TW/build/console-features/console-workflows/xbox-game-life-cycle)


## Related topics

- [XGameUiShowMessageDialogAsync](/reference/system/xgameui/functions/xgameuishowmessagedialogasync.md)
- [XGameUiShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult.md)
- [XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton.md)