syncfusion-winui-combobox

ComboBox の実装（Syncfusion WinUI）

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

ユーザーが次のことを必要としている場合に、このスキルを使用します。

• WinUI アプリケーションにドロップダウン選択コントロールを実装する
• リストから単一または複数の項目を選択できるようにする
• ドロップダウンにフィルタリング機能と検索機能を追加する
• 自動補完機能付きの編集可能なドロップダウンを作成する
• 選択した項目をトークンまたは区切り文字で区切られた値として表示する
• ドロップダウンの項目をカテゴリごとにグループ化する
• テンプレートでドロップダウンの外観をカスタマイズする
• ユーザー入力の検証と無効な項目への対応を行う
• ドロップダウンでキーボード操作を実装する

コンポーネントの概要

Syncfusion WinUI ComboBox（SfComboBox）は、次の機能を備えた多機能なドロップダウン選択コントロールです。

• 選択モード： チェックボックスに対応した単一選択と複数選択
• フィルタリング： StartsWith モードまたは Contains モードによる組み込みのフィルタリング
• 編集： 自動補完機能付きの編集可能モードと編集不可モード
• 表示モード： 複数選択時のトークン表示または区切り文字で区切られた表示
• 検索： ハイライト表示に対応したテキスト検索
• グループ化： 項目をカテゴリごとに整理
• カスタマイズ： 豊富なテンプレートとスタイルの設定オプション
• キーボード操作： キーボードによる操作とショートカットに完全対応
• アクセシビリティ： スクリーンリーダーに対応した WCAG 準拠の設計

⚠️ セキュリティに関する考慮事項

ComboBox を外部データソースやカスタムフィルタリングと併用する場合：

• データソースのセキュリティ： ItemsSource には、信頼できる内部データソースのみをバインドしてください。表示する前に外部データを検証してください。
• 画像のバインド： Image.Source を信頼できない外部 URL にバインドしないでください。代わりに、埋め込みリソース（ms-appx:///）またはローカルファイル（file:///）を使用してください。
• カスタムフィルタリング： 外部 API を使用して IComboBoxFilterBehavior を実装する場合は、許可するドメインを必ずホワイトリストに登録し、応答をサニタイズしてください。
• ユーザー入力： 編集可能モードでは、ユーザー入力を検証してサニタイズしてください。特に、バックエンドサービスに渡す場合は注意してください。

ComboBox と他のドロップダウンの使い分け：

• ComboBox を使用する場合： フィルタリング、編集、またはトークンを使った複数選択が必要な場合
• DropDownList を使用する場合： 編集機能のないシンプルな単一選択が必要な場合
• MultiSelect Dropdown を使用する場合： トークンを使わない複数選択（チェックボックスのみ）が必要な場合
• AutoComplete を使用する場合： ドロップダウンリストを表示し続けずに、入力中の候補表示が必要な場合

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

はじめに

📄 参照： references/getting-started.md

• NuGet パッケージ（Syncfusion.Editors.WinUI）のインストール
• NuGet パッケージ（Syncfusion.Editors.WinUI）のインストール
• 注：リリース前に、Syncfusion.Editors.WinUI NuGet パッケージを利用可能な最新バージョンに更新してください。
• XAML と C# での基本的な ComboBox の実装
• SfComboBoxItem を使用した項目の追加
• ItemsSource を使ったデータバインディング
• DisplayMemberPath と TextMemberPath の設定
• SelectionBox UI のカスタマイズ

選択モード

📄 参照： references/selection.md

• 単一選択（UI とプログラムによる選択）
• SelectionChangeTrigger（Committed と Always）
• チェックボックスを使った複数選択
• 複数選択時の区切り文字による表示モード
• 削除可能なトークンを使ったトークン表示モード
• チェックボックスの表示と非表示
• 自動追加時の UI タイプ（TextWithSelection と Text）
• SelectionChanged イベントと SelectionChanging イベント

フィルタリングと検索

📄 参照： references/filtering.md

• IsFilteringEnabled によるフィルタリングの有効化
• フィルターモード（StartsWith、Contains）
• TextSearchMode の設定
• IComboBoxFilterBehavior を使ったカスタムフィルタリング
• カスタムロジックのための GetMatchingIndexes の実装
• フィルタリングの例とパターン

