syncfusion-winforms-grid-control

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Grid Controls

Grid控件实现指南

Complete guide for implementing Syncfusion® Windows Forms GridControl - a powerful cell-oriented grid that provides Excel-like functionality, virtual data loading, and extensive cell-level customization for .NET desktop applications.
这是Syncfusion® Windows Forms GridControl的完整实现指南,它是一款功能强大的面向单元格的网格控件,可为.NET桌面应用提供类Excel功能、虚拟数据加载以及丰富的单元格级别自定义能力。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Implement cell-oriented grids that contain their own data
  • Create virtual grids with on-demand data loading for large datasets
  • Customize cells individually with GridStyleInfo and styling architecture
  • Add Excel-like features (selection frames, formulas, copy/paste)
  • Populate grid data using loops, PopulateValues, or QueryCellInfo
  • Implement cell types (TextBox, ComboBox, CheckBox, Button, etc.)
  • Enable cell editing with validation and custom handlers
  • Support formulas with cell references and built-in functions
  • Create covered cells or merge cells
  • Implement drag and drop for columns and rows
  • Handle selections (range-based or row-based)
  • Export grid data to Excel, PDF, Word, CSV, or HTML
  • Freeze rows/columns for better navigation
  • Build spreadsheet-like interfaces in Windows Forms
当你需要实现以下需求时可使用本技能:
  • 实现面向单元格的网格,网格自身可存储数据
  • 创建虚拟网格,支持大数据集的按需数据加载
  • 单独自定义单元格,使用GridStyleInfo和样式架构实现
  • 添加类Excel功能(选择框、公式、复制/粘贴)
  • 填充网格数据,可使用循环、PopulateValues或者QueryCellInfo实现
  • 实现多种单元格类型(TextBox、ComboBox、CheckBox、Button等)
  • 启用单元格编辑,支持验证和自定义处理程序
  • 支持公式功能,包含单元格引用和内置函数
  • 创建覆盖单元格或合并单元格
  • 实现行列的拖拽功能
  • 处理选择逻辑(基于范围或者基于行)
  • 导出网格数据到Excel、PDF、Word、CSV或HTML格式
  • 冻结行/列,提升导航体验
  • 在Windows Forms中构建类电子表格界面

GridControl Overview

GridControl概述

The GridControl is a cell-oriented grid that maintains its own data and doesn't require binding to an external data source. It's designed for maximum flexibility and performance, supporting virtually unlimited rows and columns.
Key Capabilities:
  • Cell-level customization down to individual cells
  • Virtual mode for efficient handling of millions of rows
  • 15+ built-in cell types with extensibility
  • Excel-like formulas with cell references
  • Covered cells and merged cell functionality
  • Multiple selection modes (range and row-based)
  • Rich editing with validation
  • Drag and drop support
  • Export to multiple formats
  • Frozen rows and columns
  • Clipboard operations (copy/paste)
  • Touch support
Best Use Cases:
  • Custom data layouts that don't fit table structures
  • Spreadsheet-like applications
  • Virtual grids with on-demand data loading
  • Applications requiring cell-level control
  • Grids that need formula support
  • Complex cell types and custom renderers
GridControl是一款面向单元格的网格控件,可自行维护数据,无需绑定外部数据源。它专为极致灵活性和性能设计,支持近乎无限的行和列数量。
核心能力:
  • 支持细到单个单元格的级别自定义
  • 虚拟模式可高效处理数百万行数据
  • 15+内置单元格类型,支持扩展
  • 支持带单元格引用的类Excel公式
  • 覆盖单元格和合并单元格功能
  • 多种选择模式(范围和基于行)
  • 丰富的编辑能力,支持验证
  • 支持拖拽功能
  • 可导出为多种格式
  • 支持冻结行和列
  • 剪贴板操作(复制/粘贴)
  • 支持触控操作
最佳使用场景:
  • 不适合表结构的自定义数据布局
  • 类电子表格应用
  • 支持按需加载数据的虚拟网格
  • 需要单元格级别控制的应用
  • 需要公式支持的网格
  • 复杂单元格类型和自定义渲染器

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and assembly deployment
  • Adding GridControl through designer
  • Adding GridControl through code
  • Initial configuration and setup
  • Required assemblies and namespaces
  • Basic grid creation
📄 阅读: references/getting-started.md
  • 安装和程序集部署
  • 通过设计器添加GridControl
  • 通过代码添加GridControl
  • 初始配置和设置
  • 所需程序集和命名空间
  • 基础网格创建

