syncfusion-wpf-checkedlistbox

Syncfusion WPF CheckedListBox の実装

Syncfusion® WPF CheckedListBox（CheckListBox）コントロールを実装するためのガイドです。チェックボックス付きの項目を表示して複数選択できる、強力なリストコントロールです。このスキルでは、適切なデータバインディング、スタイル設定、パフォーマンスの最適化を行いながら、WPF アプリケーションに CheckListBox コントロールを統合、構成、カスタマイズする方法を説明します。

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

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

• WPF でチェックボックスを使った複数選択リストを実装する
• カスタムコンテンツやテンプレートを使ってチェック可能な項目を表示する
• MVVM パターンでデータコレクションを CheckListBox にバインドする
• 項目のチェック／チェック解除イベントや選択状態を処理する
• リスト内の項目をグループ化および並べ替えする
• テーマ、色、チェックボックスの配置など、外観をカスタマイズする
• 大規模なデータセット向けに仮想化を使用してパフォーマンスを最適化する
• SelectAll／UnselectAll 機能を実装する
• 向きや折り返しなどのレイアウトオプションを構成する
• CheckListBox 関連の問題をトラブルシューティングする

コンポーネントの概要

CheckListBox コントロールは、チェックボックス付きの項目を持つ従来型のリストボックスを実装し、チェックボックスによる複数選択を可能にします。各項目は個別にチェックまたはチェック解除でき、コントロールは豊富なカスタマイズ、データバインディング、グループ化、並べ替え、高パフォーマンスが求められる場面向けの仮想化に対応しています。

主な機能：

• シングルクリックまたはダブルクリックによる項目選択
• チェックボックスの配置（左または右）
• 完全なデータバインディングと MVVM のサポート
• CollectionView によるグループ化
• 並べ替え機能
• SelectAll／UnselectAll 機能
• 組み込みのテーマと視覚スタイル
• 大規模な項目コレクション向けの仮想化
• カスタムテンプレートとスタイル設定
• チェック状態の変更に関するイベント通知

必要なアセンブリ：

• Syncfusion.Shared.WPF
• Syncfusion.Tools.WPF

名前空間： Syncfusion.Windows.Tools.Controls

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

はじめに

📄 参照： references/getting-started.md

参照する場面：新しい CheckListBox の実装を始めるとき、アセンブリを設定するとき、または基本的なリストを作成するとき。

扱うトピック：

• アセンブリの配置と NuGet パッケージ
• CheckListBox を使用した WPF プロジェクトの作成
• デザイナーと XAML によるコントロールの追加
• C# でのコントロールの手動追加
• CheckListBoxItem を使用した項目の追加
• ItemsSource によるデータバインディングを使用した項目の追加
• DisplayMemberPath の構成
• 基本的な例と最小限のセットアップ

データバインディング

📄 参照： references/data-binding.md

参照する場面：MVVM パターンを実装するとき、コレクションをバインドするとき、またはデータバインディングでチェック状態を管理するとき。

扱うトピック：

• ItemsSource プロパティの構成
• 表示値のための DisplayMemberPath
• IsSelected プロパティのモデルへのバインド
• モデルと ViewModel の実装
• ObservableCollection のセットアップ
• チェック状態の TwoWay バインディング
• INotifyPropertyChanged パターン
• IsSelected をバインドする ItemContainerStyle

項目のチェックと選択

📄 参照： references/checking-and-selection.md

参照する場面：項目の選択動作を管理するとき、チェックイベントを処理するとき、または SelectAll 機能を実装するとき。

扱うトピック：

• プログラムによる項目のチェック／チェック解除
• IsCheckOnFirstClick プロパティ（シングルクリックとダブルクリック）
• SelectedItems コレクションの管理
• 現在の選択項目を示す SelectedItem プロパティ
• 初期化時の項目のチェック
• SelectAll と UnselectAll の実装
• ItemChecked イベントの処理
• ItemCheckedEventArgs の使用
• キーボード操作（Space キー）
• チェック済み項目のリストの取得