📄 参照： references/searching.md

• テキスト検索機能
• IsTextSearchEnabled プロパティ
• 自動補完の動作
• 検索結果のハイライト表示
• 検索のカスタマイズオプション

編集モード

📄 参照： references/editing.md

• 編集可能モードと編集不可モード（IsEditable プロパティ）
• オートコンプリートとテキストの追加
• AllowNull を使用した null 値の設定
• プログラムによるドロップダウンの表示（IsDropDownOpen）
• InputSubmitted イベントによる無効な入力の処理
• 入力検証のパターン

グループ化と整理

📄 参照： references/grouping.md

• カテゴリ別の項目のグループ化
• GroupMemberPath の設定
• グループヘッダーのカスタマイズ
• グループテンプレートとスタイル設定
• グループ内での並べ替え

UI のカスタマイズ

📄 参照： references/ui-customization.md

• ドロップダウン項目の ItemTemplate
• 選択項目の表示用 SelectionBoxItemTemplate
• ヘッダーとフッターのテンプレート
• ComboBox 要素のスタイル設定
• テーマのカスタマイズ
• トークンモードでの ComboBoxTokenItem のスタイル設定
• カスタムテンプレートの例

キーボードと高度な機能

📄 参照： references/keyboard-and-advanced.md

• キーボードナビゲーションのショートカット
• 先頭および末尾のビュー
• ウォーターマーク／プレースホルダーテキスト（PlaceholderText）
• アクセシビリティ機能
• 大規模データセットのパフォーマンス最適化
• よくある問題のトラブルシューティング

クイックスタートの例

基本的な単一選択 ComboBox

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <editors:SfComboBox x:Name="comboBox"
                        Width="250"
                        PlaceholderText="Select a social media"
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name" />
</Window>

// Model
public class SocialMedia
{
    public string Name { get; set; }
    public int ID { get; set; }
}

// ViewModel
public class SocialMediaViewModel
{
    public ObservableCollection<SocialMedia> SocialMedias { get; set; }
    
    public SocialMediaViewModel()
    {
        SocialMedias = new ObservableCollection<SocialMedia>
        {
            new SocialMedia { Name = "Facebook", ID = 0 },
            new SocialMedia { Name = "Twitter", ID = 1 },
            new SocialMedia { Name = "Instagram", ID = 2 }
        };
    }
}

// Set DataContext
comboBox.DataContext = new SocialMediaViewModel();

フィルタリング機能付きの編集可能な ComboBox

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    PlaceholderText="Type to filter..."
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

トークンを使った複数選択

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

よくあるパターン

パターン 1：オートコンプリート付きの編集可能なドロップダウン

ユーザーが入力すると、一致する項目を自動的にフィルタリングして候補を表示します。

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    IsTextSearchEnabled="True"
                    ItemsSource="{Binding Cities}"
                    DisplayMemberPath="CityName"
                    TextMemberPath="CityName" />

主な設定：

• IsEditable="True"：テキスト入力を有効にします
• IsFilteringEnabled="True"：ユーザーの入力に応じて項目をフィルタリングします
• TextSearchMode="StartsWith"：入力テキストで始まる項目をフィルタリングします
• IsTextSearchEnabled="True"：入力テキストに最初に一致した項目を自動的に追加します

パターン 2：カスタム区切り文字を使った複数選択

選択した複数の項目を、カスタム区切り文字で区切って表示します。

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Delimiter"
                    DelimiterText=" | "
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

// Access selected items
var selectedItems = comboBox.SelectedItems;
foreach (var item in selectedItems)
{
    // Process each selected item
}

パターン 3：カスタムトークンテンプレートを使ったトークンモード

選択した項目を、カスタムスタイルの削除可能なトークンとして表示します。

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.TokenItemTemplate>
        <DataTemplate>
            <Grid Background="LightBlue" 
                  Padding="8,4"
                  CornerRadius="4">
                <TextBlock Text="{Binding Name}" 
                          Foreground="DarkBlue" />
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.TokenItemTemplate>
</editors:SfComboBox>

パターン 4：無効な入力の処理

