syncfusion-winforms-messagebox

实现消息框（MessageBoxAdv）

一个适用于 Windows Forms 的高级消息框控件，提供主题化对话框、自定义图标、可展开的详细信息、本地化支持和完整的外观自定义功能。

何时使用此技能

在以下场景中使用此技能：

• 模态对话框：在模态窗口中显示消息、确认、警告或错误
• 主题化消息框：应用 Office 2007/2010/2013/2016 或 Metro 主题，使其与应用程序样式匹配
• 自定义图标：在消息框中显示内置或自定义图标
• 确认对话框：实现“是/否”、“确定/取消”或“重试/取消”用户提示
• 详细信息视图：提供可展开的详细信息面板，展示其他信息
• 多语言对话框：为国际化应用程序本地化按钮文本和消息
• 可调整大小的对话框：允许用户在运行时调整消息框大小
• 从右到左支持：为阿拉伯语/希伯来语应用程序以 RTL 布局显示消息框

组件概述

MessageBoxAdv 是标准 Windows Forms MessageBox 的增强替代控件，提供：

• 静态 Show() 方法模式（无需实例化）
• 多种按钮组合（Ok、OkCancel、YesNo、YesNoCancel、RetryCancel、AbortRetryIgnore）
• 内置图标和自定义图标支持
• 六种视觉主题及多种配色方案（15 种以上的样式变体）
• 可展开的详细信息面板，用于显示其他信息
• 通过 ILocalizationProvider 提供完整的本地化支持
• 支持通过拖动手柄在运行时调整大小
• 支持从右到左的布局

主要功能：

• 用于显示对话框的 MessageBoxAdv.Show() 静态方法
• 用于捕获用户响应的 DialogResult 返回值
• 用于选择主题的 MessageBoxStyle 属性
• 用于自定义 Metro 主题的 MetroColorTable
• 用于在运行时调整大小的 CanResize 属性
• 带有可展开/折叠详细文本的详细信息视图
• 支持指定尺寸加载自定义图标

返回值： MessageBoxAdv 返回 DialogResult 枚举值：OK、Cancel、Yes、No、Retry、Abort、Ignore、None

文档和导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 开始新的实现、设置依赖项、首次使用、了解基本的 Show() 方法

涵盖主题：

• 程序集部署（Syncfusion.Shared.Base.dll）
• NuGet 包安装（Syncfusion.Shared.Base）
• 命名空间要求（Syncfusion.Windows.Forms）
• 静态 Show() 方法的使用模式
• 基本消息框示例
• Show() 方法重载
• DialogResult 返回值处理
• 简单的警报和确认示例

---

按钮参数和功能

📄 阅读： references/button-parameters.md

阅读时机： 配置按钮组合、添加图标、启用功能（RTL、详细信息、调整大小）

涵盖主题：

• 标题栏文本参数
• 消息文本参数
• 按钮组合（MessageBoxButtons 枚举：OK、OKCancel、YesNo、YesNoCancel、RetryCancel、AbortRetryIgnore）
• 图标支持（MessageBoxIcon 枚举：Asterisk、Error、Exclamation、Hand、Information、None、Question、Stop、Warning）
• 加载自定义图标（Image 参数和 Size）
• 从右到左支持（RightToLeft 属性）
• 详细信息视图（带有“详细信息”按钮的可展开/折叠详细信息面板）
• 调整大小支持（CanResize 属性，右下角带有拖动手柄）
• 各种按钮类型的完整示例
• 图标的位置和尺寸

---

视觉样式和主题

📄 阅读： references/visual-styles.md

阅读时机： 应用主题、匹配应用程序样式、使用 Office 配色方案时

涵盖主题：

• MessageBoxStyle 属性（Default、Office2007、Office2010、Metro、Office2013、Office2016）
• 默认主题
• Office2007 主题及其配色方案（Black、Blue、Silver、Managed）
• Office2010 主题及其配色方案（Black、Blue、Silver、Managed）
• Metro 主题（现代扁平设计）
• Office2013 主题（DarkGray、LightGray、White）
• Office2016 主题（Colorful、White、DarkGray）
• 主题枚举的用法（Office2007Theme、Office2010Theme、Office2013Theme、Office2016Theme）
• Managed 配色自定义（Office2007Colors.ApplyManagedColors、Office2010Colors.ApplyManagedColors）
• 所有主题和配色方案的完整示例

---

Metro 主题自定义

📄 阅读： references/metro-customization.md

阅读时机： 自定义 Metro 主题颜色、为消息框添加品牌标识、匹配企业配色时

涵盖主题：

