【WinForm UI控件系列】Collapse折叠面板，支持自动滚动条，支持边框，颜色定义，支持布满，支持透明、手风琴模式、扩展按钮

Collapse 是一个现代化的折叠面板控件，特点如下：

• 展开/折叠动画：平滑的展开和折叠过渡效果
• 手风琴模式：支持每次只展开一个面板
• 主题支持：实现 IThemeable 接口，支持亮暗主题切换
• 自定义颜色：支持自定义头部背景色、悬停色等
• 边框控制：支持边框显示/隐藏、圆角设置
• 内容灵活：支持文本内容和自定义控件内容
• FillRemaining：支持某面板铺满剩余空间
• 透明背景：支持透明背景，融入各种界面风格
• 点击交互：头部区域点击展开/折叠，鼠标悬停显示手形光标

一、效果图

二、使用说明

Collapse

中文名称

折叠面板控件

控件优点

Collapse 是一个现代化的折叠面板控件，参考 Ant Design Collapse 组件设计，具有以下优点：

• 展开/折叠动画：平滑的展开和折叠过渡效果
• 手风琴模式：支持每次只展开一个面板
• 主题支持：实现 IThemeable 接口，支持亮暗主题切换
• 自定义颜色：支持自定义头部背景色、悬停色等
• 边框控制：支持边框显示/隐藏、圆角设置
• 内容灵活：支持文本内容和自定义控件内容
• FillRemaining：支持某面板铺满剩余空间
• 透明背景：支持透明背景，融入各种界面风格
• 点击交互：头部区域点击展开/折叠，鼠标悬停显示手形光标

重要参数说明

Collapse 控件属性

属性	类型	默认值	说明
ActiveKeys	List<string>	空列表	当前展开的面板 key 集合
DefaultActiveKeys	List<string>	空列表	默认展开的面板 key 集合
Accordion	bool	false	是否启用手风琴模式（每次只展开一个面板）
Bordered	bool	true	是否显示边框
Ghost	bool	false	是否启用幽灵模式（无边框、透明背景）
BorderRadius	int	6	面板圆角大小（像素）
HeaderHeight	int	48	面板头部高度（像素）
ContentPadding	int	16	内容区域内边距（像素）
HeaderBackColor	Color	#FAFAFA	头部背景色
HeaderHoverBackColor	Color	#F5F5F5	头部悬停背景色
HeaderForeColor	Color	#333333	头部文字颜色
ContentBackColor	Color	#FFFFFF	内容区域背景色
BorderColor	Color	#E8E8E8	边框颜色
FollowGlobalTheme	bool	true	是否跟随全局主题变化
IconPosition	ExpandIconPosition	Start	展开图标位置（Start=左侧，End=右侧）
AutoScroll	bool	true	是否启用内容自动滚动
MaxContentHeight	int	200	内容区域最大高度（像素）

CollapsePanel 面板属性

属性	类型	默认值	说明
Key	string	-	面板唯一标识
Header	string	-	面板标题文本
Content	string	-	面板内容文本（与 ContentControl 二选一）
ContentControl	Control	null	面板内容控件（与 Content 二选一）
FillRemaining	bool	false	是否铺满剩余空间
Disabled	bool	false	是否禁用该面板
ShowArrow	bool	true	是否显示展开箭头
Extra	string	null	额外内容（显示在头部右侧）
HeaderFont	Font	null	头部字体（默认使用控件字体）
ContentFont	Font	null	内容字体（默认使用控件字体）
IconSvg	string	null	自定义图标按钮的 SVG 图标名称（如 "setting"）
IconSvgColor	Color	Gray	自定义图标的颜色
IconSvgSize	float	16f	自定义图标的大小（像素）

重要事件

事件	说明
ActiveKeyChanged	展开/折叠状态改变时触发
PanelClick	点击面板头部时触发（会切换展开状态）
PanelIconClick	点击自定义图标按钮时触发（不切换展开状态）
PropertyChanged	属性值变更时触发（实现 INotifyPropertyChanged）

公共方法

方法	说明
AddPanel(string key, string header, string content = "")	添加文本内容面板
AddPanel(string key, string header, Control contentControl)	添加控件内容面板
RemovePanel(string key)	移除指定面板
Expand(string key)	展开指定面板
CollapsePanel(string key)	折叠指定面板
ExpandAll()	展开所有面板
CollapseAll()	折叠所有面板

使用示例

基础使用

// 创建折叠面板控件
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300),
    Bordered = true,
    BorderRadius = 8
};

// 添加面板
collapse.AddPanel("panel1", "面板1", "面板1的内容文本");
collapse.AddPanel("panel2", "面板2", "面板2的内容文本");
collapse.AddPanel("panel3", "面板3", "面板3的内容文本");

// 设置默认展开的面板
collapse.DefaultActiveKeys = new List<string> { "panel1" };

this.Controls.Add(collapse);

手风琴模式

// 手风琴模式：每次只展开一个面板
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300),
    Accordion = true,  // 启用手风琴模式
    Bordered = true
};

collapse.AddPanel("panel1", "面板1", "内容1");
collapse.AddPanel("panel2", "面板2", "内容2");
collapse.AddPanel("panel3", "面板3", "内容3");

this.Controls.Add(collapse);

添加自定义控件内容

// 创建折叠面板
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300)
};

// 创建自定义控件
var panel = new Panel();
panel.BackColor = Color.LightBlue;
panel.Size = new Size(380, 100);

var label = new Label();
label.Text = "自定义控件内容";
label.Dock = DockStyle.Fill;
label.TextAlign = ContentAlignment.MiddleCenter;
panel.Controls.Add(label);

