syncfusion-winui-autocomplete

AutoComplete の実装（SfAutoComplete）

Syncfusion WinUI AutoComplete（SfAutoComplete）は、ユーザーの入力に応じて大規模なデータセットから候補を絞り込む、高度に最適化されたコントロールです。単一選択と複数選択の両方に対応しており、選択した項目を画像、テキスト、削除用の閉じるボタン付きのトークンとして表示できます。

このスキルを使用するタイミング

次のようなニーズがある場合は、このスキルを使用してください。

• WinUI アプリケーションにオートコンプリート検索機能を実装する
• ユーザー入力に基づいて候補を絞り込む、検索可能なドロップダウンを作成する
• 複数選択が可能なタグまたはトークン入力フィールドを構築する
• ユーザーが入力した文字に基づいて大規模なデータセットを絞り込む
• 入力中に候補を表示する検索体験を提供する
• チップ／トークン表示に対応した複数選択ドロップダウンを実装する
• 検索フィールドでユーザーの入力を促す透かしテキストを追加する
• 画像やカスタムテンプレートを使って候補項目の表示をカスタマイズする
• 「結果が見つかりません」シナリオをカスタムメッセージで処理する
• オートコンプリート入力欄に先頭／末尾のアイコンやボタンを追加する

コンポーネントの概要

パッケージ： Syncfusion.Editors.WinUI
名前空間： Syncfusion.UI.Xaml.Editors
コントロール： SfAutoComplete

主な機能：

• 単一選択モードと複数選択モード
• リアルタイムのフィルタリング（StartsWith または Contains）
• カスタムフィルタリングロジックのサポート
• 選択項目をトークン／チップとして表示
• 一致したテキストのハイライト表示
• 候補のグループ化
• 先頭および末尾のビュー
• 透かし／プレースホルダーテキスト
• キーボード操作
• テンプレートのカスタマイズ

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

はじめに

📄 参照： references/getting-started.md

次のようなニーズがある場合：

• AutoComplete パッケージをインストールする
• コントロールを作成して構成する
• ItemsSource を使ったデータバインディングを設定する
• TextMemberPath と DisplayMemberPath を構成する
• 基本的なオートコンプリート機能を実装する

選択

📄 参照： references/selection.md

次のようなニーズがある場合：

• 単一選択と複数選択を構成する
• 選択項目をプログラムから処理する
• 複数選択した項目をトークン／チップとして表示する
• 選択変更イベントを監視する
• SelectedItem プロパティまたは SelectedItems プロパティを使用する

検索とフィルタリング

📄 参照： references/searching-filtering.md

次のようなニーズがある場合：

• フィルタリング動作（StartsWith または Contains）を構成する
• カスタムフィルタリングロジックを実装する
• 特定のプロパティに基づいて検索する
• オートフィルと自動候補表示を処理する
• フィルタリング後に既定の項目を選択する

UI のカスタマイズ

📄 参照： references/ui-customization.md

次のようなニーズがある場合：

• ドロップダウン項目のテンプレートをカスタマイズする
• 先頭にアイコンやボタンを追加する
• 末尾にアクションやクリアボタンを追加する
• 選択項目のトークンのスタイルを設定する
• 「結果が見つかりません」UI を処理する
• 透かし／プレースホルダーテキストを設定する

高度な機能

📄 参照： references/advanced-features.md

次のようなニーズがある場合：

• カテゴリごとに候補をグループ化する
• 候補内の一致したテキストをハイライト表示する
• キーボードショートカットを実装する
• アクセシビリティ要件への準拠を確保する
• 高度なユーザー操作に対応する

クイックスタートの例

基本的な単一選択 AutoComplete

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfAutoComplete x:Name="autoComplete"
                                Width="250"
                                PlaceholderText="Search social media..."
                                ItemsSource="{Binding SocialMedias}"
                                DisplayMemberPath="Name"
                                TextMemberPath="Name"
                                TextSearchMode="Contains" />
    </Grid>
</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 = "Instagram", ID = 1 },
            new SocialMedia { Name = "Twitter", ID = 2 },
            new SocialMedia { Name = "LinkedIn", ID = 3 }
        };
    }
}

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

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

<editors:SfAutoComplete x:Name="autoComplete"
                        Width="300"
                        SelectionMode="Multiple"
                        PlaceholderText="Select multiple items..."
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains" />

一般的なパターン

パターン 1：Contains フィルターを使った検索

<editors:SfAutoComplete ItemsSource="{Binding Countries}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        TextSearchMode="Contains"
                        PlaceholderText="Type to search..." />

テキストの先頭だけでなく、テキストの任意の部分で項目を検索する必要がある場合に使用します。

パターン 2：カスタム表示を使った複数選択タグ

<editors:SfAutoComplete SelectionMode="Multiple"
                        ItemsSource="{Binding Tags}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Padding="5">
                <TextBlock Text="{Binding Name}" 
                          FontWeight="SemiBold"/>
            </StackPanel>
        </DataTemplate>
    </editors:SfAutoComplete.ItemTemplate>
