syncfusion-flutter-datagrid
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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
undefinedbash
undefinedAlways 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
核心属性和配置
| Property | Type | Description |
|---|---|---|
| DataGridSource | Data source for the grid (required) |
| List<GridColumn> | Column definitions (required) |
| double | Default row height |
| double | Height of header row |
| bool | Enable sorting |
| bool | Enable multi-column sorting |
| bool | Enable filtering |
| bool | Enable cell editing |
| GridNavigationMode | Row or Cell navigation |
| SelectionMode | None, Single, or Multiple |
| int | Number of frozen columns from left |
| int | Number of frozen rows from top |
| ColumnWidthMode | Auto, Fill, None |
| 属性 | 类型 | 描述 |
|---|---|---|
| DataGridSource | 网格的数据源(必填) |
| List<GridColumn> | 列定义(必填) |
| double | 默认行高 |
| double | 表头行高度 |
| bool | 启用排序 |
| bool | 启用多列排序 |
| bool | 启用过滤 |
| bool | 启用单元格编辑 |
| GridNavigationMode | 行导航或单元格导航 |
| SelectionMode | 不选、单选或多选 |
| int | 左侧冻结列的数量 |
| int | 顶部冻结行的数量 |
| 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 Case | Key Features | Reference Files |
|---|---|---|
| Basic data display | Data binding, columns | getting-started.md, column-types.md |
| Editable grid | Cell editing, validation | editing.md, data-binding.md |
| Sortable/filterable table | Sorting, filtering | sorting.md, filtering.md |
| Grouped data with totals | Grouping, summaries | grouping.md, summaries.md |
| Large dataset | Paging, Load More | paging.md, load-more.md |
| Data export | Excel/PDF export | export-to-excel.md, export-to-pdf.md |
| Responsive layout | Column sizing, scrolling | column-sizing.md, scrolling.md |
| Custom cell layouts | Templates, styling | styles.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 is set with a valid DataGridSource
source - Check that are defined
columns - Ensure is called in DataGridSource constructor
buildDataGridRows() - Verify data model is not empty
Editing not working:
- Set
allowEditing=true - Set to
navigationModeGridNavigationMode.cell - Set to Single or Multiple
selectionMode - Check column's property
allowEditing
Sorting not working:
- Enable on the SfDataGrid
allowSorting=true - Verify column header is tappable (check is not
GridColumn.allowSorting)false - Check that custom method is implemented correctly in DataGridSource if using custom sorting
compare() - For async sorting, override in DataGridSource
performSorting()
Filtering not working:
- Enable on the SfDataGrid
allowFiltering=true - Verify column header has filter icon visible (check is not
GridColumn.allowFiltering)false - For programmatic filters, ensure column name in matches exact
addFilter()GridColumn.columnName - Check is appropriate for the data type
FilterCondition.type - Verify returns filtered results; use
effectiveRowsto reset all filtersclearFilters()
Grouping not showing:
- Ensure is called before building the grid
addColumnGroup() - Verify exactly matches a
ColumnGroup.nameGridColumn.columnName - Check that grouping column contains non-null values
- Enable to show expand/collapse UI
allowExpandCollapseGroup=true - Use with
DataGridControllerto verify grouping is workingexpandAllGroup()
Multi-Column Sorting not working:
- Set on the SfDataGrid
allowMultiColumnSorting=true - For web/desktop: hold Ctrl while clicking column headers to add additional sort columns
- Check list to verify multiple sort entries exist
sortedColumns - Call after modifying
sort()programmaticallysortedColumns
Custom Grouping Logic not applied:
- Override in DataGridSource
performGrouping() - Return the custom group key as a String
- Ensure the method returns non-null values for proper grouping
DataGrid不展示数据:
- 确认设置了有效的DataGridSource
source - 检查是否已定义
columns - 确保DataGridSource构造函数中调用了
buildDataGridRows() - 确认数据模型不为空
编辑功能不生效:
- 设置
allowEditing=true - 将设置为
navigationModeGridNavigationMode.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 - 检查分组列包含非空值
- 启用展示展开/折叠UI
allowExpandCollapseGroup=true - 结合和
DataGridController验证分组是否正常工作expandAllGroup()
多列排序不生效:
- 在SfDataGrid上设置
allowMultiColumnSorting=true - Web/桌面端:按住Ctrl点击列表头添加额外排序列
- 检查列表确认存在多个排序条目
sortedColumns - 程序化修改后调用
sortedColumnssort()
自定义分组逻辑不生效:
- 重写DataGridSource中的
performGrouping() - 以字符串形式返回自定义分组键
- 确保方法返回非空值才能正常分组
Next Steps
后续步骤
- Start with references/getting-started.md for basic setup
- Configure columns using references/column-types.md
- Add interactivity with editing, sorting, and filtering
- Optimize for your data size using paging or virtualization
- Customize appearance with styling and templates
- 先阅读references/getting-started.md完成基础设置
- 参考references/column-types.md配置列
- 添加编辑、排序、过滤等交互功能
- 使用分页或虚拟化针对你的数据规模做优化
- 通过样式和模板自定义外观