【WinForm UI控件系列】磁贴控件MetroTilePanel（磁贴Tile布局容器）、MetroTileItem和explorerBar控件，很漂亮！

MetroTilePanel 包含子控件 MetroTileItem。

思路来源参考：DotNetBar2 ，我的文章：https://blog.csdn.net/uaime/article/details/137401008

一、展现效果

标题、副标题、文本、图标支持9位置自定义

支持iconsvg图标，支持角标，磁贴支持3种形状（圆角、直角、平角）

磁贴支持5种排序，并支持升序、降序排列，推荐按TabIndex排序

二、使用说明

2.1 MetroTilePanel 磁贴面板容器

MetroTilePanel 磁贴面板容器

控件名称

MetroTilePanel

中文名称

磁贴面板容器

控件优点

MetroTilePanel 是一个磁贴面板容器，支持流式布局、自动换行和分组管理。适用于磁贴菜单、快捷入口等场景。

主要特性

流式布局：支持流式布局和自动换行
磁贴管理：支持磁贴项的添加、删除、管理
间距控制：支持项间距和行间距设置
点击事件：支持磁贴点击事件
自动布局：支持自动调整布局
设计时支持：支持在 Visual Studio 设计器中直接添加和管理磁贴项
右键菜单：支持右键上下文菜单快速操作
主题适配：支持亮/暗主题自动切换

重要参数说明

基本属性

属性名	类型	默认值	说明
`TileItems`	`MetroTileItemCollection`	-	磁贴项集合（设计时可通过集合编辑器编辑）
`ItemSpacing`	`int`	`8`	项间距（像素）
`LineSpacing`	`int`	`8`	行间距（像素）
`ItemWidth`	`int`	`120`	项宽度（新添加项的默认尺寸）
`ItemHeight`	`int`	`120`	项高度（新添加项的默认尺寸）
`ShowTooltip`	`bool`	`false`	是否显示磁贴提示

布局属性

属性名	类型	默认值	说明
`AutoScroll`	`bool`	`true`	是否自动滚动
`AutoSize`	`bool`	`false`	是否自动调整大小
`AllowDrop`	`bool`	`false`	是否允许拖放（运行时支持）

主题属性

属性名	类型	默认值	说明
`FollowGlobalTheme`	`bool`	`true`	是否跟随全局主题变化

主题颜色说明：

MetroTilePanel 本身作为容器背景色会自动适应主题变化：

亮色模式 ：背景使用 Color.FromArgb(250, 250, 250)
暗色模式 ：背景使用 Color.FromArgb(40, 40, 40)

磁贴项（MetroTileItem）的主题适配由其自身的 FollowGlobalTheme 属性控制。

设计时支持

属性窗口编辑

在 Visual Studio 设计器中，选中 MetroTilePanel 控件后，可在属性窗口中找到 TileItems 属性：

点击 TileItems 属性右侧的按钮（...）打开集合编辑器
在集合编辑器中可以添加、删除、编辑 MetroTileItem 项
每项的属性（标题、副标题、背景色、图标等）都可以在右侧属性窗口中编辑
点击"确定"后，设计界面会立即显示添加的磁贴项
设计器代码会自动生成 TileItems.Add() 调用

右键菜单操作

在设计器界面中，右键点击 MetroTilePanel 可打开上下文菜单：

添加 MetroTileItem：快速添加一个新的磁贴项
编辑 TileItems：打开集合编辑器

设计时注意事项

自动同步 ：TileItems 集合会自动与 Controls 集合同步
- 添加到 TileItems 的项会自动添加到 Controls 集合
- 从 TileItems 移除的项会自动从 Controls 集合移除
- 清空 TileItems 会自动清空所有子控件
Z-Order 管理：磁贴项会自动置于最前面，避免被其他控件遮挡
设计时可见性 ：所有在 TileItems 中添加的项在设计界面中都会显示

重要事件

事件名	说明
`ItemClick`	磁贴点击时触发
`PropertyChanged`	属性值改变时触发

ItemClick 事件示例：

csharp 复制代码

panel.ItemClick += (sender, e) =>
{
    // e.Item 返回被点击的 MetroTileItem
    MessageBox.Show($"点击了：{e.Item.TitleText}");
};

使用示例

示例1：基本使用（代码方式）

csharp 复制代码

