syncfusion-winforms-multicolumn-listbox

实现 GridList 控件

何时使用此技能

在用户需要以下功能时使用此技能：

• 以多列格式显示带表头的项目列表
• 在 Windows Forms 应用程序中创建数据绑定列表控件
• 在列表视图中实现单选或多选
• 使用 ComboBoxBase 构建多列下拉控件
• 自定义列表外观（颜色、网格线、表头、背景）
• 使用虚拟模式处理大型数据集
• 为列表控件添加工具提示、公式或触控支持
• 从标准 ListBox 迁移到高级多列列表视图

组件概述

GridListControl 是一个适用于 Windows Forms 的多列列表视图组件，提供了超越标准 ListBox 控件的丰富数据展示功能。它结合了类似网格的功能与列表行为，为桌面应用程序提供强大的特性。

主要功能：

• 多列显示，并可自定义表头
• 绑定到任意数据源（ArrayList、DataTable、自定义对象）
• 三种选择模式：单选、简单多选、扩展多选
• 丰富的样式设置（颜色、网格线、背景、图像）
• 集成 ComboBoxBase，适用于下拉场景
• 虚拟模式，适用于高性能大型数据集
• 支持公式计算值
• 支持触控和键盘导航
• 调整列宽和行高
• 单元格级工具提示

主要功能

• 数据填充 - 绑定到任意数据源，包括数据库、集合和自定义对象
• 样式设置 - 自定义单元格样式、颜色、字体、网格线和背景
• 选择 - 支持键盘操作的单行和多行选择
• 工具提示 - 在单元格上显示悬停文本
• 调整大小 - 根据内容自动调整列宽和行高
• 视觉样式 - 多种内置主题和自定义样式
• 虚拟模式 - 按需加载数据，以获得最佳性能
• 公式 - 支持代数和算术表达式
• 下拉列表 - 与 ComboBoxBase 组合，实现多列下拉列表
• 触控支持 - 在触控设备上进行选择和滑动

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和依赖项
• 通过设计器添加 GridListControl（拖放、SqlDataAdapter 向导）
• 通过代码添加 GridListControl（以编程方式设置）
• 基本配置属性（DataSource、MultiColumn、ShowColumnHeader）
• 初始数据绑定示例
• 设计器与代码方式的对比

数据绑定与选择模式

📄 阅读： references/data-binding-selection.md

• 数据绑定概述和 DataSource 属性
• 绑定到 ArrayList 和自定义对象
• 使用 DataTable/DataSet 绑定数据库
• 选择模式类型（One、MultiSimple、MultiExtended）
• SelectionMode 属性配置
• 扩展多选模式下的键盘导航
• 获取所选项目（SelectedIndex、SelectedItem）

自定义与样式设置

📄 阅读： references/customization.md

• TransparentBackground 属性
• 网格线显示（DisplayVertLines、DisplayHorzLines）
• GridLineColor 自定义
• 表头外观（Buttons3D、HeaderBackColor、HeaderTextColor）
• 控件 BackColor 和 BackgroundImage
• 视觉样式和主题
• 触控支持配置
• 调整列宽和行高
• 工具提示配置

ComboBoxBase 集成

📄 阅读： references/combobox-integration.md

• 将 GridListControl 与 ComboBoxBase 组合使用
• ListControl 属性设置
• 创建多列下拉效果
• DropDownWidth 配置
• 下拉列表的使用场景
• 集成代码示例

快速入门示例

带数据绑定的基本多列列表

using Syncfusion.Windows.Forms.Grid;
using System.Collections;

// Create data source
ArrayList states = new ArrayList();
states.Add(new StateInfo { LongName = "California", ShortName = "CA" });
states.Add(new StateInfo { LongName = "Texas", ShortName = "TX" });
states.Add(new StateInfo { LongName = "New York", ShortName = "NY" });

// Configure GridListControl
gridListControl1.DataSource = states;
gridListControl1.MultiColumn = true;
gridListControl1.ShowColumnHeader = true;
gridListControl1.SelectionMode = SelectionMode.One;
gridListControl1.FillLastColumn = true;

// Custom class for data
public class StateInfo
{
    public string LongName { get; set; }
    public string ShortName { get; set; }
}

使用 ComboBoxBase 的多列下拉列表

// Setup GridListControl
gridListControl1.DataSource = dataSource;
gridListControl1.MultiColumn = true;

// Attach to ComboBoxBase for dropdown
comboBoxBase1.ListControl = gridListControl1;

常见模式

设计器设置

1. 将 SqlDataAdapter 从工具箱拖入窗体 → 配置数据库连接
2. 根据适配器生成 DataSet
3. 将 GridListControl 拖入窗体
4. 将 DataSource 属性设置为 DataSet
5. 在“属性”窗口中配置显示属性

基于代码的设置

