TableLayoutPanelEx 是一个功能强大的表格布局容器控件，在标准 TableLayoutPanel 基础上进行了大量增强，支持通过拖拽方式快速构建表单界面。提供网格线显示、表头行/列、单元格合并、控件对齐、行列尺寸精确控制等丰富功能，并内置设计时扩展属性支持，可在属性窗口直接配置子控件的位置和布局行为。

一、示例

二、文档

TableLayoutPanelEx 增强表格布局面板

控件名称

TableLayoutPanelEx

中文名称

增强表格布局面板

控件概述

TableLayoutPanelEx 是一个功能强大的表格布局容器控件，在标准 TableLayoutPanel 基础上进行了大量增强，支持通过拖拽方式快速构建表单界面。提供网格线显示、表头行/列、单元格合并、控件对齐、行列尺寸精确控制等丰富功能，并内置设计时扩展属性支持，可在属性窗口直接配置子控件的位置和布局行为。

主要特性

行列控制：支持任意行列数配置，可精确设置每行高度和每列宽度
表头支持：支持标题行（HeaderRow）和标题列（HeaderColumn），标题行可自动合并为一整行并显示标题文本
单元格合并：支持 RowSpan（行合并）和 ColumnSpan（列合并），合并后的内部网格线自动隐藏
控件对齐：支持 9 种对齐方式（Stretch=false 时生效），包括左上、居中、右下等
拉伸控制：每个子控件可独立设置是否拉伸填满单元格，不拉伸时保持原始尺寸
表格对齐：当表格尺寸小于控件尺寸时，支持 9 种表格在控件内的对齐方式
网格线显示：支持显示/隐藏网格线，可自定义网格线颜色和宽度
独立边框：控件外边框与表格网格线颜色独立设置，边框默认宽度为 0（无边框）
设计时支持：通过 IExtenderProvider 为子控件提供扩展属性，在属性窗口直接设置行号、列号、合并、拉伸、对齐

属性说明

布局属性

属性名	类型	默认值	说明
`ColumnCount`	int	2	列数
`RowCount`	int	4	行数
`ColumnWidths`	int[]	null	列宽度数组（像素），为空时自动均分。0 表示自动分配剩余宽度示例：`new int[]{90,0,90,0}` 表示第1、3列固定90像素，第2、4列自动平分剩余宽度
`RowHeights`	int[]	null	行高度数组（像素），为空时自动均分。数组中的 0 会被替换为 35示例：`new int[]{35,35,35,60}`
`CellPadding`	Padding	4,4,4,4	单元格内边距，控件与单元格边框之间的间隙
`Padding`	Padding	4,4,4,4	控件内边距，表格与控件边界之间的间隙。设置后表格四周会留出空白区域，避免边框贴边
`TableAlignment`	ContentAlignment	TopLeft	表格在控件内的对齐方式。当表格总尺寸小于控件尺寸时生效

外观属性

属性名	类型	默认值	说明
`ShowGridLines`	bool	true	是否显示网格线
`GridLineColor`	Color	#D9D9D9	表格内部网格线颜色
`GridLineWidth`	int	1	表格内部网格线宽度（像素）
`BorderColor`	Color	Empty	控件外边框颜色。Color.Empty 表示无边框
`BorderWidth`	int	0	控件外边框宽度（像素）。默认 0 表示无边框
`BorderRadius`	int	8	控件外边框圆角半径
`TableCornerRadius`	int	0	表格圆角半径。大于0时表格四个角显示为圆角，与控件外边框独立

表头属性

属性名	类型	默认值	说明
`HeaderRow`	bool	true	是否显示表头行。设为 true 时标题行自动合并为一整行
`HeaderColumn`	bool	false	是否显示表头列
`HeaderBackColor`	Color	#F5F5F5	表头背景色
`HeaderForeColor`	Color	#333333	表头前景色（文字颜色）
`TitleText`	string	""	标题行文本。仅在 HeaderRow=true 时显示

