syncfusion-flutter-datagrid

Syncfusion Flutter DataGrid の実装

Syncfusion Flutter DataGrid（SfDataGrid）コントロールを実装およびカスタマイズするための包括的なスキルです。DataGrid は、列、編集、並べ替え、フィルタリング、グループ化、集計、ページング、エクスポート機能を備え、データを表形式で表示および操作します。

このスキルを使用する場面

次のような場合にこのスキルを使用してください。

• Flutter アプリケーションで表形式のデータを表示する
• データソース（List、ObservableList）をグリッドにバインドする
• 列を設定する（自動生成または手動）
• セルの編集とスタイル設定を実装する
• 並べ替え、フィルタリング、検索機能を追加する
• データをグループ化し、集計を表示する
• ページングまたは段階的な読み込みを実装する
• 行操作（ドラッグ＆ドロップ、スワイプ、追加／削除）を有効にする
• グリッドのデータを Excel または PDF にエクスポートする
• グリッドの外観と動作をカスタマイズする
• 大規模なデータセットでパフォーマンスを最適化する
• キーボード操作とアクセシビリティに対応する

コンポーネントの概要

Syncfusion Flutter DataGrid（SfDataGrid）は、Flutter アプリケーションで表形式のデータを表示および操作するための、高性能なデータグリッドコントロールです。並べ替え、フィルタリング、グループ化、集計など、包括的なデータ管理機能を備えています。グリッドは高度なカスタマイズが可能で、効率的な仮想化とページングにより、小規模から大規模までのデータセットに最適化されています。

SfDataGrid が得意とすること：

• 構造化データを行と列で表示する
• 並べ替えとフィルタリングによる対話的なデータ探索
• グループ化と集計による複雑なデータ分析
• 仮想化とページングによる大規模なデータセットの処理
• セル内編集によるデータ入力と検証
• Excel および PDF 形式へのデータのエクスポート
• レスポンシブなデータ駆動型ダッシュボードとレポートの構築

主な機能

• データバインディングのオプション： List および ObservableList のデータソースに対応
• 柔軟な列設定： 列を手動で定義可能
• セル内編集： 検証機能やカスタムエディターを使用してセルの内容を編集
• 高度な並べ替え： カスタムロジックによる単一列および複数列の並べ替え
• 強力なフィルタリング： 組み込みおよびカスタムのフィルター述語
• データのグループ化： 1つ以上の列でデータをグループ化し、展開／折りたたみ
• 集計サマリー： 組み込み関数によるグループおよびキャプションのサマリー
• 選択モード： 単一選択、複数選択、または選択なしに対応し、イベントのフォールバックも利用可能
• ページングと仮想化： データ仮想化により大規模なデータセットを効率的に処理
• エクスポート機能： カスタマイズして Excel（.xlsx）および PDF 形式にエクスポート
• 行操作： スワイプ操作、ドラッグ＆ドロップ、動的な行の高さ
• 固定表示への対応： 列と行を固定してナビゲーションを改善
• 包括的なスタイル設定： 条件付き書式によるセル、行、ヘッダーのスタイル設定
• アクセシビリティ： キーボード操作とスクリーンリーダーに対応

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールと pub パッケージのセットアップ
• pubspec.yaml への依存関係の追加
• datagrid パッケージのインポート
• 最初の datagrid の作成
• 最小限の動作サンプル

データバインディング

📄 参照： references/data-binding.md

• DataGrid の基本的な実装
• データモデルと DataGridSource の作成
• List および ObservableList を使ったバインディング

列の種類

📄 参照： references/column-types.md

• 列の手動定義
• 列のプロパティ（columnName、label、width）
• 列のサイズと幅のオプション
• 列の表示／非表示と並べ替え
• チェックボックス列とカスタマイズ
• ヘッダーアイコンの表示設定

列のサイズ設定

📄 参照： references/column-sizing.md

• 列幅の設定モード
• 自動調整モードと塗りつぶしモード
• 手動での列幅変更
• 幅の計算方法
• 動的な幅の調整

列のサイズ変更

📄 参照： references/column-resizing.md

• 列のサイズ変更の有効化／無効化
• サイズ変更の操作と UX
• プログラムによるサイズ変更
• サイズ変更イベントとコールバック
• 列幅の自動調整

列のドラッグ＆ドロップ

📄 参照： references/column-drag-and-drop.md

• ドラッグ＆ドロップによる列の並べ替えの有効化
• 列の並べ替えイベント
• プログラムによる列の並べ替え
• ドラッグ＆ドロップの制約と動作

