syncfusion-flutter-datagrid

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Flutter DataGrid

实现Syncfusion Flutter DataGrid

A comprehensive skill for implementing and customizing the Syncfusion Flutter DataGrid (SfDataGrid) control. The DataGrid displays and manipulates data in a tabular format with support for columns, editing, sorting, filtering, grouping, summaries, paging, and export features.
这是一份用于实现和自定义Syncfusion Flutter DataGrid(SfDataGrid)控件的完整指南。DataGrid以表格格式展示和操作数据,支持列配置、编辑、排序、过滤、分组、汇总、分页和导出功能。

When to Use This Skill

何时使用本指南

Use this skill when you need to:
  • Display tabular data in a Flutter application
  • Bind data sources (List, ObservableList) to a grid
  • Configure columns (auto-generated or manual)
  • Implement cell editing and styling
  • Add sorting, filtering, or searching functionality
  • Group data and display summaries/aggregates
  • Implement paging or incremental loading
  • Enable row operations (drag-drop, swipe, add/delete)
  • Export grid data to Excel or PDF
  • Customize grid appearance and behavior
  • Optimize performance for large datasets
  • Handle keyboard navigation and accessibility
当你需要完成以下需求时可以使用本指南:
  • 在Flutter应用中展示表格数据
  • 给网格绑定数据源(List、ObservableList)
  • 配置列(自动生成或手动配置)
  • 实现单元格编辑和样式设置
  • 添加排序、过滤或搜索功能
  • 对数据进行分组并展示汇总/聚合结果
  • 实现分页或增量加载
  • 支持行操作(拖拽、滑动、新增/删除)
  • 将网格数据导出为Excel或PDF
  • 自定义网格的外观和行为
  • 针对大数据集优化性能
  • 处理键盘导航和无障碍适配

Component Overview

组件概述

The Syncfusion Flutter DataGrid (SfDataGrid) is a high-performance data grid control for displaying and manipulating tabular data in Flutter applications. It supports comprehensive data management features including sorting, filtering, grouping, and summarization. The grid is highly customizable and optimized for both small and large datasets with efficient virtualization and paging support.
SfDataGrid excels at:
  • Displaying structured data in rows and columns
  • Interactive data exploration with sorting and filtering
  • Complex data analysis with grouping and summaries
  • Large dataset handling with virtualization and paging
  • Data entry and validation with in-cell editing
  • Data export to Excel and PDF formats
  • Building responsive data-driven dashboards and reports
Syncfusion Flutter DataGrid(SfDataGrid)是一款高性能数据网格控件,用于在Flutter应用中展示和操作表格数据。它支持完善的数据管理功能,包括排序、过滤、分组和汇总。该网格高度可定制,通过高效的虚拟化和分页支持,对小数据集和大数据集都做了优化。
SfDataGrid的优势场景:
  • 以行列形式展示结构化数据
  • 通过排序和过滤实现交互式数据探索
  • 通过分组和汇总实现复杂数据分析
  • 通过虚拟化和分页处理大数据集
  • 通过单元格内编辑实现数据录入和校验
  • 支持将数据导出为Excel和PDF格式
  • 构建响应式的数据驱动仪表盘和报表

Key Capabilities

核心能力

  • Data Binding Options: Support for List and ObservableList data sources
  • Flexible Column Configuration: Manual column definition support
  • In-Cell Editing: Edit cell content with validation and custom editors
  • Advanced Sorting: Single and multi-column sorting with custom logic
  • Powerful Filtering: Built-in and custom filtering predicates
  • Data Grouping: Group data by one or more columns with expand/collapse
  • Aggregate Summaries: Group and caption summaries with built-in functions
  • Selection Modes: Single, multiple, or no selection with event fallbacks
  • Paging & Virtualization: Efficient handling of large datasets with data virtualization
  • Export Capabilities: Export to Excel (.xlsx) and PDF formats with customization
  • Row Operations: Swipe actions, drag-drop, and dynamic row height
  • Freezing Support: Freeze columns and rows for better navigation
  • Comprehensive Styling: Cell, row, header styling with conditional formatting
  • Accessibility: Keyboard navigation and screen reader support
  • 数据绑定选项: 支持List和ObservableList数据源
  • 灵活的列配置: 支持手动定义列
  • 单元格内编辑: 编辑单元格内容,支持校验和自定义编辑器
  • 高级排序: 单列和多列排序,支持自定义逻辑
  • 强大的过滤: 内置过滤谓词,也支持自定义过滤
  • 数据分组: 按一个或多个列分组,支持展开/折叠
  • 聚合汇总: 分组和标题汇总,内置多种聚合函数
  • 选择模式: 单选、多选、不选,支持事件回调
  • 分页和虚拟化: 通过数据虚拟化高效处理大数据集
  • 导出能力: 可导出为Excel(.xlsx)和PDF格式,支持自定义
  • 行操作: 滑动操作、拖拽、动态行高
  • 冻结支持: 冻结列和行,提升导航体验
  • 完善的样式配置: 单元格、行、表头样式,支持条件格式化
  • 无障碍适配: 支持键盘导航和屏幕阅读器

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and pub package setup
  • Adding dependency to pubspec.yaml
  • Importing the datagrid package
  • Creating your first datagrid
  • Minimal working sample
