syncfusion-winui-datagrid

WinUI DataGrid（SfDataGrid）の実装

Syncfusion WinUI DataGrid コントロールを実装するための包括的なガイドです。SfDataGrid は、WinUI 3 アプリケーションで表形式データを表示および操作するための高性能で機能豊富なコントロールで、並べ替え、フィルタリング、グループ化、編集、集計などをサポートします。

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

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

• WinUI アプリケーションで 100～1,000,000 行以上の表形式データを表示する
• 並べ替え、フィルタリング、グループ化が可能なデータビューを実装する
• データ入力シナリオ向けに、検証機能を備えたインライン編集を有効にする
• データセットに対して CRUD（作成、読み取り、更新、削除）操作を実行する
• データを Excel 形式でエクスポートする
• マスターディテールビューで階層データを表示する
• ドラッグアンドドロップによる行の並べ替えを実装する
• データの集計値（合計、平均、件数など）を表示する
• ObservableCollection を使用してリアルタイムのデータ更新を処理する
• データ中心のエンタープライズ向け Windows デスクトップアプリケーションを作成する

重要な注意事項： WinUI 3 では、DataContext は Window から直接継承されません。データバインディングが正しく機能するように、XAML で Grid または Page 要素に DataContext を明示的に設定する必要があります（例：<Grid DataContext="{x:Bind ViewModel}">）。

DataGrid の概要

SfDataGrid（Syncfusion.UI.Xaml.DataGrid.SfDataGrid）は、WinUI 3 の主要なグリッドコントロールで、次の機能を備えています。

• 高パフォーマンス： 数百万行に対応する UI とデータの仮想化
• 豊富なデータ操作： 複数レベルに対応した並べ替え、フィルタリング、グループ化
• 編集： 検証機能を備えたセル／行／一括編集モード
• 集計： カスタム集計を使用したテーブル、グループ、キャプションの集計
• 選択： 単一／複数行またはセルの選択
• スタイル設定： 条件付き書式設定とカスタムテンプレート
• エクスポート： スタイルを適用した Excel エクスポート
• 高度な機能： 非バインド行、マスターディテール、固定列

必須パッケージ：

• メインパッケージ： Syncfusion.Grid.WinUI（DataGrid コントロール）
• エクスポートパッケージ： Syncfusion.GridExport.WinUI（Excel エクスポート機能）
• Excel エンジン： Syncfusion.XlsIO.NET（エクスポート操作に必須）

名前空間： Syncfusion.UI.Xaml.DataGrid

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

はじめに

📄 参照： references/getting-started.md

• データバインディングの基本（IEnumerable、ObservableCollection、動的オブジェクト）
• ItemsSource の設定と INotifyCollectionChanged
• 複雑なプロパティのバインディング（ネストされたオブジェクト）
• 基本的な XAML の設定と最初の実装
• パッケージのインストールと名前空間の登録

列の管理

📄 参照： references/columns.md

• 列の種類（GridTextColumn、GridNumericColumn、GridCheckBoxColumn、GridComboBoxColumn など）
• 列の自動生成と手動定義
• 列幅モード（Auto、Star、None、Fill、AutoLastColumnFill）
• 列のサイズ設定、自動サイズ調整、サイズ変更
• 列の表示／非表示と表示状態
• 列の並べ替えと固定

データ操作（並べ替え、フィルタリング、グループ化）

📄 参照： references/data-operations.md

• 並べ替え：単一列および複数列の並べ替え、カスタム並べ替え、3 状態の並べ替え
• フィルタリング：プログラムによるフィルター、ビュー述語、列フィルター、フィルター行
• グループ化：単一レベルおよび複数レベルのグループ化、カスタムグループ化、展開／折りたたみ
• グループ集計とフィルター行の設定

編集とデータ検証

📄 参照： references/editing-validation.md

• 編集モード：セル、行、一括編集
• 編集の開始方法（シングルクリック、ダブルクリック、F2 キー）
• データ検証ルールとエラー処理
• CRUD 操作：行の追加、更新、削除
• 変更の確定とキャンセル
• CurrentCell のナビゲーション

選択

📄 参照： references/selection.md

• 選択モード：Single、Multiple、Extended、None
• 選択単位：行とセル
• SelectedItem、SelectedItems、SelectedIndex のバインディング
• プログラムによる選択と SelectionChanged イベント
• すべての行の選択、範囲の選択

集計と集約

📄 参照： references/summaries.md

• テーブル集計（フッターに表示）
• グループ集計（グループごと）
• キャプション集計（グループヘッダー内）
• 組み込みの集計関数（Sum、Average、Count、Min、Max）
• カスタム集計計算
• 集計行の位置

条件付きスタイル設定

📄 参照： references/conditional-styling.md