グループ化と並べ替え

📄 読む: references/grouping-and-sorting.md

読むタイミング：項目をグループにまとめるとき、項目をアルファベット順または数値順に並べ替えるとき、あるいは階層ビューを実装するときです。

対象トピック：

• CollectionView.GroupDescriptions を使用したグループ化
• PropertyGroupDescription の設定
• グループヘッダーの選択状態
• グループの展開／折りたたみ
• CollectionView.SortDescriptions を使用した並べ替え
• SortDescription のプロパティ（PropertyName、Direction）
• 昇順と降順
• 複数の並べ替え条件
• グループ化と並べ替えの組み合わせ

外観とカスタマイズ

📄 読む: references/appearance-customization.md

読むタイミング：コントロールのスタイルを設定するとき、色やフォントをカスタマイズするとき、チェックボックスの配置を変更するとき、またはテーマを適用するときです。

対象トピック：

• Foreground プロパティと Background プロパティ
• ホバー効果のための MouseOverBackground
• SelectedItemBackground のスタイル設定
• CheckBox の配置（左／右）
• CheckBoxPlacement プロパティ
• 組み込みのビジュアルスタイルとテーマ
• カスタムテンプレートとスタイル
• 境界線とパディングのカスタマイズ
• フォントのスタイル設定とテキストの外観
• ItemContainerStyle のカスタマイズ

レイアウト機能

📄 読む: references/layout-features.md

読むタイミング：コントロールのレイアウトを設定するとき、寸法を調整するとき、またはスクロール動作を管理するときです。

対象トピック：

• レイアウト関連プロパティの概要
• Orientation の設定（垂直／水平）
• 項目の折り返し動作
• スクロールの設定
• 高さと幅の管理
• ScrollViewer の設定
• 項目の間隔とパディング
• コンテナーのサイズ設定

仮想化とパフォーマンス

📄 読む: references/virtualization.md

読むタイミング：大規模なデータセットのパフォーマンスを最適化するとき、メモリ使用量を削減するとき、またはパフォーマンスの問題が発生しているときです。

対象トピック：

• VirtualizingStackPanel の使用
• UI 仮想化の有効化
• パフォーマンス最適化の手法
• ScrollUnit の設定
• メモリ管理のメリット
• 大規模なコレクションでのベストプラクティス
• 仮想化の制限事項
• 仮想化を使用するタイミング

クイックスタートの例

静的な項目を使用した基本的な CheckListBox

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:CheckListBox x:Name="checkListBox" 
                                 Width="200" 
                                 Height="300">
            <syncfusion:CheckListBoxItem Content="Mexico" />
            <syncfusion:CheckListBoxItem Content="Canada" />
            <syncfusion:CheckListBoxItem Content="Bermuda" />
            <syncfusion:CheckListBoxItem Content="Belize" />
            <syncfusion:CheckListBoxItem Content="Panama" />
        </syncfusion:CheckListBox>
    </Grid>
</Window>

データバインディングを使用した CheckListBox

<syncfusion:CheckListBox ItemsSource="{Binding Countries}"
                         DisplayMemberPath="Name"
                         IsCheckOnFirstClick="True">
    <syncfusion:CheckListBox.ItemContainerStyle>
        <Style TargetType="syncfusion:CheckListBoxItem">
            <Setter Property="IsSelected" Value="{Binding IsChecked, Mode=TwoWay}" />
        </Style>
    </syncfusion:CheckListBox.ItemContainerStyle>
</syncfusion:CheckListBox>

// ViewModel
public class ViewModel : INotifyPropertyChanged
{
    public ObservableCollection<Country> Countries { get; set; }
    
    public ViewModel()
    {
        Countries = new ObservableCollection<Country>
        {
            new Country { Name = "Mexico", IsChecked = true },
            new Country { Name = "Canada", IsChecked = false },
            new Country { Name = "Bermuda", IsChecked = false }
        };
    }
}