Data Population

数据填充

📄 Read: references/data-population.md
  • Setting RowCount and ColCount
  • Populating by looping through cells
  • Using PopulateValues method
  • Virtual grid with QueryCellInfo event
  • Data binding patterns
  • Performance considerations
📄 阅读: references/data-population.md
  • 设置RowCount和ColCount
  • 通过遍历单元格填充数据
  • 使用PopulateValues方法
  • 基于QueryCellInfo事件的虚拟网格
  • 数据绑定模式
  • 性能注意事项

Cell Styling Architecture

单元格样式架构

📄 Read: references/cell-style-architecture.md
  • GridStyleInfo object model
  • Modifying styles through designer
  • Modifying styles through code
  • Using ChangeCells method
  • GridRangeInfo for range operations
  • Appearance customization
  • Style inheritance and base styles
📄 阅读: references/cell-style-architecture.md
  • GridStyleInfo对象模型
  • 通过设计器修改样式
  • 通过代码修改样式
  • 使用ChangeCells方法
  • 用于范围操作的GridRangeInfo
  • 外观自定义
  • 样式继承和基础样式

Cell Types

单元格类型

📄 Read: references/cell-types.md
  • Overview of 15+ cell types
  • TextBox and static text
  • ComboBox and dropdown lists
  • CheckBox and radio buttons
  • DateTimePicker and calendar
  • NumericUpDown and currency
  • Button and link cells
  • Image cells
  • Progress bar cells
  • Custom cell types
  • Cell type configuration
📄 阅读: references/cell-types.md
  • 15+单元格类型概述
  • TextBox和静态文本
  • ComboBox和下拉列表
  • CheckBox和单选按钮
  • DateTimePicker和日历
  • NumericUpDown和货币
  • Button和链接单元格
  • 图片单元格
  • 进度条单元格
  • 自定义单元格类型
  • 单元格类型配置

Editing and Validation

编辑和验证

📄 Read: references/editing-validation.md
  • ReadOnly property (grid and cell level)
  • CurrentCellStartEditing event
  • CurrentCellEditingComplete event
  • Validation rules and handlers
  • Custom edit behavior
  • Preventing edits conditionally
  • Edit mode configuration
📄 阅读: references/editing-validation.md
  • ReadOnly属性(网格和单元格级别)
  • CurrentCellStartEditing事件
  • CurrentCellEditingComplete事件
  • 验证规则和处理程序
  • 自定义编辑行为
  • 条件性阻止编辑
  • 编辑模式配置

Selection

选择功能

📄 Read: references/selection.md
  • Range selection with AllowSelection
  • Row selection with ListBoxSelectionMode
  • GridSelectionFlags enumeration
  • Single vs multiple selection
  • SelectionChanging event
  • SelectionChanged event
  • Programmatic selection
  • Getting selected ranges
📄 阅读: references/selection.md
  • 基于AllowSelection的范围选择
  • 基于ListBoxSelectionMode的行选择
  • GridSelectionFlags枚举
  • 单选vs多选
  • SelectionChanging事件
  • SelectionChanged事件
  • 程序化选择
  • 获取选中范围

Excel-Like Features

类Excel功能

📄 Read: references/excel-like-features.md
  • Excel-like selection frame
  • 2016 vs 2003 selection styles
  • Excel-like current cell highlighting
  • Keyboard navigation (arrows, Tab, Enter)
  • Copy and paste support
  • Clipboard operations
  • Excel-like behaviors
  • Selection frame customization
📄 阅读: references/excel-like-features.md
  • 类Excel选择框
  • 2016 vs 2003选择样式
  • 类Excel当前单元格高亮
  • 键盘导航(方向键、Tab、Enter)
  • 复制粘贴支持
  • 剪贴板操作
  • 类Excel行为
  • 选择框自定义

Formula Support

公式支持

📄 Read: references/formula-support.md
  • Enabling formula engine
  • Formula syntax and cell references
  • Built-in functions (SUM, AVERAGE, IF, etc.)
  • Creating formulas in cells
  • Formula calculation and dependencies
  • Error handling
  • Custom functions
  • Formula events
📄 阅读: references/formula-support.md
  • 启用公式引擎
  • 公式语法和单元格引用
  • 内置函数(SUM、AVERAGE、IF等)
  • 在单元格中创建公式
  • 公式计算和依赖
  • 错误处理
  • 自定义函数
  • 公式相关事件

