syncfusion-winforms-grid-control

实现 GridControl

完整指南：如何实现 Syncfusion® Windows Forms GridControl——这是一种功能强大的面向单元格的网格，可为 .NET 桌面应用程序提供类似 Excel 的功能、虚拟数据加载和丰富的单元格级自定义能力。

何时使用此技能

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

• 实现面向单元格的网格，由网格自身保存数据
• 创建虚拟网格，按需加载大型数据集
• 使用 GridStyleInfo 和样式架构单独自定义单元格
• 添加类似 Excel 的功能（选择框、公式、复制/粘贴）
• 使用循环、PopulateValues 或 QueryCellInfo 填充网格数据
• 实现单元格类型（TextBox、ComboBox、CheckBox、Button 等）
• 通过验证和自定义处理程序启用单元格编辑
• 通过单元格引用和内置函数支持公式
• 创建覆盖单元格或合并单元格
• 实现列和行的拖放
• 处理选择（基于范围或基于行）
• 将网格数据导出为 Excel、PDF、Word、CSV 或 HTML
• 冻结行/列以便更轻松地浏览
• 在 Windows Forms 中构建类似电子表格的界面

GridControl 概述

GridControl 是一种面向单元格的网格，可自行维护数据，无需绑定到外部数据源。它旨在实现最大的灵活性和性能，支持几乎无限的行和列。

主要功能：

• 可细致自定义单元格，精确到单个单元格
• 虚拟模式，高效处理数百万行
• 15 种以上内置单元格类型，并支持扩展
• 支持单元格引用的类似 Excel 的公式
• 支持覆盖单元格和合并单元格功能
• 多种选择模式（基于范围和基于行）
• 支持验证的丰富编辑功能
• 支持拖放
• 支持导出为多种格式
• 冻结行和列
• 剪贴板操作（复制/粘贴）
• 支持触控

最佳使用场景：

• 不适合表格结构的自定义数据布局
• 类似电子表格的应用程序
• 按需加载数据的虚拟网格
• 需要控制单元格级别的应用程序
• 需要支持公式的网格
• 复杂单元格类型和自定义呈现器

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集部署
• 通过设计器添加 GridControl
• 通过代码添加 GridControl
• 初始配置和设置
• 所需程序集和命名空间
• 基本网格创建

数据填充

📄 阅读： references/data-population.md

• 设置 RowCount 和 ColCount
• 循环填充单元格
• 使用 PopulateValues 方法
• 通过 QueryCellInfo 事件创建虚拟网格
• 数据绑定模式
• 性能注意事项

单元格样式架构

📄 阅读： references/cell-style-architecture.md

• GridStyleInfo 对象模型
• 通过设计器修改样式
• 通过代码修改样式
• 使用 ChangeCells 方法
• 用于范围操作的 GridRangeInfo
• 外观自定义
• 样式继承和基样式

单元格类型

📄 阅读： references/cell-types.md

• 15 种以上单元格类型概述
• TextBox 和静态文本
• ComboBox 和下拉列表
• CheckBox 和单选按钮
• DateTimePicker 和日历
• NumericUpDown 和货币
• Button 和链接单元格
• 图像单元格
• 进度条单元格
• 自定义单元格类型
• 单元格类型配置

编辑与验证

📄 阅读： references/editing-validation.md

• ReadOnly 属性（网格级和单元格级）
• CurrentCellStartEditing 事件
• CurrentCellEditingComplete 事件
• 验证规则和处理程序
• 自定义编辑行为
• 按条件阻止编辑
• 编辑模式配置

选择

📄 阅读： references/selection.md

• 使用 AllowSelection 进行范围选择
• 使用 ListBoxSelectionMode 进行行选择
• GridSelectionFlags 枚举
• 单选与多选
• SelectionChanging 事件
• SelectionChanged 事件
• 编程方式进行选择
• 获取选定范围

类 Excel 功能

📄 阅读： references/excel-like-features.md

• 类 Excel 选择框
• 2016 与 2003 选择样式
• 类 Excel 当前单元格高亮
• 键盘导航（方向键、Tab、Enter）
• 复制和粘贴支持
• 剪贴板操作
• 类 Excel 行为
• 自定义选择框

公式支持

📄 阅读： references/formula-support.md

• 启用公式引擎
• 公式语法和单元格引用
• 内置函数（SUM、AVERAGE、IF 等）
• 在单元格中创建公式
• 公式计算和依赖关系
• 错误处理
• 自定义函数
• 公式事件

覆盖范围

📄 阅读： references/covered-ranges.md

• 覆盖多个单元格
• CoveredRanges 集合
• 添加和移除覆盖范围
• 被覆盖单元格与合并单元格
• 被覆盖单元格的外观
• 覆盖范围中的单元格值
• 设置被覆盖单元格的样式

拖放

📄 阅读： references/drag-and-drop.md

• 启用列拖放
• 支持行拖放
• 支持触控拖动操作
• 拖动事件和自定义
• 限制拖动操作
• 拖动期间的视觉反馈

滚动和缩放

📄 阅读： references/scrolling-zooming.md