📄 阅读: references/getting-started.md
  • 安装和pub包设置
  • 给pubspec.yaml添加依赖
  • 导入datagrid包
  • 创建你的第一个datagrid
  • 最小可运行示例

Data Binding

数据绑定

📄 Read: references/data-binding.md
  • Basic DataGrid implementation
  • Creating data models and DataGridSource
  • Binding with List and ObservableList
📄 阅读: references/data-binding.md
  • 基础DataGrid实现
  • 创建数据模型和DataGridSource
  • 绑定List和ObservableList

Column Types

列类型

📄 Read: references/column-types.md
  • Manually defining columns
  • Column properties (columnName, label, width)
  • Column sizing and width options
  • Column visibility and ordering
  • Checkbox column and customization
  • Header icon visiblity
📄 阅读: references/column-types.md
  • 手动定义列
  • 列属性(columnName、label、width)
  • 列尺寸和宽度选项
  • 列可见性和排序
  • 复选框列和自定义
  • 表头图标可见性

Column Sizing

列尺寸设置

📄 Read: references/column-sizing.md
  • Column width configuration modes
  • Auto-fit and fill modes
  • Manual column resizing
  • Width calculation strategies
  • Dynamic width adjustment
📄 阅读: references/column-sizing.md
  • 列宽度配置模式
  • 自适应和填充模式
  • 手动调整列大小
  • 宽度计算策略
  • 动态宽度调整

Column Resizing

列大小调整

📄 Read: references/column-resizing.md
  • Enable/disable column resizing
  • Resize interaction and UX
  • Programmatic resizing
  • Resize events and callbacks
  • Auto-fit column width
📄 阅读: references/column-resizing.md
  • 启用/禁用列大小调整
  • 调整交互和用户体验
  • 程序化调整大小
  • 调整事件和回调
  • 列宽度自适应

Column Drag and Drop

列拖拽

📄 Read: references/column-drag-and-drop.md
  • Enable column reordering via drag-drop
  • Column reorder events
  • Programmatic column reordering
  • Drag-drop constraints and behavior
📄 阅读: references/column-drag-and-drop.md
  • 通过拖拽启用列重排
  • 列重排事件
  • 程序化列重排
  • 拖拽约束和行为

Stacked Headers

堆叠表头

📄 Read: references/stacked-headers.md
  • Multi-level column headers
  • Stacked header configuration
  • Spanning columns across headers
  • Header customization and styling
📄 阅读: references/stacked-headers.md
  • 多级列表头
  • 堆叠表头配置
  • 跨表头列合并
  • 表头自定义和样式设置

Freeze Panes

冻结窗格

📄 Read: references/freeze-panes.md
  • Frozen columns (left side)
  • Frozen rows (top side)
  • Freeze pane configuration
  • Scrolling with frozen panes
📄 阅读: references/freeze-panes.md
  • 冻结列(左侧)
  • 冻结行(顶部)
  • 冻结窗格配置
  • 冻结窗格下的滚动

Scrolling

滚动

📄 Read: references/scrolling.md
  • Horizontal and vertical scrolling
  • Scroll behavior customization
  • Programmatic scrolling
  • Scroll events and callbacks
  • Virtual scrolling performance
📄 阅读: references/scrolling.md
  • 水平和垂直滚动
  • 滚动行为自定义
  • 程序化滚动
  • 滚动事件和回调
  • 虚拟滚动性能

Editing

编辑

📄 Read: references/editing.md
  • Enabling editing
  • Column-level editing control
  • Edit triggers and modes
  • Cell editing events (onBeginEdit, onEndEdit)
  • Programmatic editing
  • Enter arrow and Tab key navigation during editing
