MessageBoxW 函式 (winuser.h)

顯示包含系統圖示、一組按鈕和簡短應用程式特定訊息的強制回應對話方塊，例如狀態或錯誤資訊。 訊息方塊會傳回整數值，指出使用者按一下的按鈕。

語法

int MessageBoxW(
  [in, optional] HWND    hWnd,
  [in, optional] LPCWSTR lpText,
  [in, optional] LPCWSTR lpCaption,
  [in]           UINT    uType
);

參數

[in, optional] hWnd

類型： HWND

要建立之訊息方塊之擁有者視窗的控制碼。 如果此參數為 Null，訊息方塊沒有擁有者視窗。

[in, optional] lpText

類型： LPCTSTR

要顯示的訊息。 如果字串包含一行以上，您可以使用每一行之間的歸位字元和/或換行字元分隔行。

[in, optional] lpCaption

類型： LPCTSTR

對話方塊標題。 如果此參數為 Null，則預設標題為 Error。

[in] uType

類型： UINT

對話方塊的內容和行為。 此參數可以是來自下列旗標群組的旗標組合。

若要指出訊息方塊中顯示的按鈕，請指定下列其中一個值。

值	意義
MB_ABORTRETRYIGNORE 0x00000002L	訊息方塊包含三個按鈕： 中止、 重試和 忽略。
MB_CANCELTRYCONTINUE 0x00000006L	訊息方塊包含三個按鈕： 取消、 再試一次、 繼續。 使用此訊息方塊類型，而不是MB_ABORTRETRYIGNORE。
MB_HELP 0x00004000L	將 [說明 ] 按鈕新增至訊息方塊。 當使用者按一下 [ 說明 ] 按鈕或按下 F1 時，系統會將 WM_HELP 訊息傳送給擁有者。
MB_OK 0x00000000L	訊息方塊包含一個按鈕： 確定。 此為預設值。
MB_OKCANCEL 0x00000001L	訊息方塊包含兩個按鈕： [確定 ] 和 [ 取消]。
MB_RETRYCANCEL 0x00000005L	訊息方塊包含兩個按鈕： 重試 和 取消。
MB_YESNO 0x00000004L	訊息方塊包含兩個按鈕： 是 和 否。
MB_YESNOCANCEL 0x00000003L	訊息方塊包含三個按鈕： 是、 否和 取消。

 

若要在訊息方塊中顯示圖示，請指定下列其中一個值。

值	意義
MB_ICONEXCLAMATION 0x00000030L	訊息方塊中會出現驚嘆號圖示。
MB_ICONWARNING 0x00000030L	訊息方塊中會出現驚嘆號圖示。
MB_ICONINFORMATION 0x00000040L	由圓形中的小寫字母 i 所組成的圖示會出現在訊息方塊中。
MB_ICONASTERISK 0x00000040L	由圓形中的小寫字母 i 所組成的圖示會出現在訊息方塊中。
MB_ICONQUESTION 0x00000020L	問號圖示會出現在訊息方塊中。 我們不再建議使用問號的訊息圖示，因為它並未清楚表示特定類型的訊息，且問題訊息的措辭適用於各種訊息。 此外，使用者可能會將訊息符號的問號與「說明」資訊搞混。 因此，請勿在您的訊息方塊中使用這個問號訊息符號。 系統繼續支援將其納入，只為回溯相容性之用。
MB_ICONSTOP 0x00000010L	停止登錄圖示會出現在訊息方塊中。
MB_ICONERROR 0x00000010L	停止登錄圖示會出現在訊息方塊中。
MB_ICONHAND 0x00000010L	停止登錄圖示會出現在訊息方塊中。

 

若要指出預設按鈕，請指定下列其中一個值。

值	意義
MB_DEFBUTTON1 0x00000000L	第一個按鈕是預設按鈕。 除非指定MB_DEFBUTTON2、MB_DEFBUTTON3或MB_DEFBUTTON4，否則MB_DEFBUTTON1為預設值。
MB_DEFBUTTON2 0x00000100L	第二個按鈕是預設按鈕。
MB_DEFBUTTON3 0x00000200L	第三個按鈕是預設按鈕。
MB_DEFBUTTON4 0x00000300L	第四個按鈕是預設按鈕。

 

若要指出對話方塊的型態，請指定下列其中一個值。

值	意義
MB_APPLMODAL 0x00000000L	使用者必須先回應訊息框，才能繼續在 hWnd 參數所識別的視窗中工作。 不過，使用者可以移至其他執行緒的視窗，並在這些視窗中運作。 視應用程式中的視窗階層而定，使用者可能能夠移至執行緒內的其他視窗。 訊息方塊父系的所有子視窗都會自動停用，但快顯視窗不是。 如果未指定MB_SYSTEMMODAL或MB_TASKMODAL，則MB_APPLMODAL為預設值。
MB_SYSTEMMODAL 0x00001000L	與MB_APPLMODAL相同，不同之處在于訊息方塊具有 WS_EX_TOPMOST 樣式。 使用系統強制回應訊息框來通知使用者發生嚴重、潛在的損害錯誤，例如立即注意 (，例如記憶體不足) 。 此旗標不會影響使用者與 與 hWnd相關聯視窗以外的視窗互動。
MB_TASKMODAL 0x00002000L	與 MB_APPLMODAL相同， 不同之處在于 如果 hWnd 參數為 Null，則會停用屬於目前線程的所有最上層視窗。 當呼叫的應用程式或程式庫沒有可用的視窗控制碼，但仍需要防止呼叫執行緒中的其他視窗輸入，而不暫停其他執行緒時，請使用此旗標。

 