Covered Ranges

覆盖范围

📄 Read: references/covered-ranges.md
  • Covering multiple cells
  • CoveredRanges collection
  • Adding and removing covered ranges
  • Covered cells vs merged cells
  • Visual appearance of covered cells
  • Cell value in covered ranges
  • Styling covered cells
📄 阅读: references/covered-ranges.md
  • 覆盖多个单元格
  • CoveredRanges集合
  • 添加和移除覆盖范围
  • 覆盖单元格vs合并单元格
  • 覆盖单元格的外观
  • 覆盖范围中的单元格值
  • 覆盖单元格样式设置

Drag and Drop

拖拽功能

📄 Read: references/drag-and-drop.md
  • Enabling column drag and drop
  • Row drag and drop support
  • Touch support for drag operations
  • Drag events and customization
  • Restricting drag operations
  • Visual feedback during drag
📄 阅读: references/drag-and-drop.md
  • 启用列拖拽
  • 行拖拽支持
  • 拖拽操作的触控支持
  • 拖拽事件和自定义
  • 限制拖拽操作
  • 拖拽过程中的视觉反馈

Scrolling and Zooming

滚动和缩放

📄 Read: references/scrolling-zooming.md
  • Scroll bar configuration
  • Frozen rows and columns
  • Zoom functionality
  • Scroll events
  • Smooth scrolling
  • Performance optimization for scrolling
  • Virtual scrolling
📄 阅读: references/scrolling-zooming.md
  • 滚动条配置
  • 冻结行和列
  • 缩放功能
  • 滚动事件
  • 平滑滚动
  • 滚动性能优化
  • 虚拟滚动

Exporting

导出功能

📄 Read: references/exporting.md
  • Export to Excel (XLS, XLSX)
  • Export to PDF
  • Export to Word documents
  • Export to CSV format
  • Export to HTML
  • Export options and customization
  • Styling exported content
  • Range-based export
📄 阅读: references/exporting.md
  • 导出为Excel(XLS、XLSX)
  • 导出为PDF
  • 导出为Word文档
  • 导出为CSV格式
  • 导出为HTML
  • 导出选项和自定义
  • 导出内容样式设置
  • 基于范围的导出

Quick Start Example

快速入门示例

Basic GridControl Setup

基础GridControl设置

csharp
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);
    }
}
csharp
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);
    }
}

Common Patterns

常用模式

Pattern 1: Virtual Grid

模式1:虚拟网格

csharp
gridControl1.Model.RowCount = 1000000;
gridControl1.QueryCellInfo += (sender, e) =>
{
    e.Style.CellValue = GetData(e.RowIndex, e.ColIndex);
};
📄 Details: references/data-population.md
csharp
gridControl1.Model.RowCount = 1000000;
gridControl1.QueryCellInfo += (sender, e) =>
{
    e.Style.CellValue = GetData(e.RowIndex, e.ColIndex);
};
📄 详情: references/data-population.md

Pattern 2: Cell Styling

模式2:单元格样式

csharp
GridStyleInfo style = new GridStyleInfo { BackColor = Color.LightGreen };
gridControl1.ChangeCells(GridRangeInfo.Cells(5, 2, 8, 5), style);
📄 Details: references/cell-style-architecture.md
csharp
GridStyleInfo style = new GridStyleInfo { BackColor = Color.LightGreen };
gridControl1.ChangeCells(GridRangeInfo.Cells(5, 2, 8, 5), style);
📄 详情: references/cell-style-architecture.md

Pattern 3: Formulas

模式3:公式

csharp
gridControl1.Model.EnableFormulas = true;
gridControl1[5, 1].CellValue = "=SUM(A1:A4)";
📄 Details: references/formula-support.md
csharp
gridControl1.Model.EnableFormulas = true;
gridControl1[5, 1].CellValue = "=SUM(A1:A4)";
📄 详情: references/formula-support.md

Pattern 4: Cell Types

模式4:单元格类型

csharp
gridControl1[3, 2].CellType = GridCellTypeName.ComboBox;
gridControl1[3, 2].ChoiceList = new string[] { "Option 1", "Option 2" };
📄 Details: references/cell-types.md
csharp
gridControl1[3, 2].CellType = GridCellTypeName.ComboBox;
gridControl1[3, 2].ChoiceList = new string[] { "Option 1", "Option 2" };
📄 详情: references/cell-types.md

