syncfusion-wpf-multi-column-dropdown

Syncfusion WPF Multi Column Dropdown の実装

SfMultiColumnDropDownControl は、TextBox エディターと強力な SfDataGrid を組み合わせ、複数の列を表示する検索・フィルター対応のドロップダウンコントロールを提供します。オートコンプリート、インクリメンタルフィルタリング、単一選択モードと複数選択モード、豊富なカスタマイズオプションに対応しています。

コンポーネントの概要

SfMultiColumnDropDownControl は、ドロップダウンポップアップ内に SfDataGrid を埋め込んだ複合コントロールで、次の操作ができます。

• エディターに入力して項目を検索およびフィルター
• ドロップダウン内でデータの複数列を表示
• グリッドから単一または複数の項目を選択
• DisplayMember に基づいてテキストをオートコンプリート
• ポップアップの外観、列、動作をカスタマイズ

主な機能：

• 任意の IEnumerable ソースへのデータバインディング
• 列の自動生成または手動生成
• 大文字と小文字、および発音区別符号を区別するフィルタリング
• 複雑なプロパティとインデクサープロパティのバインディング
• キーボードナビゲーションとアクセシビリティのサポート
• 外観をカスタマイズできるサイズ変更可能なポップアップ

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

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

• 複数列のデータを表示する WPF ドロップダウンを作成する
• グリッド表示の検索・フィルター対応ドロップダウンリストを実装する
• オートコンプリートとインクリメンタルフィルタリングに対応するドロップダウンコントロールを構築する
• 複数列のデータグリッドから項目を選択できるようにする
• 複雑なデータバインディングに対応する編集可能なドロップダウンを作成する
• 単一選択または複数選択に対応するドロップダウンを実装する
• ドロップダウンポップアップの外観と動作をカスタマイズする
• ドロップダウンコントロールにキーボードナビゲーションを追加する

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

はじめに

📄 参照先： references/getting-started.md

次のような場合に使用してください。

• コントロールを初めて設定する
• アセンブリの要件を確認する
• Designer、XAML、または C# でコントロールを追加する
• 基本的なデータモデルを作成する
• 初期 ItemsSource をバインドする
• DisplayMember と ValueMember を定義する

扱うトピック：

• アセンブリの配置（Syncfusion.Data.WPF、Syncfusion.SfGrid.WPF）
• SfMultiColumnDropDownControl を使用した WPF アプリケーションの作成
• Designer、XAML、コードビハインドによるコントロールの追加
• 基本的な ItemsSource バインディング
• DisplayMember と ValueMember の設定
• テーマのサポート

データバインディング

📄 参照先： references/data-binding.md

次のような場合に使用してください。

• ドロップダウンコントロールにデータをバインドする
• DisplayMember と ValueMember の違いを理解する
• 複雑なプロパティを扱う
• インデクサープロパティを使用する
• SelectedItem と SelectedValue にアクセスする

扱うトピック：

• ItemsSource プロパティの使用方法
• DisplayMember（エディターでの視覚的な表示）
• ValueMember（SelectedValue プロパティの値）
• XAML とコードビハインドでのコレクションのバインディング
• 複雑なプロパティのバインディング（例：customerDetails.Name）
• インデクサープロパティのバインディング（例：Country[0]）

列の設定

📄 参照先： references/columns.md

次のような場合に使用してください。

• ドロップダウングリッドの列を設定する
• 列を自動生成する、または手動で定義する
• 列の種類とテンプレートをカスタマイズする
• AutoGeneratingColumn イベントを処理する
• 列のサイズと幅を設定する

扱うトピック：

• AutoGenerateColumns プロパティ
• AutoGenerateColumnMode（Reset、RetainOld、ResetAll、None）
• 列コレクションを手動で定義する
• 列の種類（GridTextColumn、GridCurrencyColumn など）
• カスタマイズ用の AutoGeneratingColumn イベント
• 列のテンプレート（HeaderTemplate、CellTemplate）
• 幅を管理する GridColumnSizer

編集とフィルタリング

📄 参照： references/editing-autocomplete.md