// 添加带控件内容的面板
collapse.AddPanel("panel1", "面板1（自定义控件）", panel);
collapse.AddPanel("panel2", "面板2", "普通文本内容");

this.Controls.Add(collapse);

FillRemaining 铺满剩余空间

// 创建折叠面板
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 400),
    Bordered = true
};

// 添加多个面板
collapse.AddPanel("panel1", "面板1", "内容1");
collapse.AddPanel("panel2", "面板2", "内容2");

// 获取第三个面板并设置 FillRemaining
var panel3 = new CollapsePanel("panel3", "面板3（铺满）", "这个面板会铺满剩余空间");
panel3.FillRemaining = true;
collapse.Panels.Add(panel3);

this.Controls.Add(collapse);

自定义颜色

// 自定义颜色的折叠面板
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300),
    HeaderBackColor = Color.FromArgb(24, 144, 255),
    HeaderForeColor = Color.White,
    HeaderHoverBackColor = Color.FromArgb(64, 169, 255),
    ContentBackColor = Color.FromArgb(240, 248, 255),
    BorderColor = Color.FromArgb(24, 144, 255)
};

collapse.AddPanel("panel1", "自定义颜色面板", "自定义颜色示例");

this.Controls.Add(collapse);

事件处理

var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300)
};

collapse.AddPanel("panel1", "面板1", "内容1");
collapse.AddPanel("panel2", "面板2", "内容2");

// 监听展开/折叠事件
collapse.ActiveKeyChanged += (sender, e) =>
{
    // e.Key: 当前触发的面板key
    // e.IsExpanded: 是否为展开状态
    // e.ActiveKeys: 当前所有展开的面板key集合
    Console.WriteLine($"面板 {e.Key} 状态变为: {e.IsExpanded}");
    Console.WriteLine($"当前展开的面板: {string.Join(", ", e.ActiveKeys)}");
};

this.Controls.Add(collapse);

自定义图标按钮

// 创建折叠面板
var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300),
    IconPosition = Collapse.ExpandIconPosition.End  // 展开箭头在右侧
};

// 创建带自定义图标的面板
var panel1 = new CollapsePanel("panel1", "面板1", "内容文本...");
panel1.IconSvg = "setting";        // 设置图标
panel1.IconSvgColor = Color.Gray;   // 图标颜色（悬停时变为主题色）
panel1.IconSvgSize = 16f;           // 图标大小
collapse.Panels.Add(panel1);

collapse.AddPanel("panel2", "面板2", "内容2");
collapse.AddPanel("panel3", "面板3", "内容3");

// 绑定面板点击事件（会切换展开状态）
collapse.PanelClick += (sender, e) =>
{
    Console.WriteLine($"点击了面板头部: {e.Panel.Key}");
};

// 绑定自定义图标点击事件（不切换展开状态）
collapse.PanelIconClick += (sender, e) =>
{
    // 用户点击了设置图标，可自定义处理逻辑
    MessageBox.Show($"点击了面板 {e.Panel.Key} 的设置按钮");
};

this.Controls.Add(collapse);

程序化控制

var collapse = new Collapse
{
    Location = new Point(20, 20),
    Size = new Size(400, 300)
};

collapse.AddPanel("panel1", "面板1", "内容1");
collapse.AddPanel("panel2", "面板2", "内容2");
collapse.AddPanel("panel3", "面板3", "内容3");

this.Controls.Add(collapse);

// 展开指定面板
collapse.Expand("panel1");

// 折叠指定面板
collapse.CollapsePanel("panel2");

// 展开所有面板
collapse.ExpandAll();

// 折叠所有面板
collapse.CollapseAll();

界面布局说明

折叠面板整体布局如下：

┌──────────────────────────────────────────────┐
│ [箭头] 面板标题                              │ [额外内容]
├──────────────────────────────────────────────┤
│ 面板内容区域（展开时显示）                     │
│                                              │
└──────────────────────────────────────────────┘

布局特点

1. 头部区域：包含展开箭头、标题文本和可选的额外内容
2. 内容区域：可显示文本或自定义控件，展开时带平滑动画
3. 边框样式：第一个面板顶部圆角，最后一个面板底部圆角，中间面板直角
4. 交互反馈：鼠标悬停头部区域时显示手形光标

主题适配

Collapse 控件实现了 IThemeable 接口，支持亮暗主题切换：

// 跟随全局主题（默认）
collapse.FollowGlobalTheme = true;

// 手动设置主题
collapse.ApplyTheme(isDark);

主题颜色映射

控件元素	亮色模式	暗色模式
头部背景	#FAFAFA	#2D2D2D
头部悬停	#F5F5F5	#3D3D3D
头部文字	#333333	#E0E0E0
内容背景	#FFFFFF	#1E1E1E
边框颜色	#E8E8E8	#3D3D3D

注意事项

1. 内容控件生命周期：添加到面板的控件会被自动管理，建议不要在其他地方同时引用该控件

2. FillRemaining 限制 ：建议只对一个面板设置 FillRemaining = true，多个面板设置可能导致布局异常

3. 动画性能：启用动画时，内容控件会在动画过程中动态调整大小，复杂控件可能影响性能

4. 透明背景 ：设置 Ghost = true 或 Bordered = false 可实现无边框透明效果

5. 自定义颜色优先级 ：手动设置的颜色属性（如 HeaderBackColor）会覆盖主题颜色，除非再次调用 ApplyTheme

6. 最小尺寸：建议控件最小高度不小于头部高度，否则可能显示异常

7. 嵌套使用：支持嵌套使用 Collapse 控件，但需要注意布局和性能问题

三、后记

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