• MetroColorTable 类概述
• ForeColor 属性（消息文本颜色）
• BackColor 属性（对话框背景色）
• BorderColor 属性（对话框边框颜色）
• CaptionBarColor 属性（标题栏背景色）
• CaptionForeColor 属性（标题栏文本颜色）
• 按钮背景色（OKButtonBackColor、YesButtonBackColor、NoButtonBackColor、CancelButtonBackColor、RetryButtonBackColor、AbortButtonBackColor、IgnoreButtonBackColor）
• 按钮前景色（按钮文本颜色）
• CloseButtonColor 和 CloseButtonHoverColor
• Metro 自定义完整示例
• 配色协调最佳实践
• 创建自定义品牌消息框

---

本地化支持

📄 阅读： references/localization.md

阅读时机： 实现多语言应用、本地化按钮文本、进行国际化部署时

涵盖主题：

• 本地化概述和工作流
• ILocalizationProvider 接口实现
• LocalizationProvider.Provider 属性初始化
• GetLocalizedString() 方法实现
• ResourceIdentifiers 类常量（Yes、No、OK、Cancel、Retry、Abort、Ignore、Details、Close）
• 特定区域设置的字符串映射
• 在 InitializeComponent 之前初始化
• 用于查找资源的 switch 语句模式
• 完整的本地化示例（德语、西班牙语、法语）
• 多语言支持最佳实践
• 创建自定义 Localizer 类

---

快速入门示例

使用 Metro 主题的基本消息框

C#：

using Syncfusion.Windows.Forms;

// Set Metro theme globally
MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Metro;

// Display simple message box
MessageBoxAdv.Show(this, "File saved successfully!", "Success", 
    MessageBoxButtons.OK, MessageBoxIcon.Information);

// Confirmation dialog with Yes/No
DialogResult result = MessageBoxAdv.Show(this, "Save changes?", "File Modified", 
    MessageBoxButtons.YesNo, MessageBoxIcon.Question);

if (result == DialogResult.Yes)
{
    // Save changes
}

VB.NET：

Imports Syncfusion.Windows.Forms

' Set Metro theme globally
MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Metro

' Display simple message box
MessageBoxAdv.Show(Me, "File saved successfully!", "Success", _
    MessageBoxButtons.OK, MessageBoxIcon.Information)

' Confirmation dialog with Yes/No
Dim result As DialogResult = MessageBoxAdv.Show(Me, "Save changes?", "File Modified", _
    MessageBoxButtons.YesNo, MessageBoxIcon.Question)

If result = DialogResult.Yes Then
    ' Save changes
End If

---

常见模式

模式 1：文件保存确认对话框

场景： 关闭前提示用户保存更改

C#：

using Syncfusion.Windows.Forms;

// Set Office2016 Colorful theme
MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Office2016;
MessageBoxAdv.Office2016Theme = Office2016Theme.Colorful;

// Show confirmation with YesNoCancel
DialogResult result = MessageBoxAdv.Show(
    this,
    "Do you want to save changes to Document1.txt?",
    "Unsaved Changes",
    MessageBoxButtons.YesNoCancel,
    MessageBoxIcon.Question
);

switch (result)
{
    case DialogResult.Yes:
        SaveDocument();
        CloseDocument();
        break;
    case DialogResult.No:
        CloseDocument();
        break;
    case DialogResult.Cancel:
        // Do nothing, stay in editor
        break;
}

---

模式 2：带自定义图标和详细信息视图的错误消息

场景： 显示错误及详细堆栈跟踪或日志信息

C#：

using Syncfusion.Windows.Forms;
using System.Drawing;

// Load custom error icon
Image customIcon = Image.FromFile("error_icon.png");

// Set theme
MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Metro;

// Show with details view
MessageBoxAdv.Show(
    this,
    "Failed to connect to database server.",
    "Connection Error",
    MessageBoxButtons.RetryCancel,
    customIcon,
    new Size(48, 48),
    "Error Details:\n" +
    "Server: db.company.com\n" +
    "Port: 1433\n" +
    "Timeout: Connection timeout after 30 seconds\n" +
    "Stack Trace: at System.Data.SqlClient.SqlConnection.Open()"
);

---

模式 3：本地化消息框（德语）

场景： 显示按钮文本和消息均为德语的消息框

C#：

using Syncfusion.Windows.Forms;
using System.Globalization;

// Implement custom localizer
public class GermanLocalizer : ILocalizationProvider
{
    public string GetLocalizedString(CultureInfo culture, string name, object obj)
    {
        switch (name)
        {
            case ResourceIdentifiers.Yes:
                return "Ja";
            case ResourceIdentifiers.No:
                return "Nein";
            case ResourceIdentifiers.OK:
                return "OK";
            case ResourceIdentifiers.Cancel:
                return "Abbrechen";
            case ResourceIdentifiers.Retry:
                return "Wiederholen";
            case ResourceIdentifiers.Abort:
                return "Abbrechen";
            case ResourceIdentifiers.Ignore:
                return "Ignorieren";
            case ResourceIdentifiers.Details:
                return "Details";
            default:
                return string.Empty;
        }
    }
}