次のような場合に使用します：

• オートコンプリート機能を有効にする
• インクリメンタルフィルタリングを実装する
• 検索条件を設定する
• 複数の列に基づいてフィルタリングする
• エディターの動作をカスタマイズする

対象トピック：

• テキスト候補の AllowAutoComplete
• ライブフィルタリングの AllowIncrementalFiltering
• SearchCondition（StartsWith、Contains、Equals）
• AllowCaseSensitiveFiltering オプション
• AllowDiacriticSensitiveFiltering オプション
• エディターのプロパティ（ReadOnly、AllowNullInput、AllowSpinOnMouseWheel）
• カスタムフィルタリング用の FilterRecord メソッドのオーバーライド
• 複数列のフィルタリング用の SearchText プロパティ

選択

📄 参照： references/selection.md

次のような場合に使用します：

• 単一選択または複数選択を実装する
• 選択した項目にプログラムからアクセスする
• 選択の変更を処理する
• 複数選択時の区切り文字をカスタマイズする
• 選択イベントを扱う

対象トピック：

• SelectionMode（Single、Multiple）
• SelectedItem、SelectedIndex、SelectedValue プロパティ
• 複数選択用の SelectedItems コレクション
• SelectionChanged イベント
• 複数選択表示用の SeparatorString
• TextSelectionOnFocus プロパティ
• プログラムからの選択
• チェックボックス付きのセレクター列

ポップアップのカスタマイズ

📄 参照： references/popup-customization.md

次のような場合に使用します：

• ポップアップの外観をカスタマイズする
• ポップアップのサイズとサイズ変更を設定する
• ポップアップの背景と境界線を設定する
• ポップアップイベントを処理する
• ドロップダウンにカスタムヘッダーを追加する

対象トピック：

• ポップアップの外観（Background、BorderBrush、BorderThickness）
• ポップアップのサイズ（PopupHeight、PopupWidth、Min/Max 値）
• 自動サイズ調整用の IsAutoPopupSize
• サイズ変更用のリサイズつまみ
• PopupContentTemplate と HeaderTemplate
• ポップアップイベント（Opening、Opened、Closing、Closed）
• StaysOpen プロパティ
• ドロップダウンヘッダー内のカスタムコントロール

キーボードとアクセシビリティ

📄 参照： references/keyboard-accessibility.md

次のような場合に使用します：

• キーボードナビゲーションを実装する
• アクセシビリティへの準拠を確保する
• UI オートメーションを設定する
• コード化された UI テストを設定する
• キーボードショートカットを理解する

対象トピック：

• キーボードショートカット（Enter、Esc、F4、Alt+Arrows、Up/Down）
• キーボードナビゲーションのパターン
• UI Automation のサポート
• Coded UI Test のプロパティとメソッド
• QTP（Quick Test Professional）のサポート
• アクセシビリティ機能

クイックスタート

基本的な実装

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns:local="clr-namespace:YourNamespace">
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    
    <Grid>
        <syncfusion:SfMultiColumnDropDownControl 
            x:Name="sfMultiColumn"
            Width="200"
            Height="30"
            ItemsSource="{Binding Orders}"
            DisplayMember="CustomerName"
            ValueMember="OrderID"
            SelectedIndex="0"/>
    </Grid>
</Window>

コードビハインドの設定

using Syncfusion.UI.Xaml.Grid;
using System.Collections.ObjectModel;