📄 阅读: references/editing.md
  • 启用编辑
  • 列级别编辑控制
  • 编辑触发条件和模式
  • 单元格编辑事件(onBeginEdit、onEndEdit)
  • 程序化编辑
  • 编辑过程中支持回车、箭头和Tab键导航

Sorting

排序

📄 Read: references/sorting.md
  • Single and multi-column sorting
  • Custom sorting logic
  • Programmatic sorting
  • Sort icons and UI customization
  • Sort order behavior
📄 阅读: references/sorting.md
  • 单列和多列排序
  • 自定义排序逻辑
  • 程序化排序
  • 排序图标和UI自定义
  • 排序顺序行为

Filtering

过滤

📄 Read: references/filtering.md
  • Filtering functionality basics
  • Filter types and predicates
  • Programmatic filtering
  • Custom filter logic
  • Filter UI customization
📄 阅读: references/filtering.md
  • 过滤功能基础
  • 过滤类型和谓词
  • 程序化过滤
  • 自定义过滤逻辑
  • 过滤UI自定义

Selection

选择

📄 Read: references/selection.md
  • Selection modes (Single, Multiple, None)
  • Selection events (onSelectionChanging, onSelectionChanged)
  • Programmatic selection
  • Current cell vs selected rows
📄 阅读: references/selection.md
  • 选择模式(单选、多选、不选)
  • 选择事件(onSelectionChanging、onSelectionChanged)
  • 程序化选择
  • 当前单元格和选中行的区别

Grouping

分组

📄 Read: references/grouping.md
  • Data grouping (single and multi-column)
  • Group expand/collapse behavior
  • Custom grouping logic
  • Group header customization
📄 阅读: references/grouping.md
  • 数据分组(单列和多列)
  • 分组展开/折叠行为
  • 自定义分组逻辑
  • 分组表头自定义

Summaries

汇总

📄 Read: references/summaries.md
  • Summary rows (Group and Caption summaries)
  • Built-in aggregate functions (Sum, Average, Count, Min, Max)
  • Custom summary calculations
  • Summary display formatting
  • Summary footer configuration
📄 阅读: references/summaries.md
  • 汇总行(分组汇总和标题汇总)
  • 内置聚合函数(求和、平均值、计数、最小值、最大值)
  • 自定义汇总计算
  • 汇总展示格式化
  • 汇总页脚配置

Paging

分页

📄 Read: references/paging.md
  • Paging setup and configuration
  • Page size and page navigation
  • Custom paging UI
  • Programmatic page navigation
  • Page change events
📄 阅读: references/paging.md
  • 分页设置和配置
  • 每页大小和页面导航
  • 自定义分页UI
  • 程序化页面导航
  • 页面切换事件

Load More

加载更多

📄 Read: references/load-more.md
  • Incremental loading setup
  • Load More row handling
  • Load More triggers and events
  • Programmatic load more control
  • Large dataset pagination strategies
📄 阅读: references/load-more.md
  • 增量加载设置
  • 加载更多行处理
  • 加载更多触发条件和事件
  • 程序化加载更多控制
  • 大数据集分页策略

Pull to Refresh

下拉刷新

📄 Read: references/pull-to-refresh.md
  • Pull to refresh gestures
  • Refresh event handling
  • Custom refresh UI
  • Loading state management
  • Data refresh patterns
📄 阅读: references/pull-to-refresh.md
  • 下拉刷新手势
  • 刷新事件处理
  • 自定义刷新UI
  • 加载状态管理
  • 数据刷新模式

Row Height Customization

行高自定义

📄 Read: references/row-height-customization.md
  • Row height configuration
  • Auto row height based on content
  • QueryRowHeight event usage
  • Dynamic row height adjustment
  • Header row height customization
📄 阅读: references/row-height-customization.md
  • 行高配置
  • 基于内容自动适配行高
  • QueryRowHeight事件使用
  • 动态行高调整
  • 表头行高自定义

Swiping

滑动

📄 Read: references/swiping.md
  • Row swiping gestures
  • Swipe actions and commands
  • Swipe event handling
  • Custom swipe action UI
  • Swipe extent configuration
📄 阅读: references/swiping.md
  • 行滑动手势
  • 滑动操作和指令
  • 滑动事件处理
  • 自定义滑动操作UI
  • 滑动范围配置

Styles

样式

📄 Read: references/styles.md
  • Grid styling basics
  • Cell styling (DataGridCellStyle)
  • Conditional cell styling
  • Row styling and alternating row colors
  • Header styling
  • Theme customization