• データ条件に基づく行のスタイル設定
• セルのスタイル設定とカスタムテンプレート
• 動的なスタイル設定のためのスタイルセレクター
• 表示状態とデータテンプレート
• 行の交互の色

高度な行機能

📄 参照： references/row-features.md

• 行のドラッグ＆ドロップによる並べ替え
• 非連結行（データ行の上と下）
• 階層データ向けのマスターディテールビュー
• 行の高さのカスタマイズ
• 詳細ビューのテンプレートとネストされたグリッド

データ仮想化

📄 参照： references/virtualization.md

• 大規模データセット向けのデータ仮想化
• UI 仮想化（デフォルトで有効）
• 仮想モードの設定
• パフォーマンス最適化の手法
• 100,000 行を超えるデータを効率的に処理

Excel へのエクスポート

📄 参照： references/export.md

• グリッド全体を Excel（.xlsx）にエクスポート
• エクスポートのオプションとカスタマイズ
• 選択した行のみをエクスポート
• スタイルと書式を保持してエクスポート
• カスタムエクスポートロジック

クイックスタートの例

基本的な実装

<Page xmlns:dataGrid="using:Syncfusion.UI.Xaml.DataGrid">
    
    <Grid>
        <dataGrid:SfDataGrid x:Name="sfDataGrid"
                             ItemsSource="{Binding Orders}"
                             AutoGenerateColumns="True"
                             AllowSorting="True"
                             AllowFiltering="True"
                             AllowEditing="True"
                             SelectionMode="Single" />
    </Grid>
</Page>

// MainPage.xaml.cs
using Microsoft.UI.Xaml.Controls;
using System.Collections.ObjectModel;

public sealed partial class MainPage : Page
{
    public ObservableCollection<Order> Orders { get; set; }
    
    public MainPage()
    {
        this.InitializeComponent();
        
        Orders = new ObservableCollection<Order>
        {
            new Order { OrderID = 1001, CustomerName = "Maria Anders", Country = "Germany", Total = 250.50M },
            new Order { OrderID = 1002, CustomerName = "Ana Trujillo", Country = "Mexico", Total = 180.00M },
            new Order { OrderID = 1003, CustomerName = "Antonio Moreno", Country = "Mexico", Total = 420.75M }
        };
        
        sfDataGrid.ItemsSource = Orders;
    }
}

// Order Model
public class Order
{
    public int OrderID { get; set; }
    public string CustomerName { get; set; }
    public string Country { get; set; }
    public decimal Total { get; set; }
}

一般的なパターン

パターン 1：列を手動で定義する

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     AutoGenerateColumns="False"
                     ItemsSource="{Binding Orders}">
    <dataGrid:SfDataGrid.Columns>
        <dataGrid:GridTextColumn MappingName="OrderID" 
                                 HeaderText="Order ID" 
                                 Width="120" />
        <dataGrid:GridTextColumn MappingName="CustomerName" 
                                 HeaderText="Customer" 
                                 Width="200" />
        <dataGrid:GridTextColumn MappingName="Country" 
                                 Width="150" />
        <dataGrid:GridNumericColumn MappingName="Total" 
                                    HeaderText="Total Amount"
                                    Width="150" />
    </dataGrid:SfDataGrid.Columns>
</dataGrid:SfDataGrid>

パターン 2：並べ替えとフィルタリングを有効にする

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowSorting="True"
                     AllowFiltering="True"
                     FilterRowPosition="FixedTop"
                     AllowTriStateSorting="True" />

パターン 3：グループ化を有効にする

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowGrouping="True"
                     ShowGroupDropArea="True" />

// Programmatic grouping
sfDataGrid.GroupColumnDescriptions.Add(new GroupColumnDescription { ColumnName = "Country" });

パターン 4：編集を有効にする

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowEditing="True"
                     EditTrigger="OnDoubleTap"
                     NavigationMode="Cell" />

パターン 5：集計を追加する

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     ShowRowHeader="True">
    <dataGrid:SfDataGrid.TableSummaryRows>
        <dataGrid:GridTableSummaryRow ShowSummaryInRow="False">
            <dataGrid:GridTableSummaryRow.SummaryColumns>
                <dataGrid:GridSummaryColumn Name="TotalSum"
                                            MappingName="Total"
                                            SummaryType="DoubleAggregate"
                                            Format="'Total: {Sum:C}'" />
                <dataGrid:GridSummaryColumn Name="OrderCount"
                                            MappingName="OrderID"
                                            SummaryType="CountAggregate"
                                            Format="'Count: {Count}'" />
            </dataGrid:GridTableSummaryRow.SummaryColumns>
        </dataGrid:GridTableSummaryRow>
    </dataGrid:SfDataGrid.TableSummaryRows>
</dataGrid:SfDataGrid>

主要なプロパティ

