syncfusion-winforms-listview

ListView の実装

Syncfusion® Windows Forms ListView（SfListView）の実装ガイドです。データバインディング、グループ化、並べ替え、フィルタリング、選択モード、チェックボックスによる選択、幅広いカスタマイズオプションを備えた、高性能なリストコントロールです。

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

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

• リストビューを作成する：Windows Forms アプリケーションでコレクションにデータバインディングする
• 項目のコレクションを表示する：グループ化、並べ替え、フィルタリング機能を使用する
• 項目の選択を実装する：単一選択または複数選択モードを使用する
• チェックボックスによる選択を追加する：複数項目に対する操作を実行する
• 検索可能なリストを構築する：フィルタリングと並べ替えを使用する
• グループ化されたリストを作成する：展開・折りたたみ可能なグループを使用する
• 項目の外観をカスタマイズする：テンプレート、スタイル、テーマを使用する
• アクセシビリティをサポートする：UIAutomation とキーボードナビゲーションを使用する
• データ駆動型 UI を構築する：ファイルエクスプローラー、連絡先リスト、商品カタログのような UI を作成する
• 大規模なデータセットを処理する：最適化されたビューの再利用を使用する

このスキルでは、セットアップ、データバインディング、選択、データ操作、カスタマイズ、高度な機能を含む、ListView の実装全般を解説します。

コンポーネントの概要

SfListView コントロールは、次の機能を提供する高性能なリストビューコントロールです。

• データバインディング - IEnumerable データソースをサポートし、自動的に更新します
• 選択モード - イベントに対応した、単一、複数、または選択なしのモード
• チェックボックスによる選択 - チェックボックスによる複数選択、すべて選択、再帰的なチェック
• グループ化 - 項目をプロパティで整理し、グループを展開できます
• 並べ替え - カスタム比較子を使用した昇順・降順の並べ替え
• フィルタリング - 条件に基づいて項目をフィルタリングし、リアルタイムで更新します
• 項目サイズ - 項目の高さを自動調整するか、固定します
• カスタマイズ - スタイル、テンプレート、テーマ（Office 2016）
• ヘッダー／フッター - カスタムのヘッダーおよびフッタービュー
• スクロールバーのカスタマイズ - 外観と動作を調整します
• ローカライズ - 多言語に対応します
• アクセシビリティ - スクリーンリーダー向けの UIAutomation をサポートします

コントロールの構造

SfListView
├── Header View (optional) - Top content area
├── Groups - Collapsible item groups
│   ├── Group Header - Group title and expand/collapse
│   └── Items - Data items in group
├── Items - Flat list of data-bound items
└── Footer View (optional) - Bottom content area

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と依存関係
• デザイナーとコードによる SfListView の追加
• データオブジェクトクラスの作成
• DataSource を使用した基本的なデータバインディング
• 最初のリストビューの例

データバインディング

📄 参照： references/data-binding.md

• IEnumerable データソースへのバインド
• DataSource プロパティの設定
• DisplayMember と ValueMember
• ライブ更新のための ObservableCollection
• プログラムによるデータの更新
• データソースの変更処理

選択

📄 参照： references/selection.md

• SelectionMode（None、One、MultiSimple、MultiExtended）

• SelectedItem プロパティと SelectedItems プロパティ

• SelectedIndex と SelectedIndices

• SelectionChanged イベント

• プログラムによる選択

• 選択時の外観のカスタマイズ

• 📄 参照： references/checkbox-selection.md

• CheckBoxSelectionMode プロパティ

• CheckedItems コレクション

• CheckedIndices プロパティ

• ItemChecking イベントと ItemChecked イベント

• すべて選択する機能

• グループ化されたリストでの再帰的なチェック

• チェックボックスの外観のカスタマイズ

データ操作

📄 参照： references/data-operations.md

• プロパティによる項目のグループ化
• GroupDescriptor の設定
• 項目の並べ替え（昇順、降順）
• カスタムの並べ替え比較子
• 述語によるフィルタリング
• フィルター条件と規則
• リアルタイム更新のための LiveDataUpdateMode

カスタマイズ

📄 参照： references/appearance.md