子控件扩展属性（单元格布局）

选中 TableLayoutPanelEx 内的子控件后，属性窗口会显示 "单元格布局" 分类，包含以下扩展属性：

属性名	类型	默认值	说明
`Row`	int	0	行索引（从 0 开始），0 表示第 1 行
`Column`	int	0	列索引（从 0 开始），0 表示第 1 列
`RowSpan`	int	1	行合并范围。设为 2 表示占据当前行和下一行
`ColumnSpan`	int	1	列合并范围。设为 2 表示占据当前列和下一列；设为 4 可跨整行
`Stretch`	bool	true	是否拉伸填满单元格。设为 false 时控件保持原始尺寸
`Alignment`	ContentAlignment	MiddleLeft	控件在单元格中的对齐方式。仅在 Stretch=false 时生效

公共方法

方法名	说明	示例
`SetRowHeight(int rowIndex, int height)`	设置指定行高度。rowIndex 从 0 开始，height <= 0 时自动设为 35	`SetRowHeight(0, 50)` 设置第 1 行高 50 像素
`SetColumnWidth(int columnIndex, int width)`	设置指定列宽度。columnIndex 从 0 开始，width = 0 时自动分配剩余宽度	`SetColumnWidth(2, 0)` 设置第 3 列为自适应宽度
`GetRowHeight(int rowIndex)`	获取指定行高度	`GetRowHeight(0)` 返回第 1 行高度
`GetColumnWidth(int columnIndex)`	获取指定列宽度	`GetColumnWidth(0)` 返回第 1 列宽度
`GetCellBounds(int row, int column)`	获取指定单元格的矩形区域	`GetCellBounds(0, 0)` 返回第 1 行第 1 列的矩形
`SetRow(Control, int)`	设置子控件所在行	`SetRow(button1, 2)`
`SetColumn(Control, int)`	设置子控件所在列	`SetColumn(button1, 1)`
`SetRowSpan(Control, int)`	设置子控件行合并范围	`SetRowSpan(button1, 2)`
`SetColumnSpan(Control, int)`	设置子控件列合并范围	`SetColumnSpan(button1, 2)` 跨 2 列
`SetStretch(Control, bool)`	设置子控件是否拉伸	`SetStretch(button1, false)`
`SetAlignment(Control, ContentAlignment)`	设置子控件对齐方式	`SetAlignment(button1, ContentAlignment.MiddleCenter)`

事件

事件名	参数	说明
`CellClick`	`CellClickEventArgs`	单击单元格时触发。参数包含 Row（行索引）和 Column（列索引）
`PropertyChanged`	`PropertyChangedEventArgs`	属性值变更时触发（INotifyPropertyChanged 接口）

代码示例

基础用法

// 设置行列数
tableLayoutPanelEx1.RowCount = 5;
tableLayoutPanelEx1.ColumnCount = 4;

// 设置标题
tableLayoutPanelEx1.TitleText = "用户表";
tableLayoutPanelEx1.HeaderRow = true;

// 设置列宽
tableLayoutPanelEx1.SetColumnWidth(0, 80);   // 第1列 80像素
tableLayoutPanelEx1.SetColumnWidth(1, 200);  // 第2列 200像素
tableLayoutPanelEx1.SetColumnWidth(2, 80);   // 第3列 80像素
tableLayoutPanelEx1.SetColumnWidth(3, 200);  // 第4列 200像素

// 设置行高
tableLayoutPanelEx1.SetRowHeight(0, 40);  // 标题行
tableLayoutPanelEx1.SetRowHeight(1, 35);
tableLayoutPanelEx1.SetRowHeight(2, 35);
tableLayoutPanelEx1.SetRowHeight(3, 35);
tableLayoutPanelEx1.SetRowHeight(4, 50);  // 按钮行

单元格合并示例