📄 阅读: references/styles.md
  • 网格样式基础
  • 单元格样式(DataGridCellStyle)
  • 条件单元格样式
  • 行样式和交替行颜色
  • 表头样式
  • 主题自定义

Conditional Styling

条件样式

📄 Read: references/conditional-styling.md
  • Apply styles based on cell/row data
  • Dynamic styling logic
  • Style builders and callbacks
  • Performance optimization for conditional styles
📄 阅读: references/conditional-styling.md
  • 基于单元格/行数据应用样式
  • 动态样式逻辑
  • 样式构建器和回调
  • 条件样式性能优化

Placeholder

占位符

📄 Read: references/placeholder.md
  • Empty DataGrid view
  • Custom placeholder widgets
  • Loading state display
  • No data message customization
📄 阅读: references/placeholder.md
  • 空DataGrid视图
  • 自定义占位符组件
  • 加载状态展示
  • 无数据消息自定义

Export to Excel

导出到Excel

📄 Read: references/export-to-excel.md
  • Export DataGrid to Excel
  • Excel export customization (columns, rows, styling)
  • Excel export options and events
  • File save and sharing
📄 阅读: references/export-to-excel.md
  • 将DataGrid导出为Excel
  • Excel导出自定义(列、行、样式)
  • Excel导出选项和事件
  • 文件保存和分享

Export to PDF

导出到PDF

📄 Read: references/export-to-pdf.md
  • Export DataGrid to PDF
  • PDF export customization
  • Page orientation and sizing
  • PDF export events
  • File save and sharing
📄 阅读: references/export-to-pdf.md
  • 将DataGrid导出为PDF
  • PDF导出自定义
  • 页面方向和尺寸
  • PDF导出事件
  • 文件保存和分享

Footer

页脚

📄 Read: references/footer.md
  • Footer row configuration
  • Summary display in footer
  • Custom footer content
  • Footer styling
📄 阅读: references/footer.md
  • 页脚行配置
  • 页脚展示汇总
  • 自定义页脚内容
  • 页脚样式

Accessibility

无障碍适配

📄 Read: references/accessibility.md
  • Keyboard navigation
  • Screen reader support
  • Accessibility best practices
📄 阅读: references/accessibility.md
  • 键盘导航
  • 屏幕阅读器支持
  • 无障碍最佳实践

Localization

本地化

📄 Read: references/localization.md
  • Localization setup
  • Multi-language support
📄 阅读: references/localization.md
  • 本地化设置
  • 多语言支持

Right-to-Left

从右到左

📄 Read: references/right-to-left.md
  • RTL (Right-to-Left) support
  • Text direction customization
📄 阅读: references/right-to-left.md
  • RTL(从右到左)支持
  • 文本方向自定义

Quick Start Example

快速入门示例

Step 1: Add Package

步骤1:添加包

bash
undefined
bash
undefined

Always installs the latest compatible version automatically

自动安装最新兼容版本

flutter pub add syncfusion_flutter_datagrid
> Always install the package via terminal — do **not** edit `pubspec.yaml` directly.
> Run this command from the Flutter project root and wait for it to complete successfully before proceeding.
flutter pub add syncfusion_flutter_datagrid
> 请始终通过终端安装该包——**不要**直接编辑`pubspec.yaml`文件。
> 在Flutter项目根目录运行该命令,等待执行成功后再进行后续步骤。

Step 2: Create Data Model

步骤2:创建数据模型

dart
class OrderInfo {
  int orderId;
  String customerId;
  String shipCountry;
  double freight;
  DateTime orderDate;

  OrderInfo({
    required this.orderId,
    required this.customerId,
    required this.shipCountry,
    required this.freight,
    required this.orderDate,
  });
}
dart
class OrderInfo {
  int orderId;
  String customerId;
  String shipCountry;
  double freight;
  DateTime orderDate;

  OrderInfo({
    required this.orderId,
    required this.customerId,
    required this.shipCountry,
    required this.freight,
    required this.orderDate,
  });
}

Step 3: Create DataGridSource

步骤3:创建DataGridSource