Pattern 5: Selection

模式5:选择

csharp
gridControl1.AllowSelection = GridSelectionFlags.Any;
gridControl1.SelectionChanged += (s, e) => { /* Handle selection */ };
📄 Details: references/selection.md
csharp
gridControl1.AllowSelection = GridSelectionFlags.Any;
gridControl1.SelectionChanged += (s, e) => { /* Handle selection */ };
📄 详情: references/selection.md

Key Properties

核心属性

Essential Properties

基础属性

PropertyTypeDescription
RowCount
intNumber of rows in the grid
ColCount
intNumber of columns in the grid
Model[row, col]
GridStyleInfoAccess cell style and properties
AllowSelection
GridSelectionFlagsEnable/configure range selection
ListBoxSelectionMode
SelectionModeEnable/configure row selection
ReadOnly
boolEnable/disable editing for entire grid
ExcelLikeSelectionFrame
boolShow Excel-style selection frame
ExcelLikeCurrentCell
boolHighlight current cell like Excel
CoveredRanges
GridRangeInfoListCollection of covered cell ranges
属性类型描述
RowCount
int网格中的行数
ColCount
int网格中的列数
Model[row, col]
GridStyleInfo访问单元格样式和属性
AllowSelection
GridSelectionFlags启用/配置范围选择
ListBoxSelectionMode
SelectionMode启用/配置行选择
ReadOnly
bool启用/禁用整个网格的编辑功能
ExcelLikeSelectionFrame
bool显示Excel风格的选择框
ExcelLikeCurrentCell
bool按照Excel风格高亮当前单元格
CoveredRanges
GridRangeInfoList覆盖单元格范围集合

GridStyleInfo Properties

GridStyleInfo属性

PropertyTypeDescription
CellValue
objectValue displayed in the cell
CellType
stringCell type (TextBox, ComboBox, etc.)
BackColor
ColorBackground color
TextColor
ColorText color
Font
GridFontInfoFont settings
ReadOnly
boolEnable/disable editing for cell
Format
stringDisplay format string
HorizontalAlignment
GridHorizontalAlignmentText horizontal alignment
VerticalAlignment
GridVerticalAlignmentText vertical alignment
属性类型描述
CellValue
object单元格中显示的值
CellType
string单元格类型(TextBox、ComboBox等)
BackColor
Color背景色
TextColor
Color文字颜色
Font
GridFontInfo字体设置
ReadOnly
bool启用/禁用单个单元格的编辑功能
Format
string显示格式字符串
HorizontalAlignment
GridHorizontalAlignment文字水平对齐方式
VerticalAlignment
GridVerticalAlignment文字垂直对齐方式

Common Use Cases

常见使用场景

  • Spreadsheet Application - Excel-like interface with formulas and formatting
  • Data Entry Form - Custom forms with various cell types
  • Report Viewer - Formatted reports with merged cells and export
  • Virtual Data Grid - Millions of rows with on-demand loading
  • Dashboard Grid - Custom layouts with visual indicators
  • Configuration Editor - Property grids with specialized cell types
  • 电子表格应用:带公式和格式设置的类Excel界面
  • 数据录入表单:包含多种单元格类型的自定义表单
  • 报表查看器:带合并单元格和导出功能的格式化报表
  • 虚拟数据网格:支持按需加载的数百万行数据网格
  • 仪表盘网格:带视觉指示器的自定义布局
  • 配置编辑器:带特殊单元格类型的属性网格

Troubleshooting

故障排查

Performance Issues: Use virtual mode (QueryCellInfo), BeginUpdate/EndUpdate for batch operations
Selection Not Working: Check AllowSelection property, verify grid has focus
Formulas Not Calculating: Ensure Model.EnableFormulas = true, validate syntax
Cell Values Not Showing: Verify CellValue set, check for covered cells, validate row/column indices (1-based)
For detailed troubleshooting, see the relevant reference files in the Navigation Guide.
性能问题: 使用虚拟模式(QueryCellInfo),批量操作使用BeginUpdate/EndUpdate 选择功能失效: 检查AllowSelection属性,确认网格已获得焦点 公式不计算: 确保Model.EnableFormulas = true,验证公式语法 单元格值不显示: 确认CellValue已设置,检查是否存在覆盖单元格,验证行/列索引(从1开始)
如需详细的故障排查方案,请查看导航指南中的相关参考文档。