syncfusion-winforms-metroform

实现 Syncfusion MetroForm

MetroForm 是一种 Syncfusion Windows Forms 控件，可为桌面应用程序提供现代 Metro UI 风格的扁平外观。它提供丰富的自定义选项，包括标题栏标签、图像、颜色、边框，以及圆角（Windows 11+）等高级功能。

何时使用此技能

在以下情况下使用此技能：

• 创建具有现代 Metro 风格的 Windows Forms 应用程序
• 使用标签、图像和自定义颜色自定义窗口标题栏
• 将标准 Windows Forms 替换为扁平、现代的外观
• 向窗体添加标题栏元素（标签、图像、图标）
• 自定义窗体边框、颜色和标题栏高度
• 在标题栏上实现自定义绘制
• 处理标题栏图像的鼠标事件
• 创建圆角窗体（Windows 11+）
• 使用现代 UI 构建专业的桌面应用程序

组件概述

MetroForm 扩展了标准 Windows Forms Form 类，提供：

• 现代 Metro UI 扁平外观
• 可自定义高度的标题栏
• 支持标题栏标签和图像
• 丰富的颜色自定义选项（边框、标题栏、按钮）
• 标题栏对齐选项（水平和垂直）
• 标题栏背景的自定义画笔效果
• 标题栏图像的鼠标事件处理
• 支持圆角（Windows 11+）
• 内置主题支持

主要功能

• 颜色自定义 - 标题栏背景色、前景色、控制框按钮颜色、边框颜色
• 标题栏元素 - 向标题栏添加标签和图像
• 帮助按钮支持 - 可选的标题栏帮助按钮
• 从右向左布局 - RTL 语言支持
• 灵活的对齐方式 - 标题文本和图标对齐选项
• 自定义绘制 - 用于高级标题栏自定义的绘制事件
• 现代外观 - 扁平 Metro 风格，可选圆角

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下阅读此参考文档：

• 首次安装和配置 MetroForm
• 设置程序集引用和 NuGet 包
• 使用 MetroForm 创建新项目
• 将现有 Form 转换为 MetroForm
• 添加基本的标题栏标签和图像
• 了解初始设置工作流

标题栏自定义

📄 阅读： references/caption-customization.md

在以下情况下阅读此参考文档：

• 通过设计器或代码添加标题栏标签
• 通过设计器或代码添加标题栏图像
• 配置 CaptionLabels 集合
• 配置 CaptionImages 集合
• 自定义标签属性（字体、颜色、大小、文本）
• 自定义图像属性（位置、大小、图像资源）

外观与样式

📄 阅读： references/appearance-styling.md

在以下情况下阅读此参考文档：

• 自定义边框粗细和颜色
• 设置标题栏高度和模式
• 更改标题栏颜色
• 对齐标题文本（左对齐、居中、右对齐）
• 垂直对齐标题文本（顶部、居中、底部）
• 配置图标对齐方式
• 自定义标题栏前景色和字体
• 设置标题栏按钮样式（颜色、悬停颜色）

高级自定义

📄 阅读： references/advanced-customization.md

在以下情况下阅读此参考文档：

• 为标题栏背景应用自定义画笔
• 使用 CaptionBarPaint 事件实现自定义绘制
• 在标题栏中创建渐变效果
• 处理标题栏图像的鼠标事件（MouseDown、MouseUp、MouseEnter、MouseLeave、MouseMove）
• 启用圆角（Windows 11+）
• 实现高级视觉效果

快速开始

步骤 1：安装包

Install-Package Syncfusion.Shared.Base

步骤 2：添加程序集引用

添加以下引用：

• Syncfusion.Shared.Base.dll

步骤 3：配置窗体

using Syncfusion.Windows.Forms;

namespace MyApplication
{
    // Inherit from MetroForm instead of Form
    public partial class MainForm : MetroForm
    {
        public MainForm()
        {
            InitializeComponent();
            
            // Basic configuration
            this.Text = "My Metro Application";
            this.CaptionBarHeight = 40;
            this.CaptionBarColor = Color.FromArgb(17, 158, 218);
            this.CaptionForeColor = Color.White;
            this.BorderColor = Color.FromArgb(17, 158, 218);
            this.BorderThickness = 2;
        }
    }
}

Imports Syncfusion.Windows.Forms

Namespace MyApplication
    ' Inherit from MetroForm instead of Form
    Public Partial Class MainForm
        Inherits MetroForm
        
        Public Sub New()
            InitializeComponent()
            
            ' Basic configuration
            Me.Text = "My Metro Application"
            Me.CaptionBarHeight = 40
            Me.CaptionBarColor = Color.FromArgb(17, 158, 218)
            Me.CaptionForeColor = Color.White
            Me.BorderColor = Color.FromArgb(17, 158, 218)
            Me.BorderThickness = 2
        End Sub
    End Class
End Namespace

常见模式

模式 1：添加标题栏标签

// Create and configure caption label
CaptionLabel captionLabel = new CaptionLabel();
captionLabel.Text = "Dashboard";
captionLabel.Font = new Font("Segoe UI", 10F, FontStyle.Regular);
captionLabel.ForeColor = Color.White;
captionLabel.Size = new Size(200, 24);

// Add to form
this.CaptionLabels.Add(captionLabel);

模式 2：添加带单击处理程序的标题栏图像

// Create and configure caption image
CaptionImage logoImage = new CaptionImage();
logoImage.Image = Properties.Resources.AppLogo;
logoImage.Location = new Point(10, 5);
logoImage.Size = new Size(32, 32);
logoImage.BackColor = Color.Transparent;

// Handle click event
logoImage.ImageMouseDown += (sender, e) =>
{
    MessageBox.Show("Logo clicked!");
};