// 将 buttonEx1 放在第5行第1列，并跨2列
tableLayoutPanelEx1.SetRow(buttonEx1, 4);
tableLayoutPanelEx1.SetColumn(buttonEx1, 0);
tableLayoutPanelEx1.SetColumnSpan(buttonEx1, 2);
tableLayoutPanelEx1.SetStretch(buttonEx1, false);
tableLayoutPanelEx1.SetAlignment(buttonEx1, ContentAlignment.MiddleCenter);

// 将 buttonEx2 放在第5行第3列，并跨2列
tableLayoutPanelEx1.SetRow(buttonEx2, 4);
tableLayoutPanelEx1.SetColumn(buttonEx2, 2);
tableLayoutPanelEx1.SetColumnSpan(buttonEx2, 2);
tableLayoutPanelEx1.SetStretch(buttonEx2, false);
tableLayoutPanelEx1.SetAlignment(buttonEx2, ContentAlignment.MiddleCenter);

自适应列宽（固定+自动分配）

// 4列表格，第1列和第3列固定90像素，第2列和第4列自动平分剩余宽度
tableLayoutPanelEx1.ColumnCount = 4;
tableLayoutPanelEx1.ColumnWidths = new int[] { 90, 0, 90, 0 };

// 若控件总宽度为800，Padding为4（左右各4像素）
// 有效宽度 = 800 - 4 - 4 = 792
// 剩余宽度 = 792 - 90*2 = 612
// 第2列和第4列宽度 = 612 / 2 = 306
// 最终列宽：90, 306, 90, 306

使用 Padding 避免表格边框贴边

// 设置控件内边距，让表格四周留出空白区域
tableLayoutPanelEx1.Padding = new Padding(8);

// 此时表格的左边距为8像素，右边距也为8像素
// 表格有效总宽度 = 控件宽度 - Padding.Left - Padding.Right
// 即使表格网格线延伸到边界，也不会与控件外边框重合

表格圆角

// 设置表格四个角为圆角，与控件外边框独立
tableLayoutPanelEx1.TableCornerRadius = 6;

// 配合 Padding 使用，圆角效果更佳
tableLayoutPanelEx1.Padding = new Padding(8);

表格在控件内居中

// 当表格总尺寸小于控件尺寸时，表格居中显示
tableLayoutPanelEx1.TableAlignment = ContentAlignment.MiddleCenter;

单元格点击事件

private void tableLayoutPanelEx1_CellClick(object sender, CellClickEventArgs e)
{
    MessageBox.Show($"点击了第 {e.Row + 1} 行，第 {e.Column + 1} 列");
}

注意事项

行号列号从 0 开始：所有行索引和列索引均从 0 开始，0 表示第 1 行/列
HeaderRow 自动合并：当 HeaderRow=true 时，标题行自动合并为一整行，不显示内部竖线
Stretch=false 保持原始尺寸：设置 Stretch=false 后，控件会保持原始尺寸（设计时的大小），按 Alignment 属性在单元格内对齐
单元格合并内部格线自动隐藏：设置 RowSpan>1 或 ColumnSpan>1 后，合并范围内的内部网格线会自动隐藏
ColumnWidths 自适应列宽：数组中的 0 表示自动分配剩余宽度。可通过属性窗口直接编辑数组，未设置的列/行会自动均分剩余空间。例如 new int[]{90,0,90,0} 表示第1、3列固定90像素，第2、4列自动平分剩余宽度
Padding 控件内边距：默认值为 4 像素，控制表格与控件边界之间的间隙。修改 Padding 后会自动重新布局，确保表格四周留出空白区域，避免边框贴边或被截断
控件外边框与网格线分离：BorderColor/BorderWidth 控制控件外边框，GridLineColor/GridLineWidth 控制表格内部网格线，两者互不影响
有效总宽度计算：表格的实际可用宽度 = 控件宽度 - Padding.Left - Padding.Right。设置 ColumnWidths 时，系统会自动基于此有效宽度计算自适应列的宽度