dart
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class OrderDataSource extends DataGridSource {
  late List<OrderInfo> _orders;

  OrderDataSource(List<OrderInfo> orders) {
    _orders = orders;
    buildDataGridRows();
  }

  List<DataGridRow> dataGridRows = [];

  
  List<DataGridRow> get rows => dataGridRows;

  void buildDataGridRows() {
    dataGridRows = _orders
        .map<DataGridRow>((order) => DataGridRow(cells: [
              DataGridCell<int>(columnName: 'orderId', value: order.orderId),
              DataGridCell<String>(columnName: 'customerId', value: order.customerId),
              DataGridCell<String>(columnName: 'shipCountry', value: order.shipCountry),
              DataGridCell<double>(columnName: 'freight', value: order.freight),
              DataGridCell<DateTime>(columnName: 'orderDate', value: order.orderDate),
            ]))
        .toList();
  }

  
  DataGridRowAdapter? buildRow(DataGridRow row) {
    return DataGridRowAdapter(cells: [
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[0].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[1].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[2].value.toString()),
      ),
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text('\$${row.getCells()[3].value.toStringAsFixed(2)}'),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[4].value.toString().split(' ')[0]),
      ),
    ]);
  }
}
dart
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class OrderDataSource extends DataGridSource {
  late List<OrderInfo> _orders;

  OrderDataSource(List<OrderInfo> orders) {
    _orders = orders;
    buildDataGridRows();
  }

  List<DataGridRow> dataGridRows = [];

  
  List<DataGridRow> get rows => dataGridRows;

  void buildDataGridRows() {
    dataGridRows = _orders
        .map<DataGridRow>((order) => DataGridRow(cells: [
              DataGridCell<int>(columnName: 'orderId', value: order.orderId),
              DataGridCell<String>(columnName: 'customerId', value: order.customerId),
              DataGridCell<String>(columnName: 'shipCountry', value: order.shipCountry),
              DataGridCell<double>(columnName: 'freight', value: order.freight),
              DataGridCell<DateTime>(columnName: 'orderDate', value: order.orderDate),
            ]))
        .toList();
  }

  
  DataGridRowAdapter? buildRow(DataGridRow row) {
    return DataGridRowAdapter(cells: [
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[0].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[1].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[2].value.toString()),
      ),
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text('\$${row.getCells()[3].value.toStringAsFixed(2)}'),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[4].value.toString().split(' ')[0]),
      ),
    ]);
  }
}

Step 4: Add DataGrid to View

步骤4:将DataGrid添加到视图

dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class DataGridPage extends StatefulWidget {
  const DataGridPage({Key? key}) : super(key: key);

  
  State<DataGridPage> createState() => _DataGridPageState();
}

class _DataGridPageState extends State<DataGridPage> {
  late List<OrderInfo> _orders;
  late OrderDataSource _orderDataSource;

  
  void initState() {
    super.initState();
    _orders = getOrders();
    _orderDataSource = OrderDataSource(_orders);
  }

  
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('DataGrid'),
      ),
      body: SfDataGrid(
        source: _orderDataSource,
        columns: [
          GridColumn(
            columnName: 'orderId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Order ID'),
            ),
          ),
          GridColumn(
            columnName: 'customerId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Customer Name'),
            ),
          ),
          GridColumn(
            columnName: 'shipCountry',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Ship Country'),
            ),
          ),
          GridColumn(
            columnName: 'freight',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Freight'),
            ),
          ),
          GridColumn(
            columnName: 'orderDate',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Order Date'),
            ),
          ),
        ],
      ),
    );
  }

  List<OrderInfo> getOrders() {
    return [
      OrderInfo(
        orderId: 1001,
        customerId: 'ALFKI',
        shipCountry: 'Germany',
        freight: 32.38,
        orderDate: DateTime(2024, 01, 15),
      ),
      OrderInfo(
        orderId: 1002,
        customerId: 'FRANS',
        shipCountry: 'Mexico',
        freight: 11.61,
        orderDate: DateTime(2024, 01, 14),
      ),
      OrderInfo(
        orderId: 1003,
        customerId: 'MEREP',
        shipCountry: 'Canada',
        freight: 45.34,
        orderDate: DateTime(2024, 01, 13),
      ),
    ];
  }
}
dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class DataGridPage extends StatefulWidget {
  const DataGridPage({Key? key}) : super(key: key);

  
  State<DataGridPage> createState() => _DataGridPageState();
}

