【WinForm UI控件系列】表格table控件（支持多种数据类型显示）

Table 是一个功能丰富的现代化表格控件.

丰富的单元格类型：支持文本、数字、布尔值（开关）、图片、标签、进度条、链接、图标等多种类型
表头功能：支持显示/隐藏表头、固定表头、表头分割线
选择功能：支持复选框选择、全选/反选
行号显示：自动显示行号，支持自定义宽度
排序功能：支持点击表头排序
列宽调整：支持拖动调整列宽
斑马纹：支持奇偶行不同背景色
悬停高亮：鼠标悬停时行高亮
主题支持：实现 IThemeable 接口，支持亮暗主题切换
滚动支持：支持水平和垂直滚动，滚动条仅在悬停时显示
属性变更通知：实现 INotifyPropertyChanged 接口，属性修改即时生效

一、效果

二、使用文档

Table

中文名称

表格控件

控件优点

Table 是一个功能丰富的现代化表格控件，参考 Ant Design Table 组件设计，具有以下优点：

丰富的单元格类型：支持文本、数字、布尔值（开关）、图片、标签、进度条、链接、图标等多种类型
表头功能：支持显示/隐藏表头、固定表头、表头分割线
选择功能：支持复选框选择、全选/反选
行号显示：自动显示行号，支持自定义宽度
排序功能：支持点击表头排序
列宽调整：支持拖动调整列宽
斑马纹：支持奇偶行不同背景色
悬停高亮：鼠标悬停时行高亮
主题支持：实现 IThemeable 接口，支持亮暗主题切换
滚动支持：支持水平和垂直滚动，滚动条仅在悬停时显示
属性变更通知：实现 INotifyPropertyChanged 接口，属性修改即时生效

重要参数说明

Table 控件属性

属性	类型	默认值	说明
`Columns`	List<TableColumn>	空列表	列定义集合
`Rows`	List<TableRow>	空列表	行数据集合
`Bordered`	bool	true	是否显示边框
`ShowHeader`	bool	true	是否显示表头
`FixedHeader`	bool	false	是否固定表头
`ShowRowNumber`	bool	false	是否显示行号列
`ShowCheckbox`	bool	false	是否显示复选框列
`Striped`	bool	false	是否显示斑马纹
`Hoverable`	bool	true	是否启用悬停高亮
`Loading`	bool	false	是否显示加载状态
`BorderRadius`	int	6	圆角大小
`CellPadding`	int	8	单元格内边距
`HeaderHeight`	int	40	表头高度
`RowHeight`	int	40	行高度
`BorderColor`	Color	#C8C8C8	边框颜色
`ScrollBarColor`	Color	#E0E0E0	滚动条颜色
`HeaderBackColor`	Color	#F5F5F5	表头背景色
`HeaderForeColor`	Color	#404040	表头文字颜色
`RowBackColor`	Color	White	行背景色
`RowForeColor`	Color	Black	行文字颜色
`HoverBackColor`	Color	#E6F7FF	悬停背景色
`SelectedBackColor`	Color	#BAE7FF	选中背景色
`SelectedForeColor`	Color	#1890FF	选中文字颜色
`FollowGlobalTheme`	bool	true	是否跟随全局主题

TableColumn 列属性

属性	类型	默认值	说明
`Key`	string	自动生成	列唯一标识
`Title`	string	-	列标题
`DataIndex`	string	-	数据字段名
`Width`	int	100	列宽度
`MinWidth`	int	50	最小宽度
`MaxWidth`	int	500	最大宽度
`Fixed`	bool	false	是否固定列
`Visible`	bool	true	是否可见
`Align`	ColumnAlign	Left	对齐方式（Left/Center/Right）
`DataType`	ColumnDataType	Text	数据类型
`Sortable`	bool	false	是否可排序
`SortDirection`	SortDirection	None	当前排序方向
`Resizable`	bool	true	是否可调整宽度
`TagColor`	Color	LightBlue	标签颜色
`ForeColor`	Color	Empty	文字颜色

TableCell 单元格属性

属性	类型	默认值	说明
`Value`	object	null	原始值
`Text`	string	""	显示文本
`Checked`	bool	false	是否选中（复选框）
`Checkable`	bool	false	是否显示复选框
`ForeColor`	Color	Empty	前景色
`BackColor`	Color	Empty	背景色
`TagColor`	Color	LightBlue	标签颜色
`Tags`	List<string>	空列表	标签列表
`Image`	Image	null	图片
`IconSvg`	string	""	SVG图标名称
`Progress`	float	0	进度值（0-1）
`ProgressColor`	Color	#1890FF	进度条颜色
`LinkText`	string	""	链接文本
`LinkUrl`	string	""	链接URL

数据类型说明