// Initialize localizer before showing message box
LocalizationProvider.Provider = new GermanLocalizer();

// Show localized message box
MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Office2013;
MessageBoxAdv.Office2013Theme = Office2013Theme.White;

MessageBoxAdv.Show(
    this,
    "Möchten Sie die Änderungen speichern?",
    "Datei geändert",
    MessageBoxButtons.YesNoCancel,
    MessageBoxIcon.Question
);

---

关键属性

静态属性

属性	类型	描述
MessageBoxStyle	MessageBoxAdv.Style	设置主题：Default、Office2007、Office2010、Metro、Office2013、Office2016
Office2007Theme	Office2007Theme	Office2007 配色方案：Black、Blue、Silver、Managed
Office2010Theme	Office2010Theme	Office2010 配色方案：Black、Blue、Silver、Managed
Office2013Theme	Office2013Theme	Office2013 配色方案：DarkGray、LightGray、White
Office2016Theme	Office2016Theme	Office2016 配色方案：Colorful、White、DarkGray
MetroColorTable	MessageBoxAdvMetroColorTable	Metro 主题颜色自定义
RightToLeft	RightToLeft	启用 RTL 布局：Yes、No
CanResize	bool	启用运行时拖动调整大小

Show() 方法参数

参数	类型	说明
owner	IWin32Window	父窗口（通常为 this 或窗体实例）
text	string	要显示的消息文本
caption	string	标题栏文本
buttons	MessageBoxButtons	按钮组合：OK、OKCancel、YesNo、YesNoCancel、RetryCancel、AbortRetryIgnore
icon	MessageBoxIcon	内置图标：Asterisk、Error、Exclamation、Hand、Information、None、Question、Stop、Warning
icon	Image	自定义图标图像
iconSize	Size	自定义图标尺寸（宽度、高度）
details	string	可展开的详细文本（显示“Details”按钮）

返回值

类型： DialogResult

值： OK、Cancel、Yes、No、Retry、Abort、Ignore、None

---

常见用例

1. 确认退出应用程序

用户尝试关闭有未保存工作的应用程序：

DialogResult result = MessageBoxAdv.Show(this, 
    "You have unsaved changes. Exit anyway?", 
    "Confirm Exit", 
    MessageBoxButtons.YesNo, 
    MessageBoxIcon.Warning);

if (result == DialogResult.Yes)
{
    Application.Exit();
}

2. 文件操作错误

显示带重试选项的错误：

DialogResult result = MessageBoxAdv.Show(this, 
    "File is locked by another process.", 
    "File Access Error", 
    MessageBoxButtons.RetryCancel, 
    MessageBoxIcon.Error);

if (result == DialogResult.Retry)
{
    AttemptFileAccess();
}

3. 信息消息

显示不带选项的简单通知：

MessageBoxAdv.Show(this, 
    "Backup completed successfully!", 
    "Backup Complete", 
    MessageBoxButtons.OK, 
    MessageBoxIcon.Information);

4. 确认删除

确认具有破坏性的操作：

DialogResult result = MessageBoxAdv.Show(this, 
    "Are you sure you want to delete this record? This cannot be undone.", 
    "Confirm Delete", 
    MessageBoxButtons.YesNo, 
    MessageBoxIcon.Exclamation);

if (result == DialogResult.Yes)
{
    DeleteRecord();
}

5. 符合企业主题的对话框

使消息框与企业品牌形象保持一致：

MessageBoxAdv.MessageBoxStyle = MessageBoxAdv.Style.Metro;
MessageBoxAdv.MetroColorTable.CaptionBarColor = Color.FromArgb(0, 120, 215); // Corporate blue
MessageBoxAdv.MetroColorTable.YesButtonBackColor = Color.FromArgb(0, 120, 215);
MessageBoxAdv.MetroColorTable.NoButtonBackColor = Color.FromArgb(82, 82, 82);

MessageBoxAdv.Show(this, 
    "Upload to cloud storage?", 
    "Company Portal", 
    MessageBoxButtons.YesNo, 
    MessageBoxIcon.Question);

---

其他资源

程序集： Syncfusion.Shared.Base.dll
命名空间： Syncfusion.Windows.Forms
NuGet 包： Syncfusion.Shared.Base
最低 .NET Framework 版本： 4.5

主要类：

• MessageBoxAdv - 用于显示消息框的主要静态类
• MessageBoxAdvMetroColorTable - Metro 主题颜色自定义
• ILocalizationProvider - 本地化接口
• LocalizationProvider - 本地化提供程序注册
• ResourceIdentifiers - 用于本地化的资源字符串常量

相关技能：

• 窗体样式设置与主题
• 对话框管理
• 用户输入验证
• 错误处理模式