1. 创建数据源（ArrayList、List、DataTable）
2. 初始化 GridListControl
3. 设置 DataSource 属性
4. 配置 MultiColumn、ShowColumnHeader
5. 设置 SelectionMode
6. 可选择自定义外观

大型数据集的虚拟模式

// Enable virtual mode for performance
gridListControl1.VirtualMode = true;

// Implement on-demand data loading
// (Refer to customization.md for details)

主要属性

数据和显示

• DataSource - 设置列表的数据源（ArrayList、DataTable、IList）
• MultiColumn - 启用多列显示（默认值：false）
• ShowColumnHeader - 显示/隐藏列标题（默认值：false）
• FillLastColumn - 使最后一列填满剩余空间（默认值：false）

选择

• SelectionMode - 控制选择行为：
  • SelectionMode.One - 仅允许选择单行
  • SelectionMode.MultiSimple - 可选择多行，单击即可切换
  • SelectionMode.MultiExtended - 可使用 SHIFT/CTRL/箭头键选择多行

外观

• BackColor - 控件的背景色
• TransparentBackground - 使背景透明（默认值：false）
• HeaderBackColor - 列标题的背景色
• HeaderTextColor - 列标题的文本颜色
• BackgroundImage - 控件的背景图像

网格线

• Properties.DisplayHorzLines - 显示水平网格线
• Properties.DisplayVertLines - 显示垂直网格线
• Grid.Properties.GridLineColor - 网格线的颜色
• Properties.Buttons3D - 将标题渲染为 3D 样式

高级

• VirtualMode - 启用按需加载数据，以提升性能
• ImageList - 将图像与列表项关联
• ToolTip - 配置单元格工具提示

常见用例

1. 数据库记录查看器

在带有标题的多列列表中显示数据库记录，方便用户浏览和选择记录。

适用场景： 浏览数据、选择记录、主从视图

2. 多列下拉选择器

与 ComboBoxBase 结合使用，创建显示多列的下拉列表（例如：客户名称 + ID + 城市）。

适用场景： 复杂选择场景、查找字段、数据丰富的选择器

3. 分类项目列表

以结构化列表形式显示具有多个属性的项目（名称、类别、价格、状态）。

适用场景： 产品目录、库存管理、订单列表

4. 选择界面

构建需要单选或多选项目并提供视觉反馈的界面。

适用场景： 批量操作、多选表单、清单界面

5. 支持触控的列表

为平板电脑或触摸屏应用创建便于触控的列表控件。

适用场景： 自助服务终端应用、平板应用、触控优化界面

6. 大型数据集浏览器

使用虚拟模式，高效显示和浏览包含数千个项目的数据集。

适用场景： 日志查看器、大型数据库表、高流量数据

选择指南

在以下需求下选择 GridListControl：

• ✅ 多列列表显示
• ✅ 列标题
• ✅ 绑定到对象/数据库的数据
• ✅ 高级选择模式
• ✅ 类似网格的样式
• ✅ 与 ComboBoxBase 下拉列表集成
• ✅ 用于提升性能的虚拟模式

在以下情况下使用标准 ListBox：

• ❌ 简单的单列列表即可满足需求
• ❌ 不需要标题
• ❌ 对样式要求极少
• ❌ 仅需简单显示数据

最佳实践

1. 性能

   • 对于包含 1000 项或更多项的数据集，使用虚拟模式
   • 如果不需要网格线，请将其禁用以加快渲染速度
   • 更改多个属性时使用 BeginUpdate/EndUpdate

2. 数据绑定

   • 绑定前验证数据源
   • 使用强类型集合（List）以确保类型安全
   • 适当处理数据更改（刷新、重新绑定）

3. 选择

   • 根据用户工作流选择合适的 SelectionMode
   • MultiExtended 灵活性最高，但需要对用户进行培训
   • 对于单选场景，One 是最简单的选择

4. 样式

   • 在整个应用程序中应用统一的视觉主题
   • 谨慎使用 TransparentBackground（会影响性能）
   • 测试自定义颜色，确保可读性

5. 集成

   • 与 ComboBoxBase 一起使用时，先配置 GridList
   • 绑定前确保数据源已就绪
   • 在父窗体中处理选择事件，而不是在 ComboBoxBase 中处理

故障排除

常见问题：

GridListControl 未显示数据

• 验证 DataSource 已设置且不为 null
• 检查多列显示时 MultiColumn 是否为 true
• 确保数据源中包含项目

标题不可见

• 设置 ShowColumnHeader = true
• 检查标题颜色是否与背景颜色一致

选择无效

• 验证 SelectionMode 不为 None
• 检查控件是否已启用
• 确保控件已获得焦点

性能问题

• 为大型数据集启用虚拟模式
• 禁用不必要的功能（网格线、工具提示）
• 批量更改时使用 BeginUpdate/EndUpdate

有关详细的故障排除和高级场景，请参阅参考文件。

后续步骤

从 入门 开始安装和配置 GridListControl，然后根据应用程序需求，通过上方的导航指南了解具体功能。