若要指定其他選項，請使用下列一或多個值。

值	意義
MB_DEFAULT_DESKTOP_ONLY 0x00020000L	與互動式視窗月臺的桌面相同。 如需詳細資訊，請參閱 視窗站台。 如果目前的輸入桌面不是預設桌面， 則 MessageBox 不會在使用者切換至預設桌面之前傳回。
MB_RIGHT 0x00080000L	文字靠右對齊。
MB_RTLREADING 0x00100000L	在希伯來文和阿拉伯文系統上，使用由右至左讀取順序顯示訊息和標題文字。
MB_SETFOREGROUND 0x00010000L	訊息方塊會變成前景視窗。 在內部，系統會呼叫訊息方塊的 SetForegroundWindow 函式。
MB_TOPMOST 0x00040000L	訊息方塊是以 視窗樣式WS_EX_TOPMOST 建立。
MB_SERVICE_NOTIFICATION 0x00200000L	呼叫者是一個會通知使用者發生事件的服務。 函式會顯示目前使用中桌面上的訊息方塊，即使沒有使用者登入電腦也一樣。 終端機服務： 如果呼叫執行緒具有模擬權杖，函式會將訊息方塊導向至模擬權杖中指定的會話。 如果設定此旗標， hWnd 參數必須是 Null。 這可讓訊息方塊出現在桌面上，而不是對應至 hWnd的桌面。 如需有關使用此旗標之安全性考慮的資訊，請參閱 互動式服務。 特別是請注意，此旗標可以在鎖定的桌面上產生互動式內容，因此應該只用于一組非常有限的案例，例如資源耗盡。

傳回值

類型： int

如果訊息方塊有[取消] 按鈕，則函式會在按下 ESC 鍵或選取 [取消]按鈕時傳回IDCANCEL值。 如果訊息方塊沒有 [取消] 按鈕，除非有MB_OK按鈕，否則按下 ESC 不會有任何作用。 如果顯示MB_OK按鈕，且使用者按下 ESC 鍵，則傳回值會是 IDOK。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果函式成功，傳回值就是下列其中一個功能表項目值。

傳回碼/值	描述
IDABORT 3	已選取 [中止] 按鈕。
IDCANCEL 2	已選取 [取消] 按鈕。
IDCONTINUE 11	已選取 [ 繼續 ] 按鈕。
IDIGNORE 5	已選取 [忽略] 按鈕。
IDNO 7	已選取 [否] 按鈕。
IDOK 1	已選取 [ 確定 ] 按鈕。
IDRETRY 4	已選取 [重試] 按鈕。
IDTRYAGAIN 10	已選取 [重試] 按鈕。
IDYES 6	已選取 [ 是 ] 按鈕。

備註

將 uType 參數設定為對應的旗標值，即可在訊息方塊中使用下列系統圖示。

圖示	旗標值
	MB_ICONHAND、 MB_ICONSTOP或 MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION 或 MB_ICONWARNING
	MB_ICONASTERISK 或 MB_ICONINFORMATION

 

在 MessageBox 顯示字串開頭的 Unicode 格式化字元 U+200F 所表示，將兩個由右至左標記新增 (RL) M，由 MessageBox 轉譯引擎解譯，以便讓 MessageBox 的讀取順序轉譯為由右至左 (RTL) 。

當您使用系統強制回應訊息框來指出系統記憶體不足時， lpText 和 lpCaption 參數所指向的字串不應該從資源檔取得，因為嘗試載入資源可能會失敗。

如果您在對話方塊存在時建立訊息方塊，請使用對話方塊的控制碼做為 hWnd 參數。 hWnd參數不應該識別子視窗，例如對話方塊中的控制項。

範例

在下列範例中，應用程式會顯示訊息方塊，提示使用者在發生錯誤狀況之後採取動作。 訊息方塊會顯示描述錯誤狀況的訊息，以及如何加以解決。 MB_CANCELTRYCONTINUE樣式會指示MessageBox提供三個按鈕，讓使用者可以選擇如何繼續。 MB_DEFBUTTON2樣式會將預設焦點設定為訊息方塊的第二個按鈕，在此案例中為[重試]按鈕。

int DisplayResourceNAMessageBox()
{
    int msgboxID = MessageBox(
        NULL,
        (LPCWSTR)L"Resource not available\nDo you want to try again?",
        (LPCWSTR)L"Account Details",
        MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
    );

    switch (msgboxID)
    {
    case IDCANCEL:
        // TODO: add code
        break;
    case IDTRYAGAIN:
        // TODO: add code
        break;
    case IDCONTINUE:
        // TODO: add code
        break;
    }

    return msgboxID;
}

下圖顯示上述程式碼範例的輸出：

如需另一個訊息方塊範例，請參閱 顯示訊息方塊。

注意

winuser.h 標頭會將 MessageBox 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-dialogbox-l1-1-0 (于 Windows 8)

另請參閱

概念

對話方塊

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

其他資源

參考

SetForegroundWindow