</editors:SfAutoComplete>

複数の項目を選択し、トークンとして表示するタグ付けシステムで使用します。

パターン 3：先頭にアイコンを配置したオートコンプリート

<editors:SfAutoComplete ItemsSource="{Binding Items}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
    <editors:SfAutoComplete.LeadingView>
        <Grid Padding="8">
            <Path Data="M15.5 14h-.79l-.28-.27C15.41..." 
                  Fill="{ThemeResource SystemAccentColor}"/>
        </Grid>
    </editors:SfAutoComplete.LeadingView>
</editors:SfAutoComplete>

オートコンプリートフィールドに視覚的な手がかり（検索アイコンなど）を加える場合に使用します。

パターン 4：カスタムの「結果が見つかりません」メッセージ

<editors:SfAutoComplete ItemsSource="{Binding Products}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name"
                        NoResultsFoundContent="No products found. Try a different search." />

フィルタリングで一致する項目が見つからない場合に、役立つフィードバックを表示するために使用します。

主なプロパティ

プロパティ	型	説明
ItemsSource	object	表示するデータ項目のコレクション
DisplayMemberPath	string	ドロップダウン項目の表示に使用するプロパティパス
TextMemberPath	string	選択ボックスのテキストに使用するプロパティパス
SelectionMode	AutoCompleteSelectionMode	Single または Multiple で選択
TextSearchMode	AutoCompleteTextSearchMode	StartsWith または Contains によるフィルタリング
PlaceholderText	string	空のときに表示するウォーターマークテキスト
SelectedItem	object	現在選択されている項目（単一選択モード）
SelectedItems	ObservableCollection	選択項目のコレクション（複数選択モード）
NoResultsFoundContent	object	一致する項目が見つからないときのコンテンツ
LeadingView	object	テキスト入力の前に表示するコンテンツ
TrailingView	object	テキスト入力の後に表示するコンテンツ
GroupMemberPath	string	項目のグループ化に使用するプロパティパス
HighlightedTextColor	Brush	一致したテキストを強調表示する色
FilterBehavior	AutoCompleteFilterBehavior	カスタムフィルタリングロジック

一般的なユースケース

メール受信者の選択

連絡先リストからメール受信者を選択する複数選択オートコンプリートです。選択した連絡先は、削除可能なトークンとして表示されます。

製品検索

EC アプリで製品を検索する単一選択オートコンプリートです。柔軟に検索できるよう、部分一致によるフィルタリングを行います。

カテゴリのタグ付け

項目に複数のカテゴリやタグを割り当てる複数選択オートコンプリートです。トークンの表示をカスタマイズできます。

場所の検索

グループ化された候補（国 > 都市）を使用する単一選択オートコンプリートです。すばやく移動できるよう、StartsWith によるフィルタリングを行います。

スキル検索

定義済みリストからユーザーのスキルを選択する複数選択オートコンプリートです。認識されない入力には「結果なし」のメッセージを表示します。

関連コンポーネント

• ComboBox - オートコンプリートフィルタリングを使わないシンプルなドロップダウン選択向け
• TextBox - 候補を表示しない基本的なテキスト入力向け（ドキュメントがある場合）

統合のヒント

MVVM との連携:

• ItemsSource を ViewModel の ObservableCollection にバインドします
• SelectedItem または SelectedItems を双方向バインディングで使用します
• バインディングコマンドを使用して、ViewModel で選択の変更を処理します

パフォーマンス:

• 大規模なデータセット（1000 項目超）には仮想化を使用します
• リモートのデータソースでは非同期読み込みを検討します
• 非常に大きなリストでパフォーマンスを向上させるには、TextSearchMode.StartsWith を使用します

アクセシビリティ:

• ユーザーを案内するため、必ず PlaceholderText を設定します
• スクリーンリーダー向けに AutomationProperties.Name を使用します
• キーボード操作（Tab、Enter、Esc）が機能することを確認します
• ハイコントラストテーマでテストします

トラブルシューティングの簡単な解決方法

問題	解決方法
候補が表示されない	ItemsSource がバインドされ、データが含まれていることを確認します。DisplayMemberPath も確認します
表示されるテキストが違う	TextMemberPath に正しいプロパティ名を設定します
フィルタリングが機能しない	TextSearchMode が設定されていることを確認します。プロパティのデータ型が文字列であることも確認します
複数選択が機能しない	SelectionMode="Multiple" を設定します
カスタムテンプレートが適用されない	ItemTemplate の DataContext バインディングがデータモデルと一致していることを確認します
結果なしのメッセージが表示されない	NoResultsFoundContent プロパティを設定します

---

次のステップ: 詳細な実装については、上記のドキュメントガイドを使用して、ニーズに合った個別のリファレンスファイルに移動してください。