// 创建磁贴面板
MetroTilePanel panel = new MetroTilePanel();
panel.Size = new Size(600, 400);
this.Controls.Add(panel);

// 添加磁贴项
MetroTileItem tile1 = new MetroTileItem();
tile1.TitleText = "首页";
tile1.SubTitleText = "返回首页";
tile1.BackColor = Color.FromArgb(0, 122, 204);
panel.TileItems.Add(tile1);

MetroTileItem tile2 = new MetroTileItem();
tile2.TitleText = "设置";
tile2.SubTitleText = "系统设置";
tile2.BackColor = Color.FromArgb(255, 87, 34);
panel.TileItems.Add(tile2);

// 点击事件
panel.ItemClick += (sender, e) =>
{
    Console.WriteLine($"点击了：{e.Item.TitleText}");
};

示例2：设计时添加（推荐方式）

csharp 复制代码

// 1. 从工具箱拖放 MetroTilePanel 到窗体
// 2. 在属性窗口中找到 TileItems 属性
// 3. 点击 ... 按钮打开集合编辑器
// 4. 点击"添加"按钮添加 MetroTileItem
// 5. 在右侧属性窗口中设置各项属性：
//    - TitleText: "首页"
//    - SubTitleText: "返回首页"
//    - BackColor: 自定义颜色
//    - IconSvg: "home"
// 6. 点击"确定"完成编辑
// 7. 设计界面会立即显示添加的磁贴

生成的 Designer.cs 代码示例：

csharp 复制代码

// Form1.Designer.cs
private void InitializeComponent()
{
    // ...
    
    // metroTilePanel1
    this.metroTilePanel1.Location = new System.Drawing.Point(12, 12);
    this.metroTilePanel1.Name = "metroTilePanel1";
    this.metroTilePanel1.Size = new System.Drawing.Size(600, 400);
    
    // metroTileItem1
    this.metroTileItem1.BackColor = System.Drawing.Color.FromArgb(0, 122, 204);
    this.metroTileItem1.Name = "metroTileItem1";
    this.metroTileItem1.SubTitleText = "返回首页";
    this.metroTileItem1.TitleText = "首页";
    
    // 添加到集合
    this.metroTilePanel1.TileItems.Add(this.metroTileItem1);
    
    // ...
}

示例3：动态添加项

csharp 复制代码

// 动态添加磁贴项
Random _random = new Random();

for (int i = 0; i < 10; i++)
{
    MetroTileItem tile = new MetroTileItem();
    tile.TitleText = $"项{i + 1}";
    tile.SubTitleText = $"描述{i + 1}";
    tile.BackColor = Color.FromArgb(
        _random.Next(100, 255),
        _random.Next(100, 255),
        _random.Next(100, 255));
    panel.TileItems.Add(tile);
}

示例4：间距设置

csharp 复制代码

// 设置项间距
panel.ItemSpacing = 10;

// 设置行间距
panel.LineSpacing = 10;

示例5：项尺寸

csharp 复制代码

// 设置新添加项的默认尺寸
panel.ItemWidth = 150;
panel.ItemHeight = 150;

// 注意：这只会影响新添加的项，已存在的项尺寸不变

示例6：遍历和操作磁贴项

csharp 复制代码

// 遍历所有磁贴项
foreach (MetroTileItem tile in panel.TileItems)
{
    Console.WriteLine($"标题: {tile.TitleText}");
}

// 根据索引获取项
if (panel.TileItems.Count > 0)
{
    MetroTileItem firstTile = panel.TileItems[0];
    firstTile.TitleText = "已修改的标题";
}

// 移除指定项
if (panel.TileItems.Count > 0)
{
    panel.TileItems.RemoveAt(0);
}

// 清空所有项
panel.TileItems.Clear();

示例7：主题适配

csharp 复制代码

// 创建磁贴面板（自动跟随主题）
MetroTilePanel panel = new MetroTilePanel
{
    Dock = DockStyle.Fill,
    FollowGlobalTheme = true  // 默认已启用
};

// 添加一些磁贴项
panel.TileItems.Add(new MetroTileItem 
{ 
    TitleText = "首页",
    BackColor = Color.FromArgb(0, 122, 204)
});

panel.TileItems.Add(new MetroTileItem 
{ 
    TitleText = "设置",
    BackColor = Color.FromArgb(255, 87, 34)
});

