syncfusion-winforms-datagrid

Syncfusion WinForms DataGrid の実装

列、フィルタリング、並べ替え、グループ化、編集、集計、エクスポート機能などを備えた、表形式データの表示と操作に強力なコントロールである Syncfusion Windows Forms DataGrid（SfDataGrid）コンポーネントを実装するための包括的なガイドです。

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

次のような場合に、このスキルを使用します。

• Windows Forms アプリケーションで表形式データを表示する
• 列（テキスト、数値、日付、チェックボックス、コンボボックスなど）を定義してカスタマイズする
• フィルタリング、並べ替え、グループ化などのデータ操作を実装する
• グリッド内編集と検証を有効にする
• データの集計値や集約結果を表示する
• 選択機能（単一、複数、行、セル）を実装する
• グリッドデータを Excel または PDF にエクスポートする
• データ値に基づいて条件付きスタイルを適用する
• 階層データでマスター詳細ビューを作成する
• グリッドでドラッグ＆ドロップ操作を有効にする
• グリッドのテキストやメッセージをローカライズする
• グリッドの状態をシリアル化および逆シリアル化する

コンポーネントの概要

Syncfusion WinForms DataGrid（SfDataGrid）は、高性能なデータグリッドコントロールで、次の機能を提供します。

• 列の管理：自動生成、手動定義、複数段ヘッダー、列の種類
• データ操作：フィルタリング（Excel 風の UI）、並べ替え、展開／折りたたみが可能なグループ化
• 編集：さまざまなモードと検証機能を備えたグリッド内編集
• 集計：グループ集計、テーブル集計、キャプション集計
• 選択：複数のモードによる行、セル、または任意の選択
• エクスポート：カスタマイズ可能な Excel および PDF エクスポート
• スタイル設定：条件付きスタイル、カスタムセル描画
• 高度な機能：マスター詳細ビュー、ドラッグ＆ドロップ、ローカライズ、シリアル化

DataGrid コントロールの作成

SfDataGrid コントロールをプログラムで作成します。

using Syncfusion.WinForms.DataGrid;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private SfDataGrid sfDataGrid1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create SfDataGrid instance
            sfDataGrid1 = new SfDataGrid();
            
            // Add to form's controls collection
            this.Controls.Add(sfDataGrid1);
        }
    }
}

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

はじめに

📄 参照： references/getting-started.md

次のような場合に参照します。

• SfDataGrid コントロールを初めてセットアップする
• アセンブリの配置と NuGet パッケージのインストールについて理解する
• デザイナーまたはコードでコントロールを作成する
• データモデルとコレクションを作成する
• グリッドにデータをバインドする
• 自動生成または手動定義の列を構成する
• TableControl イベント（KeyDown、MouseDown）を処理する
• 基本機能（並べ替え、フィルタリング、グループ化、編集）を有効にする
• 完全な動作例を確認する

列の管理

📄 参照： references/columns.md

次のような場合に参照します。

• 列を定義する（自動生成と手動定義）
• さまざまな列の種類（GridTextColumn、GridNumericColumn、GridDateTimeColumn、GridCheckBoxColumn、GridComboBoxColumn など）を使用する
• 自動生成された列をカスタマイズする、または Data Annotations を使用する
• プログラムで列を追加、削除、または並べ替える
• 複数の列にまたがる複数段ヘッダーを作成する
• 列を非表示、表示、またはサイズ変更する
• 並べ替え用の列のドラッグ＆ドロップを有効にする

データの編集

📄 参照： references/editing.md

次のような場合に参照します。

• グリッド全体または特定の列の編集を有効または無効にする
• 編集モード（シングルクリック、ダブルクリック、F2 キー）を構成する
• 編集イベント（編集開始、編集終了、値変更）を処理する
• 編集中の検証を実装する
• プログラムで編集を開始、終了、またはキャンセルする
• 編集モードでのカーソル位置をカスタマイズする
• プログラムでセルの値を変更する

フィルタリング

📄 参照： references/filtering.md

次のような場合に参照します。

• プログラムによるフィルタリング（ビューのフィルタリング、列のフィルタリング）を実装する
• ユーザー向けの Excel 風フィルター UI を有効にする
• さまざまなフィルターの種類（文字列、数値、日付）を適用する
• 複数の条件を含むフィルター述語を使用する
• フィルターイベントを処理する
• 既存のフィルターをクリアまたは変更する
• フィルタリングの問題をトラブルシューティングする

並べ替え