类型	说明	显示方式
`Text`	文本	普通文字
`Number`	数字	右对齐文字
`Boolean`	布尔值	开关控件
`Image`	图片	居中显示图片
`Tag`	标签	带颜色背景的标签
`Progress`	进度条	进度条 + 百分比
`Link`	链接	带下划线的可点击文字
`Icon`	图标	SVG图标
`IconText`	图标+文本	图标和文本组合显示

枚举类型

ColumnAlign（对齐方式）

值	说明
`Left`	左对齐
`Center`	居中对齐
`Right`	右对齐

ColumnDataType（数据类型）

值	说明
`Text`	文本类型
`Number`	数字类型
`Boolean`	布尔类型
`Image`	图片类型
`Tag`	标签类型
`Progress`	进度条类型
`Link`	链接类型
`Icon`	图标类型
`IconText`	图标+文本类型

SortDirection（排序方向）

值	说明
`None`	无排序
`Ascending`	升序
`Descending`	降序

重要事件

事件	说明	参数
`CellClick`	单元格点击时触发	`TableCellEventArgs`
`RowClick`	行点击时触发	`TableRowEventArgs`
`RowDoubleClick`	行双击时触发	`TableRowEventArgs`
`ColumnSort`	列排序时触发	`ColumnSortEventArgs`
`RowChecked`	行复选框状态改变时触发	`RowCheckedEventArgs`
`PropertyChanged`	属性变更时触发（INotifyPropertyChanged）	`PropertyChangedEventArgs`

事件参数说明

TableCellEventArgs

属性	类型	说明
`Row`	TableRow	所在行
`Column`	TableColumn	所在列
`Cell`	TableCell	单元格
`RowIndex`	int	行索引
`ColumnIndex`	int	列索引

TableRowEventArgs

属性	类型	说明
`Row`	TableRow	行对象
`RowIndex`	int	行索引

ColumnSortEventArgs

属性	类型	说明
`Column`	TableColumn	排序列
`Direction`	SortDirection	排序方向

RowCheckedEventArgs

属性	类型	说明
`Row`	TableRow	行对象
`Checked`	bool	是否选中

公共方法

方法	说明	参数	返回值
`AddColumn(TableColumn)`	添加列	`column`: 列对象	void
`RemoveColumn(string key)`	移除指定列	`key`: 列Key	void
`AddRow(TableRow)`	添加行	`row`: 行对象	void
`RemoveRow(string key)`	移除指定行	`key`: 行Key	void
`ClearRows()`	清空所有行	-	void
`SelectRow(string key)`	选中指定行	`key`: 行Key	void
`CheckAll(bool check)`	全选/反选所有行	`check`: 是否选中	void
`GetCheckedRows()`	获取所有选中的行	-	List<TableRow>
`GetSelectedRows()`	获取当前选中的行	-	List<TableRow>
`SortByColumn(string key, SortDirection)`	按指定列排序	`key`: 列Key, `direction`: 排序方向	void
`ApplyTheme(ThemeMode)`	应用主题	`mode`: 主题模式	void

使用示例

基础使用

csharp 复制代码

// 创建表格控件
var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400),
    Bordered = true,
    ShowHeader = true,
    ShowRowNumber = true,
    Striped = true
};

// 添加列
table.Columns.Add(new TableColumn("name", "姓名"));
table.Columns.Add(new TableColumn("age", "年龄", ColumnAlign.Center));
table.Columns.Add(new TableColumn("address", "地址"));
table.Columns.Add(new TableColumn("enabled", "是否启用", ColumnAlign.Center)
{
    DataType = ColumnDataType.Boolean
});

// 添加数据行
var row1 = new TableRow("row1");
row1.SetCellText("name", "张三");
row1.SetCellValue("age", 30);
row1.SetCellText("address", "北京市朝阳区");
row1.SetCellValue("enabled", true);
table.Rows.Add(row1);

var row2 = new TableRow("row2");
row2.SetCellText("name", "李四");
row2.SetCellValue("age", 25);
row2.SetCellText("address", "上海市浦东新区");
row2.SetCellValue("enabled", false);
table.Rows.Add(row2);

this.Controls.Add(table);

带复选框和排序

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400),
    ShowCheckbox = true,
    Hoverable = true
};

// 添加可排序的列
var nameCol = new TableColumn("name", "姓名");
nameCol.Sortable = true;
table.Columns.Add(nameCol);

var priceCol = new TableColumn("price", "价格", ColumnAlign.Right);
priceCol.Sortable = true;
priceCol.DataType = ColumnDataType.Number;
table.Columns.Add(priceCol);

// 添加数据
for (int i = 1; i <= 10; i++)
{
    var row = new TableRow($"row{i}");
    row.Checkable = true;
    row.SetCellText("name", $"商品{i}");
    row.SetCellValue("price", 100 + i * 10);
    table.Rows.Add(row);
}