// 主题切换时，MetroTilePanel 背景色会自动适应
// MetroTileItem 的主题适配由其自身的 FollowGlobalTheme 属性控制

示例8：导航菜单场景

csharp 复制代码

// 创建导航菜单风格的磁贴面板
MetroTilePanel navPanel = new MetroTilePanel
{
    Dock = DockStyle.Fill,
    ItemSpacing = 12,
    LineSpacing = 12,
    ItemWidth = 140,
    ItemHeight = 100,
    BackColor = Color.FromArgb(245, 245, 245)
};

// 定义菜单项数据
var menuItems = new[]
{
    ("首页", "home", Color.FromArgb(24, 144, 255)),
    ("用户管理", "user", Color.FromArgb(82, 196, 26)),
    ("订单管理", "shopping", Color.FromArgb(250, 173, 20)),
    ("系统设置", "setting", Color.FromArgb(255, 77, 79)),
    ("数据统计", "bar-chart", Color.FromArgb(114, 46, 209)),
    ("消息中心", "bell", Color.FromArgb(19, 194, 194))
};

// 创建磁贴项
foreach (var (title, icon, color) in menuItems)
{
    var tile = new MetroTileItem
    {
        TitleText = title,
        SubTitleText = "点击进入",
        IconSvg = icon,
        BackColor = color,
        ForeColor = Color.White
    };
    navPanel.TileItems.Add(tile);
}

// 处理点击事件
navPanel.ItemClick += (sender, e) =>
{
    string title = e.Item.TitleText;
    
    switch (title)
    {
        case "首页":
            // 打开首页
            break;
        case "用户管理":
            // 打开用户管理
            break;
        // ... 其他菜单项处理
    }
};

this.Controls.Add(navPanel);

注意事项

流式布局：磁贴项会自动换行排列，根据面板宽度和项宽度自动计算每行显示的项数
项尺寸 ：ItemWidth 和 ItemHeight 只影响新添加的项，已存在的项尺寸不变
间距控制 ：
- ItemSpacing 控制水平方向项与项之间的间距
- LineSpacing 控制垂直方向行与行之间的间距
点击事件 ：ItemClick 事件返回被点击的 MetroTileItem，可通过 e.Item 访问
集合同步 ：TileItems 集合会自动与 Controls 集合同步，无需手动管理
设计时编辑：推荐使用设计时的集合编辑器添加和管理磁贴项，所见即所得
主题适配 ：设置 FollowGlobalTheme = true 可使面板背景色自动适应主题变化
Z-Order：磁贴项会自动置于最前面，确保点击事件正常触发

2.2 MetroTileItem 磁贴项控件

MetroTileItem 磁贴项控件

控件名称

MetroTileItem

中文名称

磁贴项控件

控件优点

MetroTileItem 是一个磁贴项控件，支持标题、副标题、图标显示和多种样式设置。适用于磁贴菜单、快捷入口等场景。

主要特性

双行文本：支持标题和副标题显示
图标支持：支持图片图标和 SVG 图标
文本对齐：支持多种文本对齐方式
圆角类型：支持多种圆角类型
颜色自定义：支持多种颜色自定义

重要参数说明

基本属性

属性名	类型	默认值	说明
`TitleText`	string	"Title"	标题文本
`SubTitleText`	string	"SubTitle"	副标题文本
`Icon`	Image	null	图标图片
`IconSvg`	string	""	SVG 图标名称
`IconColor`	Color	White	图标颜色

文本对齐（TileTextAlignment）

对齐值	说明
`TopLeft`	左上角
`TopCenter`	中上
`TopRight`	右上角
`MiddleLeft`	左中
`MiddleCenter`	居中
`MiddleRight`	右中
`BottomLeft`	左下角
`BottomCenter`	中下
`BottomRight`	右下角

圆角类型（CornerType）

类型值	说明
`Square`	直角（无圆角）
`Inherit`	继承控件圆角设置
`Rounded`	圆角
`Diagonal`	对角线（斜角）

颜色属性

属性名	类型	默认值	说明
`BackColor`	Color	0, 122, 204	背景色
`ForeColor`	Color	White	前景色
`TitleColor`	Color	White	标题颜色
`SubTitleColor`	Color	200, 200, 200	副标题颜色

重要事件

事件名	说明
`Click`	点击时触发
`PropertyChanged`	属性值改变时触发

使用示例

基本使用

csharp 复制代码