プロパティ	型	説明
ItemsSource	object	グリッドのデータソース（IEnumerable）
AutoGenerateColumns	bool	データソースのプロパティから列を自動生成します
Columns	Columns	手動で定義した列のコレクション
AllowSorting	bool	並べ替えを有効または無効にします（デフォルト：false）
AllowFiltering	bool	フィルタリングを有効または無効にします（デフォルト：false）
AllowGrouping	bool	グループ化を有効または無効にします（デフォルト：false）
AllowEditing	bool	編集を有効または無効にします（デフォルト：false）
SelectionMode	GridSelectionMode	Single、Multiple、Extended、None
SelectionUnit	GridSelectionUnit	行またはセル
NavigationMode	NavigationMode	セルまたは行のナビゲーション
ColumnWidthMode	ColumnWidthMode	None、Star、Auto、SizeToCells、SizeToHeader、AutoLastColumnFill、AutoWithLastColumnFill
ShowGroupDropArea	bool	グループ化用のドラッグ＆ドロップ領域を表示します
FilterRowPosition	FilterRowPosition	FixedTop、Top、Bottom

一般的なユースケース

エンタープライズ向けデータ入力アプリケーション

• 編集、検証、CRUD 操作を有効にする
• 効率化のために一括編集モードを使用する
• 一括操作のために SelectedItems バインディングを実装する
• データの分析に役立つテーブル集計を追加する

データ分析ダッシュボード

• 並べ替え、フィルタリング、グループ化を有効にする
• テーブルとグループの各レベルに集計を追加する
• 条件付きスタイル設定を使用して重要なデータを強調する
• レポート作成のために Excel へのエクスポートを実装する

マスターディテール形式のデータビューアー

• ネストされたデータ向けに DetailsViewDefinition を設定する
• 階層データバインディングを使用する
• 詳細の展開と折りたたみを有効にする
• マスター行と詳細行に異なるスタイルを適用する

大規模データセットブラウザー（100K 行以上）

• データ仮想化を有効にする
• 不要な機能（グループ化、集計）を無効にする
• 重要なデータには列の固定を使用する
• 段階的な読み込みを実装する

トランザクション管理システム

• 行のドラッグ＆ドロップによる優先順位付けを有効にします
• 合計や概要情報には、データにバインドされていない行を使用します
• ObservableCollection を使用して、リアルタイム更新を実装します
• データの整合性を保つための検証ルールを追加します

MVVM との統合

// ViewModel
public class OrderViewModel : INotifyPropertyChanged
{
    private ObservableCollection<Order> orders;
    private Order selectedOrder;
    
    public ObservableCollection<Order> Orders
    {
        get => orders;
        set { orders = value; OnPropertyChanged(); }
    }
    
    public Order SelectedOrder
    {
        get => selectedOrder;
        set { selectedOrder = value; OnPropertyChanged(); }
    }
    
    public ICommand DeleteCommand { get; }
    public ICommand ExportCommand { get; }
}

<dataGrid:SfDataGrid ItemsSource="{Binding Orders}"
                     SelectedItem="{Binding SelectedOrder, Mode=TwoWay}" />

パフォーマンスに関するヒント

1. 自動的な UI 更新には List ではなく ObservableCollection を使用します
2. 可能な場合は AutoGenerateColumns="False" を設定し、列を手動で定義します
3. 仮想化を有効にします（デフォルトで有効です。必要がない限り無効にしないでください）
4. 重要な列を固定して、横スクロールのパフォーマンスを向上させます
5. データサイズがわかっている場合は、固定列幅に ColumnWidthMode="None" を使用します
6. パフォーマンスを向上させるため、グループ化の階層は 2～3 段階に制限します
7. 非常に大きなデータセット（100K 以上）では、グループ化ではなくフィルタリングを使用します
8. Page.Unloaded イベントでグリッドを破棄します

トラブルシューティング

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

• ItemsSource が正しくバインドされていることを確認します
• プロパティにパブリックなゲッターがあることを確認します
• バインディングを使用している場合は、DataContext が設定されていることを確認します

編集が機能しない場合：

• AllowEditing="True" を設定します
• NavigationMode="Cell" を設定します
• 列の AllowEditing="True" を確認します（未設定の場合はグリッドから継承されます）

大きなデータセットでパフォーマンスが低下する場合：

• 仮想化が有効になっていることを確認します（デフォルトで有効です）
• 列数を減らします
• Auto の代わりに ColumnWidthMode="None" を使用します
• 500K 以上の行では、データのページネーションを検討します

並べ替え／フィルタリングが機能しない場合：

• AllowSorting="True"、または AllowFiltering="True" を設定します
• データソースが IEnumerable を実装していることを確認します
• 列ごとにこれらが無効化されていないか確認します

関連コンポーネント

• TreeGrid： 階層ツリーデータ用
• PivotGrid： OLAP およびピボットテーブルのシナリオ用
• PropertyGrid： オブジェクトのプロパティ編集用