• スタイルプロパティのカスタマイズ
• ItemStyle と GroupHeaderStyle
• テーマのサポート（Office 2016 など）
• 色、フォント、境界線
• カスタム描画のための DrawItem イベント
• 選択色とフォーカスインジケーター

📄 参照： references/item-sizing-headers.md

• ItemHeight プロパティ
• GroupHeaderHeight プロパティ
• AutoFitMode（Height、DynamicHeight）
• ヘッダービューのカスタマイズ
• フッタービューのカスタマイズ
• 動的な高さの計算

高度な機能

📄 参照： references/advanced-features.md

• ローカライズとカルチャのサポート
• アクセシビリティのための UIAutomation
• スクロールバーのカスタマイズ
• パフォーマンス最適化の手法
• ビューの再利用戦略
• メモリ管理

クイックスタートの例

データバインディングを使った基本的な ListView

using System;
using System.Collections.Generic;
using System.Windows.Forms;
using Syncfusion.WinForms.ListView;

namespace ListViewDemo
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            InitializeListView();
        }
        
        private void InitializeListView()
        {
            // Create and configure ListView
            SfListView listView = new SfListView();
            listView.Dock = DockStyle.Fill;
            listView.Size = new Size(400, 500);
            
            // Set data source
            listView.DataSource = GetCountryData();
            listView.DisplayMember = "CountryName";
            
            // Enable selection
            listView.SelectionMode = Syncfusion.WinForms.ListView.Enums.SelectionMode.One;
            listView.SelectionChanged += ListView_SelectionChanged;
            
            // Add to form
            this.Controls.Add(listView);
        }
        
        private List<CountryInfo> GetCountryData()
        {
            return new List<CountryInfo>
            {
                new CountryInfo { CountryName = "United States", Continent = "North America" },
                new CountryInfo { CountryName = "Canada", Continent = "North America" },
                new CountryInfo { CountryName = "Germany", Continent = "Europe" },
                new CountryInfo { CountryName = "Japan", Continent = "Asia" },
                new CountryInfo { CountryName = "Australia", Continent = "Oceania" }
            };
        }
        
        private void ListView_SelectionChanged(object sender, EventArgs e)
        {
            if (sender is SfListView listView && listView.SelectedItem != null)
            {
                var selected = listView.SelectedItem as CountryInfo;
                MessageBox.Show($"Selected: {selected.CountryName}");
            }
        }
    }
    
    public class CountryInfo
    {
        public string CountryName { get; set; }
        public string Continent { get; set; }
    }
}

よく使われるパターン

パターン 1：グループ化および並べ替え済みのリスト

// Create ListView
SfListView listView = new SfListView();
listView.DataSource = GetCountryData();
listView.DisplayMember = "CountryName";

// Add grouping by continent
listView.View.GroupDescriptors.Add(new GroupDescriptor()
{
    PropertyName = "Continent"
});

// Add sorting by country name
listView.View.SortDescriptors.Add(new SortDescriptor()
{
    PropertyName = "CountryName",
    Direction = Syncfusion.Data.ListSortDirection.Ascending
});

パターン 2：すべて選択機能付きのチェックボックス選択

// Enable checkbox mode
listView.CheckBoxMode = CheckBoxMode.Default;

// Handle checked items changes
listView.CheckStateChanged += (s, e) =>
{
    MessageBox.Show($"Checked items: {listView.CheckedItems.Count}");
};

// Add Select All button
Button selectAllBtn = new Button { Text = "Select All" };
selectAllBtn.Click += (s, e) =>
{
    // Check all items
    for (int i = 0; i < listView.View.Items.Count; i++)
    {
        listView.SetItemCheckState(i, CheckState.Checked);
    }
};

パターン 3：フィルターおよび検索に対応したリスト

// Add TextBox for search
TextBox searchBox = new TextBox();
searchBox.TextChanged += (s, e) =>
{
    string searchText = searchBox.Text.ToLower();
    
    // Apply filter
    listView.View.Filter = item =>
    {
        if (item is CountryInfo country)
        {
            return country.CountryName.ToLower().Contains(searchText);
        }
        return false;
    };
    
    // Refresh view
    listView.View.RefreshFilter();
};