// 监听排序事件
table.ColumnSort += (sender, e) =>
{
    Console.WriteLine($"按 {e.Column.Title} {e.Direction} 排序");
    // 实现实际排序逻辑
    if (e.Direction == SortDirection.Ascending)
    {
        table.Rows = table.Rows.OrderBy(r => r.Cells["price"].Value).ToList();
    }
    else
    {
        table.Rows = table.Rows.OrderByDescending(r => r.Cells["price"].Value).ToList();
    }
};

this.Controls.Add(table);

进度条和标签列

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400)
};

table.Columns.Add(new TableColumn("task", "任务名称"));
table.Columns.Add(new TableColumn("progress", "进度", ColumnAlign.Center)
{
    DataType = ColumnDataType.Progress,
    Width = 150
});
table.Columns.Add(new TableColumn("status", "状态")
{
    DataType = ColumnDataType.Tag
});

// 添加数据
var row = new TableRow("row1");
row.SetCellText("task", "项目开发");

var progressCell = TableCell.ProgressCell(0.75f, Color.Green);
row.SetCell("progress", progressCell);

var tagCell = TableCell.TagCell(Color.Blue, "进行中", "重要");
row.SetCell("status", tagCell);

table.Rows.Add(row);

this.Controls.Add(table);

链接和图标列

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400)
};

table.Columns.Add(new TableColumn("name", "名称"));
table.Columns.Add(new TableColumn("icon", "图标", ColumnAlign.Center)
{
    DataType = ColumnDataType.Icon,
    Width = 60
});
table.Columns.Add(new TableColumn("action", "操作")
{
    DataType = ColumnDataType.Link
});

var row = new TableRow("row1");
row.SetCellText("name", "设置");
row.SetCell("icon", TableCell.IconCell("setting"));
row.SetCell("action", TableCell.LinkCell("点击查看", "#"));

table.Rows.Add(row);

this.Controls.Add(table);

图标+文本组合列

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400),
    ShowRowNumber = true
};

// 图标+文本列
table.Columns.Add(new TableColumn("name", "姓名")
{
    DataType = ColumnDataType.IconText,
    Width = 120
});
table.Columns.Add(new TableColumn("age", "年龄", ColumnAlign.Center));
table.Columns.Add(new TableColumn("status", "状态", ColumnAlign.Center)
{
    DataType = ColumnDataType.Tag
});

// 添加带图标的数据行
var icons = new[] { "user", "user", "user", "user", "user" };
var names = new[] { "张三", "李四", "王五", "赵六", "钱七" };

for (int i = 0; i < 5; i++)
{
    var row = new TableRow($"row{i + 1}");
    // 创建图标+文本单元格
    var iconCell = new TableCell
    {
        Text = names[i],
        IconSvg = icons[i],
        ForeColor = Color.Black
    };
    row.SetCell("name", iconCell);
    row.SetCellValue("age", 25 + i);
    row.SetCell("status", TableCell.TagCell(i % 2 == 0 ? Color.Green : Color.Blue, 
        i % 2 == 0 ? "在线" : "离线"));
    table.Rows.Add(row);
}

this.Controls.Add(table);

主题适配

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400),
    FollowGlobalTheme = true  // 跟随全局主题
};

// 手动设置主题
table.ApplyTheme(ThemeMode.Dark);

// 监听属性变更
table.PropertyChanged += (sender, e) =>
{
    Console.WriteLine($"属性 {e.PropertyName} 已变更");
};

自定义滚动条颜色

csharp 复制代码

var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(600, 400),
    ScrollBarColor = Color.FromArgb(180, 180, 180),  // 自定义滚动条颜色
    ShowRowNumber = true
};

完整示例：综合使用

csharp 复制代码

// 创建表格
var table = new Table
{
    Location = new Point(20, 20),
    Size = new Size(800, 500),
    Bordered = true,
    ShowHeader = true,
    ShowRowNumber = true,
    ShowCheckbox = true,
    Striped = true,
    Hoverable = true,
    BorderRadius = 8,
    CellPadding = 10
};

// 添加列定义
table.Columns.Add(new TableColumn("name", "姓名") { Width = 120 });
table.Columns.Add(new TableColumn("age", "年龄", ColumnAlign.Center) { Width = 80 });
table.Columns.Add(new TableColumn("registerDate", "注册日期") { Width = 150 });
table.Columns.Add(new TableColumn("status", "状态", ColumnAlign.Center) 
    { DataType = ColumnDataType.Tag, Width = 100 });
table.Columns.Add(new TableColumn("progress", "进度", ColumnAlign.Center) 
    { DataType = ColumnDataType.Progress, Width = 120 });