// Add to form
this.CaptionImages.Add(logoImage);

模式 3：自定义标题栏渐变

// Apply gradient brush to caption bar
this.CaptionBarBrush = new LinearGradientBrush(
    new Rectangle(0, 0, this.Width, this.CaptionBarHeight),
    Color.DarkBlue,
    Color.LightBlue,
    LinearGradientMode.Horizontal
);

// Optional: Custom paint event for more control
this.CaptionBarPaint += (sender, e) =>
{
    using (var brush = new LinearGradientBrush(
        e.ClipRectangle,
        Color.DarkBlue,
        Color.LightBlue,
        LinearGradientMode.Horizontal))
    {
        e.Graphics.FillRectangle(brush, e.ClipRectangle);
    }
};

模式 4：圆角（Windows 11+）

// Enable rounded corners (Windows 11 only)
this.AllowRoundedCorners = true;
this.BorderColor = Color.FromArgb(17, 158, 218);

关键属性

标题栏属性

• CaptionBarHeight - 标题栏的高度（默认值因情况而异）
• CaptionBarColor - 标题栏的背景色
• CaptionForeColor - 标题栏中的文本颜色
• CaptionFont - 标题文本的字体
• CaptionAlign - 水平对齐方式（Left、Center、Right）
• CaptionVerticalAlignment - 垂直对齐方式（Top、Center、Bottom）
• CaptionBarHeightMode - 最大化时的高度行为

边框属性

• BorderColor - 窗体边框颜色
• BorderThickness - 边框厚度（像素）
• AllowRoundedCorners - 启用圆角（Windows 11+）

按钮属性

• CaptionButtonColor - 标题栏按钮（最小化、最大化、关闭）的颜色
• CaptionButtonHoverColor - 鼠标悬停时的按钮颜色

集合

• CaptionLabels - CaptionLabel 对象集合
• CaptionImages - CaptionImage 对象集合

图标属性

• IconAlign - 窗体图标的对齐方式（Left、Center、Right）

高级属性

• CaptionBarBrush - 标题栏背景的自定义画笔

常见用例

用例 1：仪表板应用程序

在标题栏中使用自定义品牌元素，创建现代化的仪表板：

this.Text = "Analytics Dashboard";
this.CaptionBarHeight = 50;
this.CaptionBarColor = Color.FromArgb(41, 128, 185);

// Add company logo
CaptionImage logo = new CaptionImage
{
    Image = Resources.CompanyLogo,
    Location = new Point(10, 10),
    Size = new Size(30, 30)
};
this.CaptionImages.Add(logo);

// Add title label
CaptionLabel title = new CaptionLabel
{
    Text = "Real-Time Analytics",
    Font = new Font("Segoe UI Semibold", 11F),
    ForeColor = Color.White
};
this.CaptionLabels.Add(title);

用例 2：设置对话框

创建简洁清爽的设置对话框：

this.Text = "Settings";
this.CaptionBarHeight = 35;
this.CaptionBarColor = Color.FromArgb(52, 73, 94);
this.CaptionForeColor = Color.White;
this.BorderColor = Color.FromArgb(52, 73, 94);
this.BorderThickness = 1;
this.FormBorderStyle = FormBorderStyle.FixedDialog;
this.MaximizeBox = false;
this.MinimizeBox = false;

用例 3：具有自定义外观的主应用程序窗口

创建具有渐变标题栏和自定义控件的主窗口：

// Gradient caption bar
this.CaptionBarBrush = new LinearGradientBrush(
    new Rectangle(0, 0, this.Width, this.CaptionBarHeight),
    Color.FromArgb(44, 62, 80),
    Color.FromArgb(52, 152, 219),
    LinearGradientMode.Horizontal
);

// Caption buttons
this.CaptionButtonColor = Color.White;
this.CaptionButtonHoverColor = Color.FromArgb(231, 76, 60);

// Add user info to caption
CaptionLabel userLabel = new CaptionLabel
{
    Text = "Welcome, John Doe",
    ForeColor = Color.White,
    Font = new Font("Segoe UI", 9F),
    Location = new Point(100, 10)
};
this.CaptionLabels.Add(userLabel);

事件

标题栏事件

• CaptionBarPaint - 标题栏需要重新绘制时触发（用于自定义绘制）

标题栏图像事件（每个图像）

• ImageMouseDown - 在标题栏图像上按下鼠标按钮
• ImageMouseUp - 在标题栏图像上释放鼠标按钮
• ImageMouseEnter - 鼠标进入标题栏图像区域
• ImageMouseLeave - 鼠标离开标题栏图像区域
• ImageMouseMove - 鼠标在标题栏图像区域内移动

故障排除

窗体未显示 Metro 样式

• 确保继承自 MetroForm，而不是 Form
• 确认已引用 Syncfusion.Shared.Base.dll
• 检查是否已导入命名空间 Syncfusion.Windows.Forms

标题栏标签/图像不可见

• 确认 CaptionBarHeight 足以容纳内容
• 检查前景色与标题栏颜色是否形成足够的对比
• 确保已为 Size 属性设置合适的值

圆角不起作用

• 圆角仅适用于 Windows 11+
• 设置 AllowRoundedCorners = true
• 注意：启用圆角后，边框和阴影由操作系统绘制

设计器错误

• 清理并重新生成解决方案
• 重启 Visual Studio
• 确保 NuGet 包已正确还原

相关组件

• Office2007Form - Office 2007 样式的窗体
• OfficeForm - 支持功能区的 Office 样式窗体
• Form - 标准 Windows Forms（用于比较）

更多资源

• MetroForm API 参考
• 控件依赖项
• NuGet 安装指南