パターン 4：項目のカスタムスタイル設定

// Customize item appearance
listView.Style.ItemStyle.BackColor = Color.White;
listView.Style.ItemStyle.HoverBackColor = Color.LightBlue;
listView.Style.ItemStyle.SelectedItemBackColor = Color.Blue;
listView.Style.ItemStyle.SelectedItemForeColor = Color.White;
listView.Style.ItemStyle.Font = new Font("Segoe UI", 10f);

// Customize group headers
listView.Style.GroupHeaderStyle.BackColor = Color.LightGray;
listView.Style.GroupHeaderStyle.ForeColor = Color.Black;
listView.Style.GroupHeaderStyle.Font = new Font("Segoe UI", 10f, FontStyle.Bold);

パターン 5：ライブ更新に対応した ObservableCollection

using System.Collections.ObjectModel;
using System.ComponentModel;

public class CountryViewModel : INotifyPropertyChanged
{
    private ObservableCollection<CountryInfo> countries;
    
    public ObservableCollection<CountryInfo> Countries
    {
        get { return countries; }
        set
        {
            countries = value;
            OnPropertyChanged(nameof(Countries));
        }
    }
    
    public CountryViewModel()
    {
        Countries = new ObservableCollection<CountryInfo>
        {
            new CountryInfo { CountryName = "USA", Continent = "North America" }
        };
    }
    