📄 参照： references/sorting.md

以下が必要な場合：

• クリック操作による UI の並べ替えを有効にする
• プログラムから並べ替えを適用する（単一列または複数列）
• カスタムの並べ替え比較関数を実装する
• 並べ替えイベントを処理する
• 3 状態の並べ替えを設定する
• 既存の並べ替えを解除または変更する
• 並べ替えの問題をトラブルシューティングする

グループ化

📄 参照： references/grouping.md

以下が必要な場合：

• ドラッグ＆ドロップによる UI のグループ化を有効にする
• プログラムからデータをグループ化する（単一レベルまたは複数レベル）
• グループのキャプションと書式をカスタマイズする
• グループを展開／折りたたむ
• KeySelector を使ったカスタムのグループ化ロジックを実装する
• グループイベントを処理する
• グループ化の問題をトラブルシューティングする

選択

📄 参照： references/selection.md

以下が必要な場合：

• 選択モード（単一、複数、拡張）を設定する
• 選択単位（行、セル、任意）を設定する
• プログラムから行、列、セルを選択する
• 選択変更イベントを処理する
• CheckBox ベースの選択を実装する
• 特定の行または列の選択を無効にする
• 現在のセルと選択された項目を操作する

データ集計

📄 参照： references/summaries.md

以下が必要な場合：

• グループ集計（合計、平均、件数、最小値、最大値）を表示する
• テーブル集計を上部または下部に追加する
• 集計行と書式をカスタマイズする
• グループのキャプション集計を作成する
• カスタムの集計関数を実装する
• 集計行の位置とスタイルを設定する

Excel と PDF へのエクスポート

📄 参照： references/export.md

以下が必要な場合：

• グリッドデータを Excel または PDF にエクスポートする
• エクスポート時の外観と書式をカスタマイズする
• 選択した行またはフィルター処理されたデータをエクスポートする
• エクスポートに含める、または除外する列を指定する
• カスタマイズのためにエクスポートイベントを処理する
• スタイルとテーマを適用してエクスポートする
• PDF エクスポートのページ設定を構成する

条件付きスタイル設定とカスタム描画

📄 参照： references/styling.md

以下が必要な場合：

• セルの値または行データに基づいて条件付きスタイルを適用する
• セル、行、列の外観をカスタマイズする
• カスタム描画のために DrawCell イベントを処理する
• テーマとビジュアルスタイルを適用する
• セルの種類ごとに異なるスタイルを適用する
• 行の背景色を交互に設定する
• カスタムセルレンダラーを作成する

高度な機能

📄 参照： references/advanced-features.md

以下が必要な場合：

• 階層データを使ったマスター詳細ビューを実装する
• ドラッグ＆ドロップ操作（行、列）を有効にする
• 異なるカルチャ向けにグリッドのテキストとメッセージをローカライズする
• グリッドの状態（列、並べ替え、グループ化、フィルタリング）をシリアライズおよびデシリアライズする
• グリッドの設定と環境設定を構成する
• 複雑な階層データ構造を処理する

クイックスタートの例

以下は、WinForms DataGrid アプリケーションをゼロから作成するための、手順を追った完全な例です。

ステップ 1：データモデルクラスを作成する

まず、データを表すクラスを作成します。

using System;
using System.Collections.ObjectModel;

public class OrderInfo
{
    public int OrderID { get; set; }
    public string CustomerID { get; set; }
    public string CustomerName { get; set; }
    public string Country { get; set; }
    public string ShipCity { get; set; }
    
    public OrderInfo(int orderId, string customerName, string country, string customerId, string shipCity)
    {
        this.OrderID = orderId;
        this.CustomerName = customerName;
        this.Country = country;
        this.CustomerID = customerId;
        this.ShipCity = shipCity;
    }
}

public class OrderInfoCollection
{
    private ObservableCollection<OrderInfo> _orders;
    
    public ObservableCollection<OrderInfo> Orders
    {
        get { return _orders; }
        set { _orders = value; }
    }
    
    public OrderInfoCollection()
    {
        _orders = new ObservableCollection<OrderInfo>();
        GenerateOrders();
    }
    