namespace YourNamespace
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            
            // Create control programmatically
            SfMultiColumnDropDownControl sfMultiColumn = new SfMultiColumnDropDownControl();
            sfMultiColumn.Width = 200;
            sfMultiColumn.Height = 30;
            sfMultiColumn.ItemsSource = viewModel.Orders;
            sfMultiColumn.DisplayMember = "CustomerName";
            sfMultiColumn.ValueMember = "OrderID";
            
            // Add to layout
            Root_Grid.Children.Add(sfMultiColumn);
        }
    }
    
    // Data Model
    public class OrderInfo
    {
        public int OrderID { get; set; }
        public string CustomerName { get; set; }
        public string CustomerID { get; set; }
        public string Country { get; set; }
        
        public OrderInfo(int orderId, string customerName, string customerId, string country)
        {
            OrderID = orderId;
            CustomerName = customerName;
            CustomerID = customerId;
            Country = country;
        }
    }
    
    // ViewModel
    public class ViewModel
    {
        public ObservableCollection<OrderInfo> Orders { get; set; }
        
        public ViewModel()
        {
            Orders = new ObservableCollection<OrderInfo>
            {
                new OrderInfo(1001, "Maria Anders", "ALFKI", "Germany"),
                new OrderInfo(1002, "Ana Trujilo", "ANATR", "Mexico"),
                new OrderInfo(1003, "Thomas Hardy", "AROUT", "UK")
            };
        }
    }
}

よくあるパターン

パターン 1：オートコンプリート付きのフィルタリング可能なドロップダウン

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    AllowAutoComplete="True"
    AllowIncrementalFiltering="True"
    SearchCondition="Contains"
    SelectedIndex="0"/>

パターン 2：複数選択ドロップダウン

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    SelectionMode="Multiple"
    SeparatorString=", "/>

選択した項目へのアクセス：

// Get all selected items
var selectedItems = sfMultiColumn.SelectedItems;

// Programmatically add selections
sfMultiColumn.SelectedItems.Add(orderItem);

パターン 3：手動定義によるカスタム列

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="OrderID"
    ValueMember="OrderID"
    AutoGenerateColumns="False">
    <syncfusion:SfMultiColumnDropDownControl.Columns>
        <syncfusion:GridTextColumn MappingName="OrderID" HeaderText="Order ID" Width="100"/>
        <syncfusion:GridTextColumn MappingName="CustomerName" HeaderText="Customer" Width="150"/>
        <syncfusion:GridCurrencyColumn MappingName="Amount" HeaderText="Amount" Width="120"/>
        <syncfusion:GridTextColumn MappingName="Country" Width="100"/>
    </syncfusion:SfMultiColumnDropDownControl.Columns>
</syncfusion:SfMultiColumnDropDownControl>

パターン 4：カスタマイズしたポップアップの外観

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    PopupHeight="300"
    PopupWidth="500"
    PopupBackground="WhiteSmoke"
    PopupBorderBrush="SteelBlue"
    PopupBorderThickness="2"
    PopupDropDownGridBackground="White"
    IsAutoPopupSize="False"/>

主なプロパティ

コアデータプロパティ

• ItemsSource：ドロップダウンのデータソース（IEnumerable）
• DisplayMember：エディターに表示するプロパティパス
• ValueMember：SelectedValue 用のプロパティパス
• SelectedItem：現在選択されているデータオブジェクト
• SelectedIndex：選択されている項目のインデックス（未選択の場合は -1）
• SelectedValue：ValueMember に基づく SelectedItem の値
• SelectedItems：選択された項目のコレクション（複数選択モード）

フィルタリングと編集

• AllowAutoComplete：テキストのオートコンプリートを有効にする（デフォルト：false）
• AllowIncrementalFiltering：入力テキストに基づいて項目をフィルタリングする（デフォルト：false）
• SearchCondition：フィルタリング条件（StartsWith、Contains、Equals）
• AllowCaseSensitiveFiltering：大文字と小文字を区別してフィルタリングする（デフォルト：false）
• AllowDiacriticSensitiveFiltering：ダイアクリティカルマークを区別してフィルタリングする（デフォルト：true）
• ReadOnly：エディターを読み取り専用にする（デフォルト：false）
• AllowNullInput：null 値を許可する（デフォルト：false）
• SearchText：エディター内の現在のテキスト（読み取り専用）

列の構成

• AutoGenerateColumns：データから列を自動生成します（既定値：true）
• AutoGenerateColumnMode：列の生成モード（Reset、RetainOld、ResetAll、None）
• Columns：手動で定義した列のコレクション
• GridColumnSizer：列幅のサイズ設定方法（Auto、Star、None）

選択