// 创建磁贴项
MetroTileItem tile = new MetroTileItem();
tile.Size = new Size(120, 120);
tile.TitleText = "设置";
tile.SubTitleText = "系统设置";
this.Controls.Add(tile);

图标设置

csharp 复制代码

// 设置图片图标
tile.Icon = Image.FromFile("icon.png");

// 设置 SVG 图标
tile.IconSvg = "setting";
tile.IconColor = Color.White;

文本对齐

csharp 复制代码

// 设置文本对齐方式
tile.TextAlignment = TileTextAlignment.TopLeft;
tile.TextAlignment = TileTextAlignment.MiddleCenter;
tile.TextAlignment = TileTextAlignment.BottomRight;

圆角类型

csharp 复制代码

// 设置圆角类型
tile.CornerType = CornerType.Square;    // 直角
tile.CornerType = CornerType.Rounded;   // 圆角
tile.CornerType = CornerType.Diagonal;  // 对角线

颜色自定义

csharp 复制代码

// 设置颜色
tile.BackColor = Color.FromArgb(0, 122, 204);
tile.TitleColor = Color.White;
tile.SubTitleColor = Color.FromArgb(200, 200, 200);

注意事项

图标类型：支持图片图标和 SVG 图标
文本对齐：TextAlignment 控制标题和副标题的对齐方式
圆角类型：CornerType 控制磁贴的圆角样式
颜色设置：BackColor 控制背景色，ForeColor 控制前景色

2.3 explorerBar控件

ExplorerBar 资源管理器栏控件

控件名称

ExplorerBar

中文名称

资源管理器栏控件

控件优点

ExplorerBar 是一个功能丰富的资源管理器栏控件，支持分组管理、展开/折叠、图标显示等功能。适用于导航菜单、分类展示等场景。

主要特性

分组管理：支持添加多个分组，每个分组可以包含多个按钮
展开/折叠：支持分组的展开和折叠
图标支持：支持分组和按钮显示SVG图标
自动布局：支持自动调整分组位置
滚动支持：支持自动滚动

重要参数说明

基本属性

属性名	类型	默认值	说明
`Groups`	ExplorerBarGroupCollection	-	分组集合
`GroupSpacing`	int	4	分组间距
`BackColor`	Color	Teal	背景颜色
`Padding`	Padding	4	内边距

ExplorerBarGroup 属性

属性名	类型	默认值	说明
`GroupText`	string	""	分组标题
`GroupTextAlign`	ContentAlignment	MiddleLeft	标题对齐方式
`IconSvg`	string	""	分组图标SVG
`IconSize`	int	16	图标大小
`Expanded`	bool	true	是否展开
`ShowExpandButton`	bool	true	是否显示展开按钮
`Buttons`	ExplorerBarButtonCollection	-	按钮集合
`ButtonHeight`	int	35	按钮默认高度，统一设置所有按钮高度（不影响单独设置了高度的按钮）
`HeaderBackColor`	Color	Orange	分组标题栏背景色
`HeaderForeColor`	Color	Black	分组标题栏前景色

主题支持

属性名	类型	默认值	说明
`FollowGlobalTheme`	bool	true	是否跟随全局主题变化

主题颜色说明：

元素	亮色模式	暗色模式
ExplorerBar 背景	浅灰 (240,240,240)	深灰 (45,45,48)
Group 标题背景	浅蓝 (64,158,255)	深蓝 (0,122,204)
Group 背景	浅灰 (245,245,245)	深灰 (60,60,60)
Button 悬停	浅蓝灰 (220,235,255)	深蓝灰 (60,80,110)
文字颜色	深灰 (50,50,50)	白色

ExplorerBarButton 属性

属性名	类型	默认值	说明
`Text`	string	""	按钮文本
`IconSvg`	string	""	按钮图标SVG
`IconSize`	int	16	图标大小
`Tag`	object	null	关联数据

重要事件

事件名	说明
`ButtonClick`	点击按钮时触发
`GroupExpandedChanged`	分组展开状态改变时触发

使用示例

基本使用

csharp 复制代码

// 创建资源管理器栏
ExplorerBar explorerBar = new ExplorerBar();
explorerBar.Size = new Size(250, 400);
explorerBar.BackColor = Color.Teal;
this.Controls.Add(explorerBar);