class _DataGridPageState extends State<DataGridPage> {
  late List<OrderInfo> _orders;
  late OrderDataSource _orderDataSource;

  
  void initState() {
    super.initState();
    _orders = getOrders();
    _orderDataSource = OrderDataSource(_orders);
  }

  
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('DataGrid'),
      ),
      body: SfDataGrid(
        source: _orderDataSource,
        columns: [
          GridColumn(
            columnName: 'orderId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Order ID'),
            ),
          ),
          GridColumn(
            columnName: 'customerId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Customer Name'),
            ),
          ),
          GridColumn(
            columnName: 'shipCountry',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Ship Country'),
            ),
          ),
          GridColumn(
            columnName: 'freight',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Freight'),
            ),
          ),
          GridColumn(
            columnName: 'orderDate',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Order Date'),
            ),
          ),
        ],
      ),
    );
  }

  List<OrderInfo> getOrders() {
    return [
      OrderInfo(
        orderId: 1001,
        customerId: 'ALFKI',
        shipCountry: 'Germany',
        freight: 32.38,
        orderDate: DateTime(2024, 01, 15),
      ),
      OrderInfo(
        orderId: 1002,
        customerId: 'FRANS',
        shipCountry: 'Mexico',
        freight: 11.61,
        orderDate: DateTime(2024, 01, 14),
      ),
      OrderInfo(
        orderId: 1003,
        customerId: 'MEREP',
        shipCountry: 'Canada',
        freight: 45.34,
        orderDate: DateTime(2024, 01, 13),
      ),
    ];
  }
}

Key Properties and Configuration

核心属性和配置

PropertyTypeDescription
source
DataGridSourceData source for the grid (required)
columns
List<GridColumn>Column definitions (required)
rowHeight
doubleDefault row height
headerRowHeight
doubleHeight of header row
allowSorting
boolEnable sorting
allowMultiColumnSorting
boolEnable multi-column sorting
allowFiltering
boolEnable filtering
allowEditing
boolEnable cell editing
navigationMode
GridNavigationModeRow or Cell navigation
selectionMode
SelectionModeNone, Single, or Multiple
frozenColumnsCount
intNumber of frozen columns from left
frozenRowsCount
intNumber of frozen rows from top
columnWidthMode
ColumnWidthModeAuto, Fill, None
属性类型描述
source
DataGridSource网格的数据源(必填)
columns
List<GridColumn>列定义(必填)
rowHeight
double默认行高
headerRowHeight
double表头行高度
allowSorting
bool启用排序
allowMultiColumnSorting
bool启用多列排序
allowFiltering
bool启用过滤
allowEditing
bool启用单元格编辑
navigationMode
GridNavigationMode行导航或单元格导航
selectionMode
SelectionMode不选、单选或多选
frozenColumnsCount
int左侧冻结列的数量
frozenRowsCount
int顶部冻结行的数量
columnWidthMode
ColumnWidthMode自适应、填充、无

Common Patterns

常用模式

Pattern 1: Sorting with Multi-Column Support

模式1:支持多列排序

Enable single and multi-column sorting with visual indicators:
dart
SfDataGrid(
  source: _employeeDataSource,
  allowSorting: true,
  allowMultiColumnSorting: true,
  allowTriStateSorting: true,
  showSortNumbers: true,
  columns: _columns,
)
Add programmatic sorting:
dart
_employeeDataSource.sortedColumns.add(
  SortColumnDetails(
    name: 'name',
    sortDirection: DataGridSortDirection.ascending,
  ),
);
_employeeDataSource.sort();
启用单列和多列排序,带视觉指示器:
dart
SfDataGrid(
  source: _employeeDataSource,
  allowSorting: true,
  allowMultiColumnSorting: true,
  allowTriStateSorting: true,
  showSortNumbers: true,
  columns: _columns,
)
添加程序化排序:
dart
_employeeDataSource.sortedColumns.add(
  SortColumnDetails(
    name: 'name',
    sortDirection: DataGridSortDirection.ascending,
  ),
);
_employeeDataSource.sort();

Pattern 2: Filtering with Programmatic and UI Support

模式2:同时支持程序化和UI过滤

Enable both programmatic and UI-based filtering:
dart
SfDataGrid(
  source: _employeeDataSource,
  allowFiltering: true,
  columns: _columns,
  onFilterChanging: (DataGridFilterChangeDetails details) {
    // Optional: validate before applying filter
    return true;
  },
  onFilterChanged: (DataGridFilterChangeDetails details) {
    // Optional: handle post-filter notification
    print('Filtered column: ${details.column.columnName}');
  },
)
Add programmatic filters:
dart
// Add single condition
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    type: FilterType.greaterThanOrEqual,
    value: 50000,
  ),
);

// Add multiple conditions (AND operator)
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    value: 100000,
    type: FilterType.lessThanOrEqual,
    filterOperator: FilterOperator.and,
  ),
);