どの項目にも一致しないユーザー入力を検証して処理します。

<editors:SfComboBox x:Name="comboBox"
                    IsEditable="True"
                    InputSubmitted="OnInputSubmitted"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private async void OnInputSubmitted(object sender, ComboBoxInputSubmittedEventArgs e)
{
    // Option 1: Show error message
    var dialog = new ContentDialog
    {
        Content = $"'{e.Text}' is not a valid option. Please select from the list.",
        CloseButtonText = "Close"
    };
    dialog.XamlRoot = this.Content.XamlRoot;
    await dialog.ShowAsync();
    
    // Option 2: Add new item dynamically (for multiple selection)
    // e.Item = new YourModel { Name = e.Text, ID = comboBox.Items.Count };
    
    // Option 3: Prevent selection
    // e.Handled = true;
}

パターン 5：カスタムフィルタリングロジック

複雑なシナリオに対応するカスタムフィルタリングを実装します。

public class CustomFilterBehavior : IComboBoxFilterBehavior
{
    public List<int> GetMatchingIndexes(SfComboBox source, ComboBoxFilterInfo filterInfo)
    {
        var filteredList = new List<int>();
        var items = source.Items.OfType<YourModel>().ToList();
        
        // Custom filtering logic - search in multiple properties
        filteredList.AddRange(
            from item in items
            where item.Name.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase) ||
                  item.Category.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase)
            select items.IndexOf(item)
        );
        
        return filteredList;
    }
}

<editors:SfComboBox ItemsSource="{Binding Items}"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.FilterBehavior>
        <local:CustomFilterBehavior />
    </editors:SfComboBox.FilterBehavior>
</editors:SfComboBox>

パターン 6：プログラムによる選択の管理

動的なシナリオに対応するため、コードから選択を制御します。

// Single selection
comboBox.SelectedIndex = 2;
comboBox.SelectedItem = specificItem;

// Multiple selection
comboBox.SelectedItems.Add(item1);
comboBox.SelectedItems.Add(item2);

// Clear selection
comboBox.SelectedItems.Clear();

// React to selection changes
comboBox.SelectionChanged += (sender, e) =>
{
    foreach (var added in e.AddedItems)
    {
        // Handle newly selected items
    }
    
    foreach (var removed in e.RemovedItems)
    {
        // Handle deselected items
    }
};

主なプロパティ

データバインディング

• ItemsSource： 表示する項目のコレクション（IEnumerable）
• DisplayMemberPath： ドロップダウンリストに表示するプロパティ名
• TextMemberPath： 選択ボックスに表示するプロパティ名
• SelectedItem： 現在選択されている項目（単一選択）
• SelectedItems： 選択されている項目のコレクション（複数選択）
• SelectedIndex： 選択されている項目のインデックス（単一選択）

選択の設定

• SelectionMode： Single または Multiple による選択
• MultiSelectionDisplayMode： 複数選択時の Delimiter または Token
• DelimiterText： 区切り文字モードで項目を区切る文字（デフォルト：","）
• IsMultiSelectCheckBoxEnabled： ドロップダウンのチェックボックスの表示／非表示（デフォルト：true）
• SelectionChangeTrigger： 選択を更新するタイミング（Committed または Always）

編集とフィルタリング

• IsEditable： テキスト編集の有効／無効（デフォルト：false）
• IsFilteringEnabled： フィルタリングの有効／無効（デフォルト：false）
• TextSearchMode： フィルターモード（StartsWith または Contains）
• IsTextSearchEnabled： オートコンプリートの有効／無効（デフォルト：true）
• AllowNull： テキストを消去したときに null の選択を許可するかどうか（デフォルト：false）

表示とUI

• PlaceholderText: 選択されていないときに表示するウォーターマークテキスト
• IsDropDownOpen: プログラムからドロップダウンを開閉します
• SelectionBoxItemTemplate: 選択した項目の表示に使用するテンプレート
• ItemTemplate: ドロップダウンリストの項目に使用するテンプレート
• HeaderTemplate: ドロップダウンのヘッダーに使用するテンプレート
• FooterTemplate: ドロップダウンのフッターに使用するテンプレート

グループ化

• GroupMemberPath: 項目のグループ化に使用するプロパティ名