    private void GenerateOrders()
    {
        _orders.Add(new OrderInfo(1001, "Maria Anders", "Germany", "ALFKI", "Berlin"));
        _orders.Add(new OrderInfo(1002, "Ana Trujilo", "Mexico", "ANATR", "Mexico D.F."));
        _orders.Add(new OrderInfo(1003, "Antonio Moreno", "Mexico", "ANTON", "Mexico D.F."));
        _orders.Add(new OrderInfo(1004, "Thomas Hardy", "UK", "AROUT", "London"));
        _orders.Add(new OrderInfo(1005, "Christina Berglund", "Sweden", "BERGS", "Lula"));
        _orders.Add(new OrderInfo(1006, "Hanna Moos", "Germany", "BLAUS", "Mannheim"));
        _orders.Add(new OrderInfo(1007, "Frederique Citeaux", "France", "BLONP", "Strasbourg"));
        _orders.Add(new OrderInfo(1008, "Martin Sommer", "Spain", "BOLID", "Madrid"));
        _orders.Add(new OrderInfo(1009, "Laurence Lebihan", "France", "BONAP", "Marseille"));
        _orders.Add(new OrderInfo(1010, "Elizabeth Lincoln", "Canada", "BOTTM", "Tsawassen"));
    }
}

ステップ 2：フォームに DataGrid を作成して構成する

using System;
using System.Windows.Forms;
using Syncfusion.WinForms.DataGrid;
using Syncfusion.WinForms.DataGrid.Enums;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private SfDataGrid sfDataGrid1;
        
        public Form1()
        {
            InitializeComponent();
            InitializeDataGrid();
        }
        
        private void InitializeDataGrid()
        {
            // Create DataGrid instance
            sfDataGrid1 = new SfDataGrid();
            sfDataGrid1.Dock = DockStyle.Fill;
            
            // Create and bind data source
            OrderInfoCollection collection = new OrderInfoCollection();
            sfDataGrid1.DataSource = collection.Orders;
            
            // Enable features
            sfDataGrid1.AllowEditing = true;
            sfDataGrid1.AllowFiltering = true;
            sfDataGrid1.AllowSorting = true;
            sfDataGrid1.AllowGrouping = true;
            sfDataGrid1.ShowGroupDropArea = true;
            
            // Configure selection
            sfDataGrid1.SelectionMode = GridSelectionMode.Extended;
            
            // Auto-generate columns from data model
            sfDataGrid1.AutoGenerateColumns = true;
            
            // Add to form
            this.Controls.Add(sfDataGrid1);
        }
    }
}

ステップ 3：列を手動で定義する（任意）

自動生成ではなく、列を完全に制御したい場合：

private void InitializeDataGrid()
{
    sfDataGrid1 = new SfDataGrid();
    sfDataGrid1.Dock = DockStyle.Fill;
    
    // Disable auto-generation to define columns manually
    sfDataGrid1.AutoGenerateColumns = false;
    
    // Add columns with specific properties
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "OrderID", 
        HeaderText = "Order ID",
        Width = 100,
        AllowEditing = false // Make this column read-only
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "CustomerID", 
        HeaderText = "Customer ID",
        Width = 120
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "CustomerName", 
        HeaderText = "Customer Name",
        Width = 150
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "Country", 
        HeaderText = "Country",
        Width = 120
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "ShipCity", 
        HeaderText = "Ship City",
        Width = 120
    });
    
    // Bind data source
    OrderInfoCollection collection = new OrderInfoCollection();
    sfDataGrid1.DataSource = collection.Orders;
    
    // Enable features
    sfDataGrid1.AllowSorting = true;
    sfDataGrid1.AllowFiltering = true;
    sfDataGrid1.AllowGrouping = true;
    sfDataGrid1.ShowGroupDropArea = true;
    
    // Add to form
    this.Controls.Add(sfDataGrid1);
}

表示される内容

アプリケーションを実行すると：

• 顧客情報を含む 10 件の注文を表示するデータグリッド
• 列ヘッダーをクリックして並べ替え
• フィルターアイコンをクリックしてデータをフィルター
• 列ヘッダーをドロップ領域にドラッグして、その列でグループ化
• セルをダブルクリックして編集（AllowEditing が true の場合）
• Ctrl／Shift キーによる複数選択に対応

基本的なデータ操作

さまざまなデータソースのバインド

DataGrid はさまざまな種類のデータソースに対応しています。

// Bind to ObservableCollection (recommended for automatic UI updates)
ObservableCollection<OrderInfo> orders = new ObservableCollection<OrderInfo>();
sfDataGrid1.DataSource = orders;

// Bind to List
List<OrderInfo> orderList = new List<OrderInfo>();
sfDataGrid1.DataSource = orderList;

