syncfusion-winforms-splitcontainer

在 Windows Forms 中实现 SplitContainerAdv

SplitContainerAdv 是一种容器控件，可帮助开发者创建带有可移动分隔条的可调整大小的双面板布局。当窗体需要灵活划分面板时，可以使用它。

何时使用此技能

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

• 在 Windows Forms 应用程序中创建可调整大小的分隔面板布局
• 在容器内的不同面板中添加控件
• 允许用户拖动分隔条调整面板大小
• 配置水平或垂直面板方向
• 自定义分隔条的外观和行为
• 动态折叠或展开面板
• 处理面板大小调整事件

组件概览

SplitContainerAdv 提供：

• 两个可调整大小的面板（Panel1 和 Panel2），由分隔条隔开
• 支持水平和垂直方向
• 面板折叠/展开功能
• 丰富的分隔条外观自定义选项
• 分隔条移动事件处理
• 嵌套容器支持（在 SplitContainerAdv 中嵌套 SplitContainerAdv）
• 视觉样式选项

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集依赖项和 NuGet 设置
• 创建新的 Windows Forms 项目
• 通过设计器添加 SplitContainerAdv
• 以编程方式添加 SplitContainerAdv
• 向面板添加子控件
• 设置分隔条方向

面板配置

📄 阅读： references/panel-configuration.md

• 面板方向（水平或垂直）
• 固定和可调整大小的面板
• 面板最小尺寸限制
• 在运行时折叠和展开面板
• 面板专属属性和行为

分隔条自定义

📄 阅读： references/splitter-customization.md

• 分隔条距离和位置
• 固定分隔条配置
• 分隔条宽度和增量设置
• 缩略图箭头和抓手外观
• 悬停状态自定义
• 运行时外观更改

外观和样式

📄 阅读： references/appearance-styling.md

• 背景颜色配置
• 前景属性（字体、颜色）
• 边框样式选项
• 面板专属外观覆盖
• 渐变和画刷自定义

事件和交互

📄 阅读： references/events-handling.md

• SplitterMoved 事件处理
• SplitterMoving 事件处理
• 常见事件模式
• 事件参数和数据访问
• 阻止分隔条移动

快速入门示例

SplitContainerAdv 的基本实现：

// Create and configure SplitContainerAdv
SplitContainerAdv splitContainer = new SplitContainerAdv();
splitContainer.Dock = DockStyle.Fill;
splitContainer.Orientation = Orientation.Horizontal;
splitContainer.SplitterDistance = 150;

// Add controls to panels
Label label1 = new Label { Text = "Panel 1", Dock = DockStyle.Fill };
Label label2 = new Label { Text = "Panel 2", Dock = DockStyle.Fill };

splitContainer.Panel1.Controls.Add(label1);
splitContainer.Panel2.Controls.Add(label2);

// Add to form
this.Controls.Add(splitContainer);

' Create and configure SplitContainerAdv
Dim splitContainer As New SplitContainerAdv()
splitContainer.Dock = DockStyle.Fill
splitContainer.Orientation = Orientation.Horizontal
splitContainer.SplitterDistance = 150

' Add controls to panels
Dim label1 As New Label With {.Text = "Panel 1", .Dock = DockStyle.Fill}
Dim label2 As New Label With {.Text = "Panel 2", .Dock = DockStyle.Fill}

splitContainer.Panel1.Controls.Add(label1)
splitContainer.Panel2.Controls.Add(label2)

' Add to form
Me.Controls.Add(splitContainer)

常见模式

模式 1：左侧面板固定，右侧面板可调整大小

splitContainer.Orientation = Orientation.Vertical;
splitContainer.FixedPanel = FixedPanel.Panel1;
splitContainer.Panel1MinSize = 200;
splitContainer.SplitterDistance = 200;

模式 2：可折叠面板

splitContainer.PanelToBeCollapsed = CollapsedPanel.Panel2;
splitContainer.TogglePanelOn = TogglePanelOn.DoubleClick;

模式 3：垂直布局，尺寸相等

splitContainer.Orientation = Orientation.Vertical;
splitContainer.SplitterDistance = splitContainer.Height / 2;
splitContainer.Panel1MinSize = 50;
splitContainer.Panel2MinSize = 50;

关键属性

属性	类型	用途
Orientation	Orientation	设置水平或垂直分隔（默认：水平）
SplitterDistance	int	从边缘到分隔条的距离，单位为像素
FixedPanel	FixedPanel	调整大小时保持固定的面板（Panel1、Panel2 或 None）
Panel1Collapsed	bool	Panel1 是否隐藏
Panel2Collapsed	bool	Panel2 是否隐藏
IsSplitterFixed	bool	分隔条是否可以移动
SplitterWidth	int	分隔条的宽度，单位为像素
Panel1MinSize	int	Panel1 的最小尺寸（默认值：25）
Panel2MinSize	int	Panel2 的最小尺寸（默认值：25）
ExpandFill	BrushInfo	展开箭头填充颜色
HotGripDark	BrushInfo	悬停时的抓手颜色

快速提示

• 默认方向： 左右分割使用 Orientation.Horizontal，上下分割使用 Orientation.Vertical
• 最小尺寸： 设置 Panel1MinSize 和 Panel2MinSize，以防面板收缩得过小
• 固定面板： 使用 FixedPanel 固定一侧，适用于工具栏或侧边栏
• 折叠面板： 当 TogglePanelOn = TogglePanelOn.DoubleClick 时，双击分隔条即可折叠面板
• 嵌套容器： 将 SplitContainerAdv 添加到另一个 SplitContainerAdv 的面板中，以构建复杂布局
• 停靠： 使用 Dock = DockStyle.Fill 使控件填满其父容器