一般的なユースケース

ユースケース 1：国／州の選択

2段階の連動ドロップダウン：

<editors:SfComboBox x:Name="countryComboBox"
                    PlaceholderText="Select Country"
                    ItemsSource="{Binding Countries}"
                    SelectionChanged="OnCountryChanged"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

<editors:SfComboBox x:Name="stateComboBox"
                    PlaceholderText="Select State"
                    ItemsSource="{Binding States}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private void OnCountryChanged(object sender, ComboBoxSelectionChangedEventArgs e)
{
    if (e.AddedItems.Count > 0)
    {
        var country = e.AddedItems[0] as Country;
        // Update states collection based on selected country
        viewModel.LoadStates(country.ID);
    }
}

ユースケース 2：ブログ記事のタグ選択

複数のタグを選択するための、トークン表示付き複数選択：

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    PlaceholderText="Add tags..."
                    ItemsSource="{Binding AvailableTags}"
                    InputSubmitted="OnTagInputSubmitted"
                    DisplayMemberPath="TagName"
                    TextMemberPath="TagName" />

ユースケース 3：検索可能な従業員ディレクトリ

従業員をすばやく検索できる、フィルタリング機能付きの編集可能なドロップダウン：

⚠️ セキュリティに関する注意： 従業員の写真や外部画像を表示する場合は、信頼できる社内ソースからのみ画像が読み込まれるようにしてください。検証せずに外部URLへバインドしないでください。

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="Contains"
                    PlaceholderText="Search employee..."
                    ItemsSource="{Binding Employees}"
                    DisplayMemberPath="FullName"
                    TextMemberPath="FullName">
    <editors:SfComboBox.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                
                <Ellipse Width="32" Height="32" Margin="8">
                    <Ellipse.Fill>
                        <ImageBrush ImageSource="{Binding PhotoUrl}" />
                    </Ellipse.Fill>
                </Ellipse>
                <StackPanel Grid.Column="1" VerticalAlignment="Center">
                    <TextBlock Text="{Binding FullName}" FontWeight="SemiBold" />
                    <TextBlock Text="{Binding Department}" 
                              FontSize="12" 
                              Foreground="Gray" />
                </StackPanel>
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.ItemTemplate>
</editors:SfComboBox>

ユースケース 4：グループ化されたオプションを含む設定パネル

関連する設定オプションをグループ化します：

<editors:SfComboBox ItemsSource="{Binding Settings}"
                    GroupMemberPath="Category"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.GroupStyle>
        <GroupStyle>
            <GroupStyle.HeaderTemplate>
                <DataTemplate>
                    <TextBlock Text="{Binding Key}" 
                              FontWeight="Bold"
                              Foreground="DarkBlue"
                              Margin="8,4" />
                </DataTemplate>
            </GroupStyle.HeaderTemplate>
        </GroupStyle>
    </editors:SfComboBox.GroupStyle>
</editors:SfComboBox>

ベストプラクティス

1. 複雑なオブジェクトにバインドする場合は、DisplayMemberPath と TextMemberPath の両方を必ず設定してください
2. 項目数が多い場合にユーザーエクスペリエンスを向上させるには、IsEditable="True" と IsFilteringEnabled="True" を使用してください
3. 編集可能モードを使用する場合は、ユーザー入力を検証するために InputSubmitted イベントを処理してください
4. 適切な TextSearchMode を選択してください： 予測しやすいリストには StartsWith、柔軟な検索には Contains を使用します
5. 複数選択にはトークンモードを使用し、スペースに余裕がない場合は区切り文字モードを使用してください
6. 複雑なフィルタリング（複数のプロパティ、あいまい検索など）には、カスタム FilterBehavior を実装してください
7. ユーザーが選択する項目を把握できるように、PlaceholderText を設定してください
8. リアルタイム更新には SelectionChangeTrigger="Always" を使用し、パフォーマンスを優先する場合は Committed を使用してください
9. ユースケースで null の選択が有効な場合は、編集可能モードで AllowNull を有効にしてください
10. 画像、アイコン、複数行のテキストを使って豊かな視覚表現を実現するには、ItemTemplate をカスタマイズしてください