// 添加分组
ExplorerBarGroup group1 = new ExplorerBarGroup();
group1.GroupText = "文件管理";
group1.IconSvg = "folder";
explorerBar.Groups.Add(group1);

// 添加按钮
ExplorerBarButton button1 = new ExplorerBarButton();
button1.Text = "新建文件";
button1.IconSvg = "file-add";
group1.Buttons.Add(button1);

ExplorerBarButton button2 = new ExplorerBarButton();
button2.Text = "打开文件";
button2.IconSvg = "folder-open";
group1.Buttons.Add(button2);

分组展开/折叠

csharp 复制代码

// 展开分组
group1.Expanded = true;

// 折叠分组
group1.Expanded = false;

// 隐藏展开按钮
group1.ShowExpandButton = false;

图标设置

csharp 复制代码

// 分组图标
group1.IconSvg = "folder";
group1.IconSize = 20;

// 按钮图标
button1.IconSvg = "file";
button1.IconSize = 16;

标题对齐

csharp 复制代码

// 标题左对齐（默认）
group1.GroupTextAlign = ContentAlignment.MiddleLeft;

// 标题居中
group1.GroupTextAlign = ContentAlignment.MiddleCenter;

// 标题右对齐
group1.GroupTextAlign = ContentAlignment.MiddleRight;

按钮点击事件

csharp 复制代码

// 按钮点击事件
button1.Click += (sender, e) =>
{
    Console.WriteLine($"点击了按钮：{button1.Text}");
};

动态添加分组和按钮

csharp 复制代码

// 动态添加分组
private void AddGroup(string text, string iconSvg)
{
    ExplorerBarGroup group = new ExplorerBarGroup();
    group.GroupText = text;
    group.IconSvg = iconSvg;
    explorerBar.Groups.Add(group);
}

// 动态添加按钮
private void AddButton(ExplorerBarGroup group, string text, string iconSvg)
{
    ExplorerBarButton button = new ExplorerBarButton();
    button.Text = text;
    button.IconSvg = iconSvg;
    group.Buttons.Add(button);
}

// 使用示例
AddGroup("系统设置", "setting");
AddButton(explorerBar.Groups[0], "用户管理", "user");
AddButton(explorerBar.Groups[0], "权限设置", "lock");

设置间距

csharp 复制代码

// 设置分组间距
explorerBar.GroupSpacing = 8;

// 设置内边距
explorerBar.Padding = new Padding(8);

统一设置按钮高度

csharp 复制代码

// 统一设置分组内所有按钮的高度为 40（默认是 33）
group1.ButtonHeight = 40;

// 单独设置某个按钮的高度（不会被 ButtonHeight 影响）
ExplorerBarButton specialButton = new ExplorerBarButton();
specialButton.Text = "特殊按钮";
specialButton.Height = 50;  // 单独设置高度为 50
group1.Buttons.Add(specialButton);

// 其他按钮会自动使用 ButtonHeight (40)
ExplorerBarButton normalButton = new ExplorerBarButton();
normalButton.Text = "普通按钮";
// 不设置 Height，自动使用 group1.ButtonHeight (40)
group1.Buttons.Add(normalButton);

设置分组标题栏颜色

csharp 复制代码

// 设置分组标题栏背景色
group1.HeaderBackColor = Color.FromArgb(255, 128, 0);  // 橙色

// 设置分组标题栏前景色（文本颜色）
group1.HeaderForeColor = Color.White;

注意事项

分组集合：通过 Groups 属性管理分组，支持设计时编辑
按钮集合：每个分组通过 Buttons 属性管理按钮
图标大小：IconSize 控制图标显示大小，默认为16
展开状态：Expanded 控制分组的展开/折叠状态
自动布局：添加分组或按钮后会自动调整布局
按钮高度 ：
- ButtonHeight 属性统一设置分组内所有按钮的默认高度（默认33）
- 如果单独设置了按钮的 Height 属性（不是默认值33），则保留该高度
- 最小高度限制为20，小于20会自动调整为20
标题栏颜色 ：HeaderBackColor 和 HeaderForeColor 控制分组标题栏的颜色

更新日志

2025-04-18

新增 ButtonHeight 属性，支持统一设置分组内所有按钮的高度
完善文档，添加按钮高度和标题栏颜色的使用示例

三、后记

更多控件，敬请关注，如有需求、好的建议，请留言(xue5zhijing)

更多：https://blog.csdn.net/uaime/article/details/161663833