• SelectionMode：単一選択または複数選択
• SeparatorString：複数選択の表示に使用する区切り文字（既定値：「;」）
• TextSelectionOnFocus：フォーカス時にテキストを自動選択します（既定値：false）

ポップアップ

• IsDropDownOpen：ポップアップの開閉状態
• PopupHeight/PopupWidth：ポップアップのサイズ
• PopupMinHeight/PopupMaxHeight：サイズの制約
• PopupMinWidth/PopupMaxWidth：サイズの制約
• IsAutoPopupSize：グリッドに合わせてサイズを自動調整します（既定値：false）
• PopupBackground：ポップアップの背景ブラシ
• PopupBorderBrush：ポップアップの境界線ブラシ
• PopupBorderThickness：ポップアップの境界線の太さ

動作

• AllowImmediatePopup：編集中に一致項目が見つかったときにポップアップを開きます
• AllowSpinOnMouseWheel：マウスホイールで選択項目を変更します（既定値：true）

主なユースケース

1. 検索機能付きの商品選択

ID、名前、カテゴリ、価格などの複数列で商品カタログを表示し、オートコンプリートを使って商品名で検索できるようにします。

2. 顧客情報の検索

ドロップダウンに顧客情報（名前、メールアドレス、電話番号、都市）を表示し、入力に応じて絞り込み、選択した顧客名をエディターに表示します。

3. 複数プロジェクトの割り当て

プロジェクトコード、名前、ステータス、期限を示す一覧から、チェックボックスを使って複数のプロジェクトを選択できるようにします。

4. 請求書の項目選択

項目コード、説明、単価、在庫数を列に表示するドロップダウンを用意し、項目コードまたは説明で絞り込みます。

5. 従業員名簿

名前、部署、メールアドレス、電話番号の列を備えた検索可能な従業員一覧を表示し、従業員名のオートコンプリートを利用します。

6. レポートパラメーターの選択

名前、カテゴリ、説明の列で利用可能なレポートを表示し、レポートの生成に向けて絞り込みや選択ができるようにします。

関連スキル

• WPF データグリッドの実装 - ドロップダウンで使用する高度な SfDataGrid 機能について説明します
• WPF データバインディング - 一般的な WPF データバインディングのパターン
• WPF のテーマ設定 - コンポーネントへのテーマの適用

ベストプラクティス

1. ValueMember を適切に使用する：選択状態を確実に追跡できるよう、一意の識別子となるプロパティを ValueMember に設定します
2. 大規模なデータセットではフィルタリングを有効にする：項目数が多い場合は AllowIncrementalFiltering を使用し、使いやすさを向上させます
3. 制御しやすいように列を手動で定義する：AutoGenerateColumns="False" を設定し、予測可能なレイアウトになるよう列を定義します
4. SelectionChanged イベントを処理する：選択の変更に応じて、連動する UI を更新します
5. 適切なポップアップサイズを設定する：PopupHeight/PopupWidth を構成するか、IsAutoPopupSize を使用して最適な表示を実現します
6. パフォーマンスを考慮する：非常に大きなデータセット（1000 項目超）では、仮想化またはサーバー側でのフィルタリングを実装します
7. キーボード操作をテストする：ユーザーがキーボードショートカットで効率よく操作できることを確認します
8. 分かりやすい DisplayMember を指定する：ユーザーが項目を明確に識別できるプロパティを選択します

トラブルシューティング

• 列が表示されない：ItemsSource がバインドされ、データが含まれていることを確認します。AutoGenerateColumns の設定も確認してください
• フィルタリングが機能しない：AllowIncrementalFiltering="True" が設定され、DisplayMember が正しく設定されていることを確認します
• オートコンプリートが表示されない：AllowAutoComplete="True" を設定し、データに DisplayMember プロパティが存在することを確認します
• 複数選択が表示されない：SelectionMode="Multiple" を設定し、SelectedItems コレクションを確認します
• ポップアップのサイズが適切でない：PopupHeight/PopupWidth を調整するか、IsAutoPopupSize を有効にします
• 大量データでパフォーマンスに問題がある：データの仮想化を検討するか、表示する列を制限します