MessageBoxW 函数（winuser.h）

项目
11/20/2024

显示一个模式对话框，其中包含系统图标、一组按钮和一条特定于应用程序的简短消息，例如状态或错误信息。消息框返回一个整数值，该值指示用户单击的按钮。

语法

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，则默认标题错误。

[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_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对应的桌面。有关使用此标志的安全注意事项的信息，请参阅 Interactive Services。具体而言，请注意，此标志可以在锁定的桌面上生成交互式内容，因此应仅用于一组非常有限的方案，例如资源耗尽。

返回值

类型：int

如果消息框具有“取消”按钮，则如果按下 ESC 键或选中 “取消”按钮，该函数将返回 IDCANCEL 值。如果消息框没有取消按钮，则按 ESC 将不起作用 - 除非存在MB_OK按钮。如果显示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_ICONHAND、MB_ICONSTOP或 MB_ICONERROR
用于MB_ICONQUESTION的“”图标	MB_ICONQUESTION
用于MB_ICONEXCLAMATION和MB_ICONWARNING的图标	MB_ICONEXCLAMATION 或 MB_ICONWARNING
用于MB_ICONASTERISK和MB_ICONINFORMATION的图标	MB_ICONASTERISK 或 MB_ICONINFORMATION

在 MessageBox 呈现引擎解释 MessageBox 显示字符串开头添加由 Unicode 格式字符 U+200F 表示的两个从右向左标记（RLM），以便使 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 Professional [仅限桌面应用]
支持的最低服务器	Windows 2000 Server [仅限桌面应用]
目标平台	窗户
标头	winuser.h （包括 Windows.h）
库	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-dialogbox-l1-1-0（在 Windows 8 中引入）