// Model
public class Country : INotifyPropertyChanged
{
    private bool isChecked;
    public string Name { get; set; }
    public bool IsChecked 
    { 
        get => isChecked;
        set { isChecked = value; OnPropertyChanged(); }
    }
}

よくあるパターン

パターン 1：項目のチェックイベントを処理する

// XAML
<syncfusion:CheckListBox ItemChecked="CheckListBox_ItemChecked" />

// Code-behind
private void CheckListBox_ItemChecked(object sender, ItemCheckedEventArgs e)
{
    var item = e.Item as CheckListBoxItem;
    MessageBox.Show($"{item.Content} is {(e.IsChecked ? "checked" : "unchecked")}");
}

パターン 2：チェックされたすべての項目を取得する

// Get checked items from SelectedItems property
var checkedItems = checkListBox.SelectedItems;

foreach (var item in checkedItems)
{
    var checkListBoxItem = item as CheckListBoxItem;
    Console.WriteLine(checkListBoxItem.Content);
}

パターン 3：プログラムから項目をチェックする

// Add items to SelectedItems collection
checkListBox.SelectedItems.Add(countryModel1);
checkListBox.SelectedItems.Add(countryModel2);

パターン 4：SelectAll の実装

// Check all items
foreach (var item in checkListBox.Items)
{
    if (!checkListBox.SelectedItems.Contains(item))
    {
        checkListBox.SelectedItems.Add(item);
    }
}

主なプロパティ

プロパティ	型	説明	デフォルト
ItemsSource	IEnumerable	項目のデータソース	null
DisplayMemberPath	string	表示テキストのプロパティパス	null
SelectedItems	IList	チェックされた項目のコレクション	Empty
SelectedItem	object	現在選択されている（フォーカスされた）項目	null
IsCheckOnFirstClick	bool	初回クリックで項目をチェックするか、ダブルクリックでチェックするか	true
CheckBoxPlacement	CheckBoxPlacement	チェックボックスの位置（Left/Right）	Left
Foreground	Brush	テキストの色	Black
Background	Brush	背景色	Transparent
MouseOverBackground	Brush	ホバー時の背景色	System default
SelectedItemBackground	Brush	選択項目の背景	System default

主なイベント

イベント	EventArgs	説明
ItemChecked	ItemCheckedEventArgs	項目のチェック状態が変わったときに発生します
SelectionChanged	SelectionChangedEventArgs	選択が変わったときに発生します

よくあるユースケース

ユースケース 1：複数選択フィルターリスト

検索フィルター、レポートオプション、または設定パネルで複数選択できるよう、チェックボックス付きのフィルター可能な項目を表示します。

→ 読む: getting-started.md + data-binding.md

ユースケース 2：設定構成パネル

切り替え可能なオプション、機能フラグ、または設定の選択項目を複数備えた設定 UI を作成します。

→ 参照： checking-and-selection.md + appearance-customization.md

ユースケース 3：グループ化された大規模データセット

パフォーマンス向上のための仮想化を適用し、カテゴリ別に整理された数千件のチェック可能な項目を表示します。

→ 参照： grouping-and-sorting.md + virtualization.md

ユースケース 4：権限／ロール管理

グループ化された機能とグループごとの SelectAll を備えた、ロールまたは権限の選択 UI を実装します。

→ 参照： grouping-and-sorting.md + checking-and-selection.md

ユースケース 5：ブランドに合わせたスタイルのチェックリスト

カスタムテーマ、色、チェックボックスの配置を適用して、アプリケーションのブランドに合わせます。

→ 参照： appearance-customization.md

トラブルシューティングのクイックリンク

問題	移動先
項目が正しくデータバインディングされない	data-binding.md
チェック状態が更新されない	checking-and-selection.md
項目数が多い場合のパフォーマンス問題	virtualization.md
スタイルが適用されない	appearance-customization.md
グループが表示されない	grouping-and-sorting.md

---

次のステップ： 実装のニーズに応じて上記のリファレンスガイドを選ぶか、初期設定については getting-started.md から始めてください。