// Clear filters
_employeeDataSource.clearFilters('salary');
启用程序化过滤和基于UI的过滤:
dart
SfDataGrid(
  source: _employeeDataSource,
  allowFiltering: true,
  columns: _columns,
  onFilterChanging: (DataGridFilterChangeDetails details) {
    // 可选:应用过滤前校验
    return true;
  },
  onFilterChanged: (DataGridFilterChangeDetails details) {
    // 可选:处理过滤后通知
    print('过滤的列: ${details.column.columnName}');
  },
)
添加程序化过滤:
dart
// 添加单个条件
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    type: FilterType.greaterThanOrEqual,
    value: 50000,
  ),
);

// 添加多个条件(AND运算符)
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    value: 100000,
    type: FilterType.lessThanOrEqual,
    filterOperator: FilterOperator.and,
  ),
);

// 清除过滤
_employeeDataSource.clearFilters('salary');

Pattern 3: Grouping with Custom Captions and Expand/Collapse

模式3:支持自定义标题和展开/折叠的分组

Implement hierarchical data grouping with expand/collapse functionality:
dart
// In initState
_employeeDataSource.addColumnGroup(
  ColumnGroup(name: 'city', sortGroupRows: true),
);

// In widget build
SfDataGrid(
  source: _employeeDataSource,
  controller: _dataGridController,
  allowExpandCollapseGroup: true,
  autoExpandGroups: false,
  groupCaptionTitleFormat: '{ColumnName}: {Key} ({ItemsCount} records)',
  groupExpanded: (DataGridGroupChangedDetails group) {
    print('Group expanded: ${group.key}');
  },
  groupCollapsed: (DataGridGroupChangedDetails group) {
    print('Group collapsed: ${group.key}');
  },
  columns: _columns,
)
Programmatic expand/collapse:
dart
// Expand all groups
_dataGridController.expandAllGroup();

// Collapse groups at specific level
_dataGridController.collapseGroupsAtLevel(1);
实现分层数据分组,带展开/折叠功能:
dart
// 在initState中
_employeeDataSource.addColumnGroup(
  ColumnGroup(name: 'city', sortGroupRows: true),
);

// 在widget build中
SfDataGrid(
  source: _employeeDataSource,
  controller: _dataGridController,
  allowExpandCollapseGroup: true,
  autoExpandGroups: false,
  groupCaptionTitleFormat: '{ColumnName}: {Key} ({ItemsCount} 条记录)',
  groupExpanded: (DataGridGroupChangedDetails group) {
    print('分组已展开: ${group.key}');
  },
  groupCollapsed: (DataGridGroupChangedDetails group) {
    print('分组已折叠: ${group.key}');
  },
  columns: _columns,
)
程序化展开/折叠:
dart
// 展开所有分组
_dataGridController.expandAllGroup();

// 折叠指定层级的分组
_dataGridController.collapseGroupsAtLevel(1);

Common Use Cases

常见使用场景

Use CaseKey FeaturesReference Files
Basic data displayData binding, columnsgetting-started.md, column-types.md
Editable gridCell editing, validationediting.md, data-binding.md
Sortable/filterable tableSorting, filteringsorting.md, filtering.md
Grouped data with totalsGrouping, summariesgrouping.md, summaries.md
Large datasetPaging, Load Morepaging.md, load-more.md
Data exportExcel/PDF exportexport-to-excel.md, export-to-pdf.md
Responsive layoutColumn sizing, scrollingcolumn-sizing.md, scrolling.md
Custom cell layoutsTemplates, stylingstyles.md, conditional-styling.md
使用场景核心功能参考文件
基础数据展示数据绑定、列配置getting-started.md, column-types.md
可编辑网格单元格编辑、校验editing.md, data-binding.md
可排序/过滤的表格排序、过滤sorting.md, filtering.md
带合计的分组数据分组、汇总grouping.md, summaries.md
大数据集分页、加载更多paging.md, load-more.md
数据导出Excel/PDF导出export-to-excel.md, export-to-pdf.md
响应式布局列尺寸设置、滚动column-sizing.md, scrolling.md
自定义单元格布局模板、样式styles.md, conditional-styling.md

Troubleshooting

故障排查

DataGrid not showing data:
  • Verify
    source
    is set with a valid DataGridSource
  • Check that
    columns
    are defined
  • Ensure
    buildDataGridRows()
    is called in DataGridSource constructor
  • Verify data model is not empty
Editing not working:
  • Set
    allowEditing=true
  • Set
    navigationMode
    to
    GridNavigationMode.cell
  • Set
    selectionMode
    to Single or Multiple
  • Check column's
    allowEditing
    property