複数段ヘッダー

📄 参照： references/stacked-headers.md

• 複数レベルの列ヘッダー
• 複数段ヘッダーの設定
• ヘッダー間での列の結合
• ヘッダーのカスタマイズとスタイル設定

ペインの固定

📄 参照： references/freeze-panes.md

• 列の固定（左側）
• 行の固定（上側）
• ペイン固定の設定
• ペインを固定した状態でのスクロール

スクロール

📄 参照： references/scrolling.md

• 水平スクロールと垂直スクロール
• スクロール動作のカスタマイズ
• プログラムによるスクロール
• スクロールイベントとコールバック
• 仮想スクロールのパフォーマンス

編集

📄 参照： references/editing.md

• 編集の有効化
• 列単位の編集制御
• 編集のトリガーとモード
• セル編集イベント（onBeginEdit、onEndEdit）
• プログラムによる編集
• 編集中の Enter、矢印キー、Tab キーによる移動

並べ替え

📄 参照： references/sorting.md

• 単一列および複数列による並べ替え
• カスタムの並べ替えロジック
• プログラムによる並べ替え
• 並べ替えアイコンと UI のカスタマイズ
• 並べ替え順序の動作

フィルタリング

📄 参照： references/filtering.md

• フィルタリング機能の基本
• フィルターの種類と述語
• プログラムによるフィルタリング
• カスタムのフィルタリングロジック
• フィルター UI のカスタマイズ

選択

📄 参照： references/selection.md

• 選択モード（単一、複数、なし）
• 選択イベント（onSelectionChanging、onSelectionChanged）
• プログラムによる選択
• 現在のセルと選択された行の違い

グループ化

📄 参照： references/grouping.md

• データのグループ化（単一列および複数列）
• グループの展開／折りたたみ動作
• カスタムのグループ化ロジック
• グループヘッダーのカスタマイズ

集計

📄 参照： references/summaries.md

• 集計行（グループ集計とキャプション集計）
• 組み込みの集計関数（Sum、Average、Count、Min、Max）
• カスタム集計計算
• 集計の表示形式
• 集計フッターの設定

ページング

📄 参照： references/paging.md

• ページングのセットアップと設定
• ページサイズとページ移動
• カスタムページング UI
• プログラムによるページ移動
• ページ変更イベント

さらに読み込む

📄 参照： references/load-more.md

• 増分読み込みのセットアップ
• 「さらに読み込む」行の処理
• 「さらに読み込む」のトリガーとイベント
• プログラムによる追加読み込みの制御
• 大規模データセットのページネーション戦略

引っ張って更新

📄 参照： references/pull-to-refresh.md

• 引っ張って更新するジェスチャー
• 更新イベントの処理
• カスタム更新 UI
• 読み込み状態の管理
• データ更新のパターン

行の高さのカスタマイズ

📄 参照： references/row-height-customization.md

• 行の高さの設定
• コンテンツに応じた行の高さの自動調整
• QueryRowHeight イベントの使用
• 動的な行の高さの調整
• ヘッダー行の高さのカスタマイズ

スワイプ

📄 参照： references/swiping.md

• 行をスワイプするジェスチャー
• スワイプ操作とコマンド
• スワイプイベントの処理
• カスタムスワイプ操作 UI
• スワイプ範囲の設定

スタイル

📄 参照： references/styles.md

• グリッドのスタイル設定の基本
• セルのスタイル設定（DataGridCellStyle）
• 条件付きセルのスタイル設定
• 行のスタイル設定と交互の行色
• ヘッダーのスタイル設定
• テーマのカスタマイズ

条件付きスタイル

📄 参照: references/conditional-styling.md

• セルや行のデータに基づくスタイルの適用
• 動的なスタイル設定ロジック
• スタイルビルダーとコールバック
• 条件付きスタイルのパフォーマンス最適化

プレースホルダー

📄 参照: references/placeholder.md

• 空の DataGrid の表示
• カスタムプレースホルダーウィジェット
• 読み込み状態の表示
• データがない場合のメッセージのカスタマイズ

Excel へのエクスポート

📄 参照: references/export-to-excel.md

• DataGrid の Excel へのエクスポート
• Excel エクスポートのカスタマイズ（列、行、スタイル）
• Excel エクスポートのオプションとイベント
• ファイルの保存と共有

PDF へのエクスポート

📄 参照: references/export-to-pdf.md