    // Add item - ListView updates automatically
    public void AddCountry(CountryInfo country)
    {
        Countries.Add(country);
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

// Bind to ListView
var viewModel = new CountryViewModel();
listView.DataSource = viewModel.Countries;
listView.DisplayMember = "CountryName";

主なプロパティ

コアプロパティ

プロパティ	型	説明
DataSource	object	データソース（IEnumerable）を取得または設定します
DisplayMember	string	項目に表示するプロパティ名
ValueMember	string	項目の値に使用するプロパティ名
SelectedItem	object	現在選択されている項目
SelectedItems	List	選択されている項目のコレクション
CheckedItems	List	チェックされている項目のコレクション

選択プロパティ

プロパティ	型	説明
SelectionMode	SelectionMode	None、One、MultiSimple、MultiExtended
SelectedIndex	int	選択されている項目のインデックス
SelectedIndices	List	選択されている項目のインデックス一覧
AllowMultiSelection	bool	複数選択を有効にします

チェックボックスのプロパティ

プロパティ	型	説明
CheckBoxSelectionMode	CheckBoxSelectionMode	None、Default、SelectAll
CheckedIndices	List	チェックされている項目のインデックス一覧
AllowRecursiveChecking	bool	グループ内の再帰的なチェックを有効にします
ShowCheckBoxes	bool	チェックボックスの表示／非表示を切り替えます

外観プロパティ

プロパティ	型	説明
Style	ListViewStyle	全体のスタイル設定
ItemHeight	int	各項目の高さ
GroupHeaderHeight	int	グループヘッダーの高さ
AutoFitMode	AutoFitMode	None、Height、DynamicHeight

データ操作プロパティ

プロパティ	型	説明
View	DataView	グループ化、並べ替え、フィルターへのアクセス
LiveDataUpdateMode	LiveDataUpdateMode	AllowDataShaping、AllowSummary、Default

イベント

イベント	説明
SelectionChanged	選択が変更されたときに発生します
ItemChecking	項目のチェック中に発生します（キャンセル可能）
ItemChecked	項目のチェック状態が変更された後に発生します
ItemsSourceChanged	DataSource が変更されたときに発生します
DrawItem	項目のカスタム描画
QueryItemHeight	項目の高さを動的に計算します

よくあるユースケース

1. 連絡先リストアプリケーション

先頭の文字でグループ化した連絡先を表示し、検索機能や操作対象の選択機能を備えます。

2. 商品カタログブラウザー

カテゴリで商品をフィルターし、価格で並べ替え、カートに追加する商品をチェックボックスで選択できるようにします。

3. ファイルエクスプローラービュー

アイコン付きのファイル／フォルダー一覧を作成し、種類ごとにグループ化して、名前、日付、サイズで並べ替えます。

4. タスク管理リスト

チェックボックスでタスクの完了を管理し、優先度やステータスでグループ化して、日付でフィルターします。

5. メールクライアントの受信トレイ

メールメッセージを表示し、選択、日付順の並べ替え、既読／未読状態によるフィルタリングを行います。

6. 顧客の注文リスト

注文を表示し、ステータスごとにグループ化し、日付順に並べ替えて、詳細を確認する注文を選択できるようにします。

7. 設定構成 UI

機能の有効／無効を切り替えるチェックボックス付きの設定リストを作成します。

8. データグリッドの代替

複雑なグリッド機能を使わず、シンプルなリスト形式でデータを表示する場合は、ListView を使用します。

関連コンポーネント

• DataGrid - 列を含む表形式のデータ向け
• TreeView - 階層型のデータ構造向け
• ComboBox - リストからドロップダウンで選択する場合に使用
• CheckedListBox - 高度な機能を必要としないシンプルなチェックボックスリスト

ベストプラクティス

1. データバインディング

   • UI を自動更新するには ObservableCollection を使用します
   • 項目のプロパティ変更を反映するには INotifyPropertyChanged を実装します
   • 分かりやすくするため、DisplayMember と ValueMember を設定します

2. パフォーマンス

   • ビューの再利用を有効にします（既定で有効です）
   • 大規模なデータセットでは AutoFitMode を慎重に使用します
   • シンプルなケースではカスタム DrawItem を避けます
   • データソースを再作成する代わりに、フィルタリングやグループ化を使用します

3. 選択

   • ユーザー操作には SelectionChanged イベントを処理します
   • 用途に適した SelectionMode を使用します
   • 必要に応じて、データソースの変更時に選択を解除します

4. グループ化とフィルタリング

   • グループ化には View.GroupDescriptors を使用します
   • フィルタリングには View.Filter の述語を設定します
   • フィルター条件の変更後に RefreshFilter() を呼び出します
   • 一貫した順序にするには SortDescriptors を使用します

5. カスタマイズ

   • カスタム描画を行う前に Style プロパティを使用します
   • 一貫した外観にするため、テーマを適用します
   • 基本的なカスタマイズには ItemStyle と GroupHeaderStyle を使用します
   • 複雑なカスタム描画に限り、DrawItem を使用します

6. アクセシビリティ

   • UIAutomation のサポートを有効にします
   • 意味のある DisplayMember 値を指定します
   • キーボード操作をサポートします
   • スクリーンリーダーでテストします

トラブルシューティング

項目が表示されない

• DataSource が設定されており、null でないことを確認します
• DisplayMember がプロパティ名と一致していることを確認します（大文字と小文字を区別します）
• データオブジェクトにパブリックプロパティがあることを確認します
• ListView のサイズがゼロでないことを確認します

選択が機能しない

• SelectionMode が None でないことを確認します
• SelectionChanged イベントが登録されていることを確認します
• 項目が有効になっていることを確認します
• AllowMultiSelection が SelectionMode と一致しているか確認します

グループ化／フィルタリングが適用されない

• フィルターの変更後に View.RefreshFilter() を呼び出します
• GroupDescriptor の PropertyName が正しいことを確認します
• データプロパティが存在し、アクセス可能であることを確認します
• LiveDataUpdateMode が適切であることを確認します

パフォーマンスの問題

• 大規模なリストでは AutoFitMode の使用を減らします
• 複雑な DrawItem のロジックを避けます
• ビューの再利用を使用します（既定の動作です）
• 非常に大規模なデータセットでは仮想化を検討します

チェックボックスの問題

• CheckBoxSelectionMode が None でないことを確認します
• グループ化されたリストでは AllowRecursiveChecking の設定を確認します
• SelectionChanged ではなく、ItemChecking／ItemChecked イベントを使用します
• CheckedItems と SelectedItems の違いに注意します

---

次のステップ： 実装のニーズに応じて、該当するリファレンスドキュメントに進んでください。初期設定については getting-started.md から始め、その後、必要に応じてデータバインディング、選択、データ操作について確認してください。