Sorting not working:
  • Enable
    allowSorting=true
    on the SfDataGrid
  • Verify column header is tappable (check
    GridColumn.allowSorting
    is not
    false
    )
  • Check that custom
    compare()
    method is implemented correctly in DataGridSource if using custom sorting
  • For async sorting, override
    performSorting()
    in DataGridSource
Filtering not working:
  • Enable
    allowFiltering=true
    on the SfDataGrid
  • Verify column header has filter icon visible (check
    GridColumn.allowFiltering
    is not
    false
    )
  • For programmatic filters, ensure column name in
    addFilter()
    matches exact
    GridColumn.columnName
  • Check
    FilterCondition.type
    is appropriate for the data type
  • Verify
    effectiveRows
    returns filtered results; use
    clearFilters()
    to reset all filters
Grouping not showing:
  • Ensure
    addColumnGroup()
    is called before building the grid
  • Verify
    ColumnGroup.name
    exactly matches a
    GridColumn.columnName
  • Check that grouping column contains non-null values
  • Enable
    allowExpandCollapseGroup=true
    to show expand/collapse UI
  • Use
    DataGridController
    with
    expandAllGroup()
    to verify grouping is working
Multi-Column Sorting not working:
  • Set
    allowMultiColumnSorting=true
    on the SfDataGrid
  • For web/desktop: hold Ctrl while clicking column headers to add additional sort columns
  • Check
    sortedColumns
    list to verify multiple sort entries exist
  • Call
    sort()
    after modifying
    sortedColumns
    programmatically
Custom Grouping Logic not applied:
  • Override
    performGrouping()
    in DataGridSource
  • Return the custom group key as a String
  • Ensure the method returns non-null values for proper grouping
DataGrid不展示数据:
  • 确认
    source
    设置了有效的DataGridSource
  • 检查
    columns
    是否已定义
  • 确保DataGridSource构造函数中调用了
    buildDataGridRows()
  • 确认数据模型不为空
编辑功能不生效:
  • 设置
    allowEditing=true
  • navigationMode
    设置为
    GridNavigationMode.cell
  • selectionMode
    设置为单选或多选
  • 检查列的
    allowEditing
    属性
排序功能不生效:
  • 在SfDataGrid上启用
    allowSorting=true
  • 确认列表头可点击(检查
    GridColumn.allowSorting
    不为
    false
  • 如果使用自定义排序,检查DataGridSource中的自定义
    compare()
    方法是否正确实现
  • 异步排序需要重写DataGridSource中的
    performSorting()
过滤功能不生效:
  • 在SfDataGrid上启用
    allowFiltering=true
  • 确认列表头可见过滤图标(检查
    GridColumn.allowFiltering
    不为
    false
  • 程序化过滤时,确保
    addFilter()
    中的列名和
    GridColumn.columnName
    完全一致
  • 检查
    FilterCondition.type
    是否适配对应的数据类型
  • 确认
    effectiveRows
    返回过滤后的结果;使用
    clearFilters()
    重置所有过滤
分组不展示:
  • 确保构建网格前调用了
    addColumnGroup()
  • 确认
    ColumnGroup.name
    GridColumn.columnName
    完全匹配
  • 检查分组列包含非空值
  • 启用
    allowExpandCollapseGroup=true
    展示展开/折叠UI
  • 结合
    DataGridController
    expandAllGroup()
    验证分组是否正常工作
多列排序不生效:
  • 在SfDataGrid上设置
    allowMultiColumnSorting=true
  • Web/桌面端:按住Ctrl点击列表头添加额外排序列
  • 检查
    sortedColumns
    列表确认存在多个排序条目
  • 程序化修改
    sortedColumns
    后调用
    sort()
自定义分组逻辑不生效:
  • 重写DataGridSource中的
    performGrouping()
  • 以字符串形式返回自定义分组键
  • 确保方法返回非空值才能正常分组

Next Steps

后续步骤

  1. Start with references/getting-started.md for basic setup
  2. Configure columns using references/column-types.md
  3. Add interactivity with editing, sorting, and filtering
  4. Optimize for your data size using paging or virtualization
  5. Customize appearance with styling and templates
  1. 先阅读references/getting-started.md完成基础设置
  2. 参考references/column-types.md配置列
  3. 添加编辑、排序、过滤等交互功能
  4. 使用分页或虚拟化针对你的数据规模做优化
  5. 通过样式和模板自定义外观