syncfusion-winforms-metroform
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion MetroForm
实现Syncfusion MetroForm
MetroForm is a Syncfusion Windows Forms control that provides modern Metro UI styling with flat appearance for desktop applications. It offers extensive customization options including caption bar labels, images, colors, borders, and advanced features like rounded corners (Windows 11+).
MetroForm是Syncfusion推出的Windows Forms控件,可为桌面应用提供现代化Metro UI风格的扁平外观。它提供了丰富的自定义选项,包括标题栏标签、图片、颜色、边框,以及圆角(Windows 11及以上版本支持)等高级功能。
When to Use This Skill
什么时候使用本指南
Use this skill when you need to:
- Create modern, Metro-styled Windows Forms applications
- Customize window title bars with labels, images, and custom colors
- Replace standard Windows Forms with flat, modern appearance
- Add caption bar elements (labels, images, icons) to forms
- Customize form borders, colors, and caption bar height
- Implement custom painting on caption bars
- Handle mouse events for caption images
- Create rounded corner forms (Windows 11+)
- Build professional desktop applications with modern UI
当你需要完成以下操作时可使用本指南:
- 开发现代化Metro风格的Windows Forms应用
- 自定义窗口标题栏的标签、图片和自定义配色
- 将标准Windows Forms替换为扁平的现代化外观
- 为表单添加标题栏元素(标签、图片、图标)
- 自定义表单边框、颜色和标题栏高度
- 在标题栏上实现自定义绘制
- 处理标题栏图片的鼠标事件
- 创建圆角表单(Windows 11及以上版本支持)
- 开发具备现代化UI的专业桌面应用
Component Overview
组件概览
MetroForm extends the standard Windows Forms class with:
Form- Modern Metro UI flat appearance
- Customizable caption bar with configurable height
- Support for caption labels and images
- Extensive color customization (borders, caption bar, buttons)
- Caption alignment options (horizontal and vertical)
- Custom brush effects for caption bar background
- Mouse event handling for caption images
- Rounded corners support (Windows 11+)
- Built-in theme support
MetroForm 扩展了标准Windows Forms 类,具备以下特性:
Form- 现代化Metro UI扁平外观
- 可自定义高度的标题栏
- 支持标题标签和图片配置
- 丰富的颜色自定义能力(边框、标题栏、按钮)
- 标题对齐选项(水平和垂直方向)
- 标题栏背景自定义画笔效果
- 标题栏图片的鼠标事件处理
- 圆角效果支持(Windows 11及以上版本支持)
- 内置主题支持
Key Features
核心功能
- Color Customization - Caption background, foreground, control box buttons, border colors
- Caption Elements - Add labels and images to the caption bar
- Help Button Support - Optional help button in title bar
- Right-to-Left Layout - RTL language support
- Flexible Alignment - Caption text and icon alignment options
- Custom Painting - Paint events for advanced caption bar customization
- Modern Appearance - Flat Metro style with optional rounded corners
- 颜色自定义 - 标题栏背景、前景、控制盒按钮、边框颜色
- 标题栏元素 - 可向标题栏添加标签和图片
- 帮助按钮支持 - 标题栏可选添加帮助按钮
- 从右到左布局 - 支持RTL语言
- 灵活对齐 - 标题文本和图标对齐选项
- 自定义绘制 - 提供绘制事件用于高级标题栏自定义
- 现代化外观 - 扁平Metro风格,可选圆角效果
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
Read this reference when you need to:
- Install and configure MetroForm for the first time
- Set up assembly references and NuGet packages
- Create a new project with MetroForm
- Convert existing Form to MetroForm
- Add basic caption labels and images
- Understand the initial setup workflow
📄 阅读: references/getting-started.md
当你需要完成以下操作时阅读该参考文档:
- 首次安装和配置MetroForm
- 配置程序集引用和NuGet包
- 基于MetroForm创建新项目
- 将现有Form转换为MetroForm
- 添加基础的标题标签和图片
- 了解初始配置工作流
Caption Customization
标题栏自定义
📄 Read: references/caption-customization.md
Read this reference when you need to:
- Add caption labels through designer or code
- Add caption images through designer or code
- Configure CaptionLabels collection
- Configure CaptionImages collection
- Customize label properties (font, color, size, text)
- Customize image properties (location, size, image resource)
📄 阅读: references/caption-customization.md
当你需要完成以下操作时阅读该参考文档:
- 通过设计器或代码添加标题标签
- 通过设计器或代码添加标题图片
- 配置CaptionLabels集合
- 配置CaptionImages集合
- 自定义标签属性(字体、颜色、尺寸、文本)
- 自定义图片属性(位置、尺寸、图片资源)
Appearance and Styling
外观与样式
📄 Read: references/appearance-styling.md
Read this reference when you need to:
- Customize border thickness and color
- Set caption bar height and modes
- Change caption bar colors
- Align caption text (left, center, right)
- Align caption text vertically (top, center, bottom)
- Configure icon alignment
- Customize caption fore color and font
- Style caption buttons (color, hover color)
📄 阅读: references/appearance-styling.md
当你需要完成以下操作时阅读该参考文档:
- 自定义边框厚度和颜色
- 设置标题栏高度和模式
- 修改标题栏颜色
- 对齐标题文本(左对齐、居中、右对齐)
- 垂直对齐标题文本(顶部、居中、底部)
- 配置图标对齐方式
- 自定义标题前景色和字体
- 为标题按钮设置样式(颜色、悬停颜色)
Advanced Customization
高级自定义
📄 Read: references/advanced-customization.md
Read this reference when you need to:
- Apply custom brushes to caption bar background
- Implement custom painting with CaptionBarPaint event
- Create gradient effects in caption bar
- Handle mouse events for caption images (MouseDown, MouseUp, MouseEnter, MouseLeave, MouseMove)
- Enable rounded corners (Windows 11+)
- Implement advanced visual effects
📄 阅读: references/advanced-customization.md
当你需要完成以下操作时阅读该参考文档:
- 为标题栏背景应用自定义画笔
- 通过CaptionBarPaint事件实现自定义绘制
- 在标题栏中创建渐变效果
- 处理标题图片的鼠标事件(MouseDown、MouseUp、MouseEnter、MouseLeave、MouseMove)
- 启用圆角效果(Windows 11及以上版本支持)
- 实现高级视觉效果
Quick Start
快速开始
Step 1: Install Package
步骤1:安装包
bash
Install-Package Syncfusion.Shared.Basebash
Install-Package Syncfusion.Shared.BaseStep 2: Add Assembly Reference
步骤2:添加程序集引用
Add reference to:
Syncfusion.Shared.Base.dll
添加以下引用:
Syncfusion.Shared.Base.dll
Step 3: Configure Your Form
步骤3:配置你的表单
csharp
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;
}
}
}vb
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 Namespacecsharp
using Syncfusion.Windows.Forms;
namespace MyApplication
{
// 继承自MetroForm而非Form
public partial class MainForm : MetroForm
{
public MainForm()
{
InitializeComponent();
// 基础配置
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;
}
}
}vb
Imports Syncfusion.Windows.Forms
Namespace MyApplication
' 继承自MetroForm而非Form
Public Partial Class MainForm
Inherits MetroForm
Public Sub New()
InitializeComponent()
' 基础配置
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 NamespaceCommon Patterns
常用模式
Pattern 1: Adding Caption Label
模式1:添加标题标签
csharp
// 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);csharp
// 创建并配置标题标签
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);
// 添加到表单
this.CaptionLabels.Add(captionLabel);Pattern 2: Adding Caption Image with Click Handler
模式2:添加带点击事件的标题图片
csharp
// 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);csharp
// 创建并配置标题图片
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;
// 处理点击事件
logoImage.ImageMouseDown += (sender, e) =>
{
MessageBox.Show("Logo clicked!");
};
// 添加到表单
this.CaptionImages.Add(logoImage);Pattern 3: Custom Caption Bar Gradient
模式3:自定义标题栏渐变
csharp
// 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);
}
};csharp
// 为标题栏应用渐变画笔
this.CaptionBarBrush = new LinearGradientBrush(
new Rectangle(0, 0, this.Width, this.CaptionBarHeight),
Color.DarkBlue,
Color.LightBlue,
LinearGradientMode.Horizontal
);
// 可选:通过自定义绘制事件实现更多控制
this.CaptionBarPaint += (sender, e) =>
{
using (var brush = new LinearGradientBrush(
e.ClipRectangle,
Color.DarkBlue,
Color.LightBlue,
LinearGradientMode.Horizontal))
{
e.Graphics.FillRectangle(brush, e.ClipRectangle);
}
};Pattern 4: Rounded Corners (Windows 11+)
模式4:圆角效果(Windows 11及以上版本支持)
csharp
// Enable rounded corners (Windows 11 only)
this.AllowRoundedCorners = true;
this.BorderColor = Color.FromArgb(17, 158, 218);csharp
// 启用圆角效果(仅支持Windows 11)
this.AllowRoundedCorners = true;
this.BorderColor = Color.FromArgb(17, 158, 218);Key Properties
核心属性
Caption Bar Properties
标题栏属性
- - Height of the caption bar (default varies)
CaptionBarHeight - - Background color of caption bar
CaptionBarColor - - Text color in caption bar
CaptionForeColor - - Font for caption text
CaptionFont - - Horizontal alignment (Left, Center, Right)
CaptionAlign - - Vertical alignment (Top, Center, Bottom)
CaptionVerticalAlignment - - Height behavior on maximize
CaptionBarHeightMode
- - 标题栏高度(默认值不固定)
CaptionBarHeight - - 标题栏背景色
CaptionBarColor - - 标题栏文本颜色
CaptionForeColor - - 标题文本字体
CaptionFont - - 水平对齐方式(左对齐、居中、右对齐)
CaptionAlign - - 垂直对齐方式(顶部、居中、底部)
CaptionVerticalAlignment - - 最大化时的高度行为
CaptionBarHeightMode
Border Properties
边框属性
- - Color of the form border
BorderColor - - Thickness of the border in pixels
BorderThickness - - Enable rounded corners (Windows 11+)
AllowRoundedCorners
- - 表单边框颜色
BorderColor - - 边框厚度(单位:像素)
BorderThickness - - 启用圆角效果(Windows 11及以上版本支持)
AllowRoundedCorners
Button Properties
按钮属性
- - Color of caption buttons (minimize, maximize, close)
CaptionButtonColor - - Button color on hover
CaptionButtonHoverColor
- - 标题栏按钮颜色(最小化、最大化、关闭)
CaptionButtonColor - - 按钮悬停颜色
CaptionButtonHoverColor
Collections
集合属性
- - Collection of CaptionLabel objects
CaptionLabels - - Collection of CaptionImage objects
CaptionImages
- - CaptionLabel对象集合
CaptionLabels - - CaptionImage对象集合
CaptionImages
Icon Properties
图标属性
- - Alignment of form icon (Left, Center, Right)
IconAlign
- - 表单图标对齐方式(左对齐、居中、右对齐)
IconAlign
Advanced Properties
高级属性
- - Custom brush for caption bar background
CaptionBarBrush
- - 标题栏背景自定义画笔
CaptionBarBrush
Common Use Cases
常见使用场景
Use Case 1: Dashboard Application
场景1:仪表盘应用
Create a modern dashboard with custom branding in the caption bar:
csharp
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);创建标题栏带有自定义品牌标识的现代化仪表盘:
csharp
this.Text = "Analytics Dashboard";
this.CaptionBarHeight = 50;
this.CaptionBarColor = Color.FromArgb(41, 128, 185);
// 添加企业logo
CaptionImage logo = new CaptionImage
{
Image = Resources.CompanyLogo,
Location = new Point(10, 10),
Size = new Size(30, 30)
};
this.CaptionImages.Add(logo);
// 添加标题标签
CaptionLabel title = new CaptionLabel
{
Text = "Real-Time Analytics",
Font = new Font("Segoe UI Semibold", 11F),
ForeColor = Color.White
};
this.CaptionLabels.Add(title);Use Case 2: Settings Dialog
场景2:设置对话框
Create a simple, clean settings dialog:
csharp
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;创建简洁清爽的设置对话框:
csharp
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;Use Case 3: Main Application Window with Custom Appearance
场景3:带自定义外观的主应用窗口
Create a main window with gradient caption and custom controls:
csharp
// 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);创建带有渐变标题栏和自定义控件的主窗口:
csharp
// 渐变标题栏
this.CaptionBarBrush = new LinearGradientBrush(
new Rectangle(0, 0, this.Width, this.CaptionBarHeight),
Color.FromArgb(44, 62, 80),
Color.FromArgb(52, 152, 219),
LinearGradientMode.Horizontal
);
// 标题栏按钮
this.CaptionButtonColor = Color.White;
this.CaptionButtonHoverColor = Color.FromArgb(231, 76, 60);
// 在标题栏添加用户信息
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);Events
事件
Caption Bar Events
标题栏事件
- - Raised when caption bar needs repainting (for custom drawing)
CaptionBarPaint
- - 标题栏需要重绘时触发(用于自定义绘制)
CaptionBarPaint
Caption Image Events (per image)
标题图片事件(单图片)
- - Mouse button pressed on caption image
ImageMouseDown - - Mouse button released on caption image
ImageMouseUp - - Mouse enters caption image area
ImageMouseEnter - - Mouse leaves caption image area
ImageMouseLeave - - Mouse moves within caption image area
ImageMouseMove
- - 鼠标按下标题图片时触发
ImageMouseDown - - 鼠标释放标题图片时触发
ImageMouseUp - - 鼠标进入标题图片区域时触发
ImageMouseEnter - - 鼠标离开标题图片区域时触发
ImageMouseLeave - - 鼠标在标题图片区域移动时触发
ImageMouseMove
Troubleshooting
故障排查
Form Doesn't Show Metro Style
表单未显示Metro风格
- Ensure you're inheriting from , not
MetroFormForm - Verify is referenced
Syncfusion.Shared.Base.dll - Check that the namespace is imported
Syncfusion.Windows.Forms
- 确保你继承的是而非
MetroFormForm - 确认已引用
Syncfusion.Shared.Base.dll - 检查是否已导入命名空间
Syncfusion.Windows.Forms
Caption Labels/Images Not Visible
标题标签/图片不可见
- Verify is sufficient for the content
CaptionBarHeight - Check that foreground colors contrast with caption bar color
- Ensure Size property is set appropriately
- 确认足以容纳内容
CaptionBarHeight - 检查前景色与标题栏颜色是否有足够对比度
- 确保Size属性设置合理
Rounded Corners Not Working
圆角效果不生效
- Rounded corners only work on Windows 11+
- Set
AllowRoundedCorners = true - Note: Border and shadow are drawn by OS when rounded corners are enabled
- 圆角仅支持Windows 11及以上版本
- 确认已设置
AllowRoundedCorners = true - 注意:启用圆角后边框和阴影由操作系统绘制
Designer Errors
设计器报错
- Clean and rebuild the solution
- Restart Visual Studio
- Ensure NuGet packages are properly restored
- 清理并重新生成解决方案
- 重启Visual Studio
- 确认NuGet包已正确还原
Related Components
相关组件
- Office2007Form - Office 2007 styled forms
- OfficeForm - Office styled forms with ribbon support
- Form - Standard Windows Forms (for comparison)
- Office2007Form - Office 2007风格表单
- OfficeForm - 支持ribbon的Office风格表单
- Form - 标准Windows Forms(用于对比)