table.Columns.Add(new TableColumn("score", "评分", ColumnAlign.Center) 
    { DataType = ColumnDataType.Number, Width = 80 });
table.Columns.Add(new TableColumn("active", "活跃", ColumnAlign.Center) 
    { DataType = ColumnDataType.Boolean, Width = 80 });
table.Columns.Add(new TableColumn("link", "链接") { DataType = ColumnDataType.Link });
table.Columns.Add(new TableColumn("action", "操作"));

// 添加数据
var statusColors = new[] { Color.Green, Color.Blue, Color.Orange, Color.Red };
var statusTexts = new[] { "正常", "异常", "处理中", "已完成" };

for (int i = 1; i <= 20; i++)
{
    var row = new TableRow($"row{i}");
    row.Checkable = true;
    
    // 姓名列（带图标）
    var nameCell = new TableCell
    {
        Text = $"用户{i}",
        IconSvg = "user",
        ForeColor = Color.Black
    };
    row.SetCell("name", nameCell);
    
    row.SetCellValue("age", 20 + i % 15);
    row.SetCellText("registerDate", $"2024-0{i % 12 + 1}-{i % 28 + 1:00} 08:59:33");
    row.SetCell("status", TableCell.TagCell(statusColors[i % 4], statusTexts[i % 4]));
    row.SetCell("progress", TableCell.ProgressCell(i * 0.05f, Color.FromArgb(24, 144, 255)));
    row.SetCellValue("score", 80 + i % 20);
    row.SetCellValue("active", i % 3 != 0);
    row.SetCell("link", TableCell.LinkCell($"链接{i}", "#"));
    
    // 操作列（按钮组）
    var buttons = new List<TableCellButton>
    {
        new TableCellButton("新增", Color.Green),
        new TableCellButton("删除", Color.Red),
        new TableCellButton("详情", Color.Blue)
    };
    row.SetCell("action", TableCell.ButtonCell(buttons));
    
    table.Rows.Add(row);
}

// 事件处理
table.RowClick += (sender, e) =>
{
    MessageBox.Show($"点击了第 {e.RowIndex + 1} 行");
};

table.RowChecked += (sender, e) =>
{
    var checkedRows = table.GetCheckedRows();
    Console.WriteLine($"当前选中 {checkedRows.Count} 行");
};

this.Controls.Add(table);

界面布局说明

表格整体布局如下：

复制代码

┌─────────────────────────────────────────────────────────────────┐
│ [行号] [复选框] 列1标题        列2标题        列3标题         │ ← 表头（可固定）
├─────────────────────────────────────────────────────────────────┤
│ [  1 ] [☑]     单元格内容     单元格内容     单元格内容       │
│ [  2 ] [☐]     单元格内容     单元格内容     单元格内容       │ ← 斑马纹效果
│ [  3 ] [☑]     单元格内容     单元格内容     单元格内容       │
│ ...                                                           │
└─────────────────────────────────────────────────────────────────┘
         ↓ 垂直滚动条（悬停时显示）        ↓ 水平滚动条（悬停时显示）

主题颜色映射

控件元素	亮色模式	暗色模式
背景色	White	#1E1E1E
表头背景	#F5F5F5	#2D2D2D
表头文字	#404040	#E0E0E0
行背景	White	#1E1E1E
行文字	Black	#E0E0E0
悬停背景	#E6F7FF	#2D2D2D
选中背景	#BAE7FF	#1890FF
边框颜色	#C8C8C8	#3D3D3D
滚动条颜色	#E0E0E0	#404040

注意事项

列宽调整：拖动列边界可调整列宽，最小宽度为50像素，最大宽度为500像素
排序功能：点击可排序列的表头会触发排序事件，需要在事件处理中实现实际的排序逻辑
复选框选择 ：只有设置了 Checkable = true 的行才能被勾选
图片单元格：建议使用较小的图片尺寸，避免影响性能
主题切换 ：设置 FollowGlobalTheme = true 后，控件会自动跟随全局主题变化
滚动性能：大量数据时建议启用虚拟滚动优化（后续版本支持）
滚动条显示：滚动条仅在鼠标悬停在表格上时显示，移开后自动隐藏
属性变更通知：所有属性都实现了 INotifyPropertyChanged 接口，修改属性后会立即触发 PropertyChanged 事件
行号宽度：行号列宽度固定为60像素，以确保两位数序号能完整显示

更新日志

v1.3.0

实现 INotifyPropertyChanged 接口，所有属性修改即时生效
添加 ScrollBarColor 属性，支持自定义滚动条颜色
滚动条仅在鼠标悬停时显示
优化行号列宽度为60像素，确保两位数序号完整显示
修复图标+文本单元格显示重叠问题
优化表格边框线宽度为0.5像素，更细更美观

三、后记

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