// Bind to DataTable
DataTable dataTable = new DataTable();
sfDataGrid1.DataSource = dataTable;

// Bind to BindingList
BindingList<OrderInfo> bindingList = new BindingList<OrderInfo>();
sfDataGrid1.DataSource = bindingList;

選択イベントの処理

// Handle selection changed
sfDataGrid1.SelectionChanged += (sender, e) =>
{
    if (sfDataGrid1.SelectedItem != null)
    {
        var selectedOrder = sfDataGrid1.SelectedItem as OrderInfo;
        Console.WriteLine($"Selected: {selectedOrder.CustomerName}");
    }
};


## Common Patterns

### Manual Column Definition with Selection

```csharp
sfDataGrid.AutoGenerateColumns = false;

// Add columns
sfDataGrid.Columns.Add(new GridTextColumn() 
{ 
    MappingName = "OrderID", 
    HeaderText = "Order ID",
    AllowEditing = false 
});

sfDataGrid.Columns.Add(new GridNumericColumn() 
{ 
    MappingName = "Quantity", 
    HeaderText = "Qty"
});

// Configure selection
sfDataGrid.SelectionMode = GridSelectionMode.Multiple;
sfDataGrid.SelectionUnit = SelectionUnit.Row;

主なプロパティ

グリッドの主なプロパティ

• DataSource - バインドするデータソース
• AutoGenerateColumns - 列の自動生成を有効または無効にします
• AllowEditing - 編集を有効または無効にします
• AllowFiltering - フィルタリングを有効または無効にします
• AllowSorting - 並べ替えを有効または無効にします
• AllowGrouping - グループ化を有効または無効にします
• AllowDraggingColumns - 列の並べ替えを有効または無効にします
• AllowDraggingRows - 行の並べ替えを有効または無効にします

選択プロパティ

• SelectionMode - 単一、複数、拡張、なし
• SelectionUnit - 行、セル、任意
• SelectedItem - 選択した項目を取得または設定します
• SelectedItems - 複数の選択項目を取得または設定します

外観プロパティ

• HeaderRowHeight - ヘッダー行の高さ
• RowHeight - 既定の行の高さ
• Style - グリッドのスタイル設定
• ShowGroupDropArea - グループ化ドロップ領域を表示または非表示にします
• ShowRowHeader - 行ヘッダーを表示または非表示にします

一般的なユースケース

ユースケース 1：E コマースの注文管理

注文を表示し、ステータスによるフィルタリング、日付による並べ替え、顧客によるグループ化、更新のための編集、優先度の高い注文に対する条件付きスタイル設定を行います。

ユースケース 2：財務レポート

集計（合計、平均値）を含む取引データを表示し、Excel/PDF へのエクスポート、負の値に対する条件付きスタイル設定、取引の詳細を表示するマスター・ディテール機能を利用します。

ユースケース 3：在庫管理

カテゴリによるフィルタリング、在庫不足に対する条件付きスタイル設定、数量更新のための編集、一括操作のための選択機能を使って商品を管理します。

ユースケース 4：顧客関係管理

複数列での並べ替え、地域によるグループ化、エクスポート機能、ステータス表示のカスタム描画を利用して連絡先を管理します。

ユースケース 5：プロジェクト管理

サブタスクを表示するマスター・ディテール機能、並べ替えのためのドラッグ＆ドロップ、ステータスに応じた条件付きスタイル設定、進捗を追跡する集計を使ってタスクを表示します。

トラブルシューティング

一般的な問題と解決方法については、以下をご覧ください。

• 列が表示されない：MappingName がプロパティ名と完全に一致していることを確認してください（大文字と小文字を区別します）。
• 編集できない：グリッドレベルと列レベルの両方で、AllowEditing プロパティを確認してください。
• フィルターが適用されない：AllowFiltering が有効になっていることを確認し、プログラムによる変更後に RefreshFilter() を呼び出してください。
• エクスポートの書式に関する問題：エクスポートオプションをカスタマイズし、エクスポートイベントを処理してください。
• スタイルが表示されない：DrawCell イベントが設定され、Style プロパティが正しく設定されていることを確認してください。
• 選択できない：SelectionMode と SelectionUnit が正しく設定されていることを確認してください。

各機能領域の詳しいトラブルシューティングについては、上記の該当するリファレンスファイルを参照してください。

---

次のステップ

まず Getting Started で SfDataGrid をインストールして設定し、アプリケーションの要件に応じて、上記のナビゲーションガイドから各機能を確認してください。