• DataGrid の PDF へのエクスポート
• PDF エクスポートのカスタマイズ
• ページの向きとサイズ
• PDF エクスポートのイベント
• ファイルの保存と共有

フッター

📄 参照: references/footer.md

• フッター行の設定
• フッターでの集計表示
• カスタムフッターコンテンツ
• フッターのスタイル設定

アクセシビリティ

📄 参照: references/accessibility.md

• キーボード操作
• スクリーンリーダーのサポート
• アクセシビリティのベストプラクティス

ローカライズ

📄 参照: references/localization.md

• ローカライズの設定
• 多言語サポート

右から左への表示

📄 参照: references/right-to-left.md

• RTL（右から左への表示）のサポート
• テキスト方向のカスタマイズ

クイックスタートの例

ステップ 1：パッケージを追加

# Always installs the latest compatible version automatically
flutter pub add syncfusion_flutter_datagrid

パッケージは必ずターミナルからインストールしてください。pubspec.yaml を直接編集しないでください。 このコマンドを Flutter プロジェクトのルートから実行し、正常に完了するまで待ってから次に進んでください。

ステップ 2：データモデルを作成

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

ステップ 3：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]),
      ),
    ]);
  }
}

ステップ 4：ビューに DataGrid を追加

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),
      ),
    ];
  }
}

主なプロパティと設定

プロパティ	型	説明
source	DataGridSource	グリッドのデータソース（必須）
columns	List	列の定義（必須）
rowHeight	double	デフォルトの行の高さ
headerRowHeight	double	ヘッダー行の高さ
allowSorting	bool	並べ替えを有効化
allowMultiColumnSorting	bool	複数列の並べ替えを有効化
allowFiltering	bool	フィルタリングを有効化
allowEditing	bool	セルの編集を有効化
navigationMode	GridNavigationMode	行またはセルのナビゲーション
selectionMode	SelectionMode	なし、単一、または複数
frozenColumnsCount	int	左側から固定する列の数
frozenRowsCount	int	上側から固定する行の数
columnWidthMode	ColumnWidthMode	自動、塗りつぶし、なし

よくあるパターン

パターン 1：複数列に対応した並べ替え

視覚的なインジケーターを使って、単一列および複数列の並べ替えを有効にします。

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

プログラムによる並べ替えを追加します。

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

パターン 2：プログラムと UI の両方に対応したフィルタリング

プログラムと UI によるフィルタリングの両方を有効にします。

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

パターン 3：カスタムキャプションと展開／折りたたみに対応したグループ化

階層データのグループ化と、展開／折りたたみ機能を実装します。

// 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,
)

プログラムによる展開／折りたたみ：

// Expand all groups
_dataGridController.expandAllGroup();

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

一般的なユースケース

ユースケース	主な機能	参照ファイル
基本的なデータ表示	データバインディング、列	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

トラブルシューティング

DataGrid にデータが表示されない場合：

• source に有効な DataGridSource が設定されていることを確認します
• columns が定義されていることを確認します
• DataGridSource のコンストラクターで buildDataGridRows() が呼び出されていることを確認します
• データモデルが空でないことを確認します

編集が機能しない場合：

• allowEditing=true を設定します
• navigationMode を GridNavigationMode.cell に設定します
• selectionMode を Single または Multiple に設定します
• 列の 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 と完全に一致することを確認します
• グループ化する列に null 以外の値が含まれていることを確認します
• 展開／折りたたみ UI を表示するには、allowExpandCollapseGroup=true を有効にします
• DataGridController と expandAllGroup() を使用して、グループ化が機能していることを確認します

複数列の並べ替えが機能しない場合：

• SfDataGrid で allowMultiColumnSorting=true を設定します
• Web／デスクトップでは、追加の並べ替え列を加えるために Ctrl キーを押しながら列ヘッダーをクリックします
• 複数の並べ替え項目が存在することを確認するため、sortedColumns リストを確認します
• プログラムで sortedColumns を変更した後に sort() を呼び出します

カスタムのグループ化ロジックが適用されない場合：

• DataGridSource の performGrouping() をオーバーライドします
• カスタムのグループキーを String として返します
• 正しくグループ化するため、このメソッドが null 以外の値を返すことを確認します

次のステップ

1. 基本設定については、references/getting-started.md から始めます
2. references/column-types.md を使用して列を設定します
3. 編集、並べ替え、フィルタリングを追加して操作性を高めます
4. ページングまたは仮想化を使用して、データサイズに合わせて最適化します
5. スタイル設定とテンプレートを使用して外観をカスタマイズします