• 滚动条配置
• 冻结行和列
• 缩放功能
• 滚动事件
• 平滑滚动
• 滚动性能优化
• 虚拟滚动

导出

📄 阅读： references/exporting.md

• 导出为 Excel（XLS、XLSX）
• 导出为 PDF
• 导出为 Word 文档
• 导出为 CSV 格式
• 导出为 HTML
• 导出选项和自定义
• 设置导出内容的样式
• 基于范围导出

快速入门示例

GridControl 基本设置

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

public partial class Form1 : Form
{
    private GridControl gridControl1;
    
    public Form1()
    {
        InitializeComponent();
        InitializeGrid();
    }
    
    private void InitializeGrid()
    {
        // Create and configure GridControl
        gridControl1 = new GridControl();
        gridControl1.Size = new Size(800, 600);
        gridControl1.Dock = DockStyle.Fill;
        
        // Set dimensions
        gridControl1.RowCount = 50;
        gridControl1.ColCount = 10;
        
        // Populate with data
        for (int row = 1; row <= gridControl1.RowCount; row++)
        {
            for (int col = 1; col <= gridControl1.ColCount; col++)
            {
                gridControl1[row, col].CellValue = $"R{row}C{col}";
            }
        }
        
        // Style header row
        GridStyleInfo headerStyle = new GridStyleInfo();
        headerStyle.BackColor = Color.DarkBlue;
        headerStyle.TextColor = Color.White;
        headerStyle.Font.Bold = true;
        gridControl1.ChangeCells(GridRangeInfo.Row(1), headerStyle);
        
        // Enable Excel-like features
        gridControl1.ExcelLikeSelectionFrame = true;
        gridControl1.ExcelLikeCurrentCell = true;
        gridControl1.AllowSelection = GridSelectionFlags.Any;
        
        // Add to form
        this.Controls.Add(gridControl1);
    }
}

常见模式

模式 1：虚拟网格

gridControl1.Model.RowCount = 1000000;
gridControl1.QueryCellInfo += (sender, e) =>
{
    e.Style.CellValue = GetData(e.RowIndex, e.ColIndex);
};

📄 详情： references/data-population.md

模式 2：单元格样式

GridStyleInfo style = new GridStyleInfo { BackColor = Color.LightGreen };
gridControl1.ChangeCells(GridRangeInfo.Cells(5, 2, 8, 5), style);

📄 详情： references/cell-style-architecture.md

模式 3：公式

gridControl1.Model.EnableFormulas = true;
gridControl1[5, 1].CellValue = "=SUM(A1:A4)";

📄 详情： references/formula-support.md

模式 4：单元格类型

gridControl1[3, 2].CellType = GridCellTypeName.ComboBox;
gridControl1[3, 2].ChoiceList = new string[] { "Option 1", "Option 2" };

📄 详情： references/cell-types.md

模式 5：选择

gridControl1.AllowSelection = GridSelectionFlags.Any;
gridControl1.SelectionChanged += (s, e) => { /* Handle selection */ };

📄 详情： references/selection.md

关键属性

基本属性

Property	Type	Description
RowCount	int	网格中的行数
ColCount	int	网格中的列数
Model[row, col]	GridStyleInfo	访问单元格样式和属性
AllowSelection	GridSelectionFlags	启用/配置范围选择
ListBoxSelectionMode	SelectionMode	启用/配置行选择
ReadOnly	bool	启用/禁用整个网格的编辑
ExcelLikeSelectionFrame	bool	显示类 Excel 选择框
ExcelLikeCurrentCell	bool	像 Excel 一样高亮当前单元格
CoveredRanges	GridRangeInfoList	被覆盖单元格范围的集合

GridStyleInfo 属性

属性	类型	描述
CellValue	object	单元格中显示的值
CellType	string	单元格类型（TextBox、ComboBox 等）
BackColor	Color	背景色
TextColor	Color	文本颜色
Font	GridFontInfo	字体设置
ReadOnly	bool	启用/禁用单元格编辑
Format	string	显示格式字符串
HorizontalAlignment	GridHorizontalAlignment	文本水平对齐方式
VerticalAlignment	GridVerticalAlignment	文本垂直对齐方式

常见用例

• 电子表格应用 - 提供类似 Excel 的界面，支持公式和格式设置
• 数据录入表单 - 包含各种单元格类型的自定义表单
• 报表查看器 - 支持合并单元格和导出的格式化报表
• 虚拟数据网格 - 按需加载数百万行数据
• 仪表板网格 - 带可视化指示器的自定义布局
• 配置编辑器 - 使用专用单元格类型的属性网格

故障排除

性能问题： 使用虚拟模式（QueryCellInfo），批量操作使用 BeginUpdate/EndUpdate
无法进行选择： 检查 AllowSelection 属性，并确认网格已获得焦点
公式未计算： 确保 Model.EnableFormulas = true，并验证语法
未显示单元格值： 确认已设置 CellValue，检查是否存在被覆盖的单元格，并验证行/列索引（从 1 开始）

如需详细的故障排除信息，请参阅导航指南中的相关参考文件。