syncfusion-flutter-datagrid（syncfusion Flutter datagrid 搜索）

Implementing 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.

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

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

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

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

Data Binding

📄 Read: references/data-binding.md

• Basic DataGrid implementation
• Creating data models and DataGridSource
• Binding with List and 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

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

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

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

Stacked Headers

📄 Read: references/stacked-headers.md

• Multi-level column headers
• Stacked header configuration
• Spanning columns across headers
• Header customization and styling

Freeze Panes

📄 Read: references/freeze-panes.md

• Frozen columns (left side)
• Frozen rows (top side)
• Freeze pane configuration
• Scrolling with frozen panes

Scrolling

📄 Read: references/scrolling.md

• Horizontal and vertical scrolling
• Scroll behavior customization
• Programmatic scrolling
• Scroll events and callbacks
• Virtual scrolling performance

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

Sorting

📄 Read: references/sorting.md

• Single and multi-column sorting
• Custom sorting logic
• Programmatic sorting
• Sort icons and UI customization
• Sort order behavior

Filtering

📄 Read: references/filtering.md

• Filtering functionality basics
• Filter types and predicates
• Programmatic filtering
• Custom filter logic
• Filter UI customization

Selection

📄 Read: references/selection.md

• Selection modes (Single, Multiple, None)
• Selection events (onSelectionChanging, onSelectionChanged)
• Programmatic selection
• Current cell vs selected rows

Grouping

📄 Read: references/grouping.md

• Data grouping (single and multi-column)
• Group expand/collapse behavior
• Custom grouping logic
• Group header customization

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

Paging

📄 Read: references/paging.md

• Paging setup and configuration
• Page size and page navigation
• Custom paging UI
• Programmatic page navigation
• Page change events

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

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

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

Swiping

📄 Read: references/swiping.md

• Row swiping gestures
• Swipe actions and commands
• Swipe event handling
• Custom swipe action UI
• Swipe extent configuration

Styles

📄 Read: references/styles.md

• Grid styling basics
• Cell styling (DataGridCellStyle)
• Conditional cell styling
• Row styling and alternating row colors
• Header styling
• Theme customization

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

Placeholder

📄 Read: references/placeholder.md

• Empty DataGrid view
• Custom placeholder widgets
• Loading state display
• No data message customization

Export to 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

Export to 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

Footer

📄 Read: references/footer.md

• Footer row configuration
• Summary display in footer
• Custom footer content
• Footer styling

Accessibility

📄 Read: references/accessibility.md

• Keyboard navigation
• Screen reader support
• Accessibility best practices

Localization

📄 Read: references/localization.md

• Localization setup
• Multi-language support

Right-to-Left

📄 Read: references/right-to-left.md

• RTL (Right-to-Left) support
• Text direction customization

Quick Start Example

Step 1: Add Package

# 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.

Step 2: Create Data Model

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

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 = [];

  @override
  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();
  }

  @override
  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

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

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

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

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

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

  @override
  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

Common Patterns

Pattern 1: Sorting with Multi-Column Support

Enable single and multi-column sorting with visual indicators:

SfDataGrid(
  source: _employeeDataSource,
  allowSorting: true,
  allowMultiColumnSorting: true,
  allowTriStateSorting: true,
  showSortNumbers: true,
  columns: _columns,
)

Add programmatic sorting:

_employeeDataSource.sortedColumns.add(
  SortColumnDetails(
    name: 'name',
    sortDirection: DataGridSortDirection.ascending,
  ),
);
_employeeDataSource.sort();

Pattern 2: Filtering with Programmatic and UI Support

Enable both programmatic and UI-based filtering:

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:

// 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');

Pattern 3: Grouping with Custom Captions and Expand/Collapse

Implement hierarchical data grouping with expand/collapse functionality:

// 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:

// Expand all groups
_dataGridController.expandAllGroup();

// Collapse groups at specific level
_dataGridController.collapseGroupsAtLevel(1);

Common Use Cases

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

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