syncfusion-wpf-autocomplete

WPF オートコンプリートの実装（SfTextBoxExt）

インテリジェントなテキスト候補、高度なフィルタリング、複数選択機能、豊富なカスタマイズオプションを提供し、ユーザー入力をより快適にする Syncfusion WPF オートコンプリートコントロール（SfTextBoxExt）の実装ガイドです。

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

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

• オートコンプリートテキストボックスを実装する：予測テキスト候補を表示します
• 検索機能を追加する：フィルタリングされたドロップダウン候補を表示します
• 複数選択を有効にする：トークンまたは区切り文字モードを使用します
• 入力中に候補を表示するフィールドを作成する：インテリジェントなフィルタリングを実装します
• 検索可能なドロップダウンを構築する：カスタムデータソースを使用します
• タグ／トークン選択 UI を実装する：複数の項目を選択できます
• テキスト入力コントロールに候補ボックスを追加する
• 高度なフィルタリングを設定する：18 種類以上のフィルターモードを使用します
• テキスト入力の外観をカスタマイズする：ウォーターマークとテンプレートを使用します
• 選択イベントを処理する：選択された値を取得します
• 発音区別符号を無視した検索に対応する：国際テキストを検索します
• 候補リスト内の一致するテキストを強調表示する

このスキルでは、データバインディング、フィルタリング戦略、選択の処理、ドロップダウンのカスタマイズ、高度な機能など、すべての機能を詳しく解説し、SfTextBoxExt コントロール全体を取り上げます。

コンポーネントの概要

SfTextBoxExt は、標準的な WPF TextBox の機能を拡張し、オートコンプリート機能を備えた強化版 TextBox コントロールです。ユーザーの入力に基づくインテリジェントな候補を表示し、複数のフィルターモードに対応するほか、単一選択と複数選択の両方のシナリオで使用できます。

主な機能

コア機能：

• 18 種類以上のフィルターモード：StartsWith、EndsWith、Contains、Equals、Custom など
• 複数のオートコンプリートモード：Suggest、Append、SuggestAppend
• 複数選択への対応：トークンモードと区切り文字モード
• 豊富なデータバインディング：シンプルなデータ型と複雑なデータ型に対応
• カスタムテンプレート：オートコンプリート項目、ウォーターマーク、結果なしのテンプレート
• イベント駆動型：選択、ポップアップ、候補変更イベント

高度な機能：

• 発音区別符号の感度設定：アクセント記号を無視するフィルタリングで多言語の検索に対応
• テキストの強調表示：一致するテキストを視覚的に示します
• カスタムフィルタリング：複数のパスや複雑なフィルターロジックを実装します
• ポップアップの設定：配置、遅延、高さ、動作を設定します
• パフォーマンスの最適化：プレフィックスの最小文字数、候補の最大数を設定します

UI のカスタマイズ：

• ウォーターマークへの対応：プレースホルダーテキストとカスタムテンプレート
• 視覚スタイル：フォント、色、背景のカスタマイズ
• トークンの外観：画像を含むカスタムトークンテンプレート
• ドロップダウンのスタイル：背景、選択色、項目テンプレート
• ボタンコントロール：オプションのドロップダウンボタンとクリアボタン

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

このスキルでは、段階的に情報を開示する方式を採用しています。まず SKILL.md で概要とナビゲーションを確認し、次に実装の要件に応じて個別のリファレンスファイルを参照してください。

はじめに

📄 読むファイル： references/getting-started.md

参照するタイミング： 初めて SfTextBoxExt を設定するとき、初期実装を行うとき

説明する内容：

• アセンブリの配置と NuGet パッケージのインストール
• SfTextBoxExt を使用した WPF アプリケーションの作成
• デザイナー、XAML、C# によるコントロールの追加
• データソースを使用したオートコンプリート候補の設定
• データモデルと ViewModel のセットアップ
• オートコンプリートモード（Suggest、Append、SuggestAppend、None）
• 基本的な選択の設定
• テーマへの対応とスタイル設定

オートコンプリートとフィルタリング

📄 参照： references/autocomplete-filtering.md

参照するタイミング： フィルタリングロジックを実装する場合、候補の動作をカスタマイズする場合

説明内容：

• AutoCompleteSource プロパティとデータバインディング
• カスタムデータオブジェクト向けの SearchItemPath
• 表示をカスタマイズする AutoCompleteItemTemplate
• SuggestionMode のオプション（StartsWith、EndsWith、Contains、Equals、Custom など、18 種類以上のフィルターモード）
• MinimumPrefixCharacters の設定
• 大文字と小文字を区別しないフィルタリングを行う IgnoreCase
• 画像を表示する ImageMemberPath
• 結果数を制限する MaximumSuggestionsCount
• NoResultsFoundTemplate のカスタマイズ
• 手動でフィルタリングする FilterSuggestions メソッド
• SuggestionsChanged イベントの処理

選択と値の取得

📄 参照： references/selection.md

参照するタイミング： 単一選択または複数選択を実装する場合、選択した値を取得する場合

説明内容：

• MultiSelectMode のオプション（None、Token、Delimiter）
• 単一選択用の SelectedItem プロパティ
• 複数選択用の SelectedItems コレクション
• トークンの表示とレイアウト
• TokensWrapMode（Wrap、None）の設定
• 動的な高さ調整を行う EnableAutoSize
• カスタム区切り文字を使用する Delimiter モード
• Delimiter プロパティの設定
• SelectedValue と ValueMemberPath
• 選択項目のインデックスを示す SuggestionIndex
• トークン画像用の ImageMemberPath
• SelectedItemChanged イベントの処理

ドロップダウンのカスタマイズ

📄 参照： references/dropdown-customization.md

参照するタイミング： 候補ポップアップの外観や動作をカスタマイズする場合

説明内容：

• 候補ボックスのスタイルを設定する DropDownBackground
• SuggestionBoxPlacement のオプション（Bottom、Top、None）
• MaximumDropDownHeight の設定
• ShowSuggestionsOnFocus の動作
• 表示を遅らせる PopupDelay
• 選択項目用の SelectionBackgroundColor
• AutoHighlightMatchedItem API
• SuggestionPopupOpened イベント
• SuggestionPopupClosed イベント
• ドロップダウンのスタイル設定例

TextBox のカスタマイズ

📄 参照： references/textbox-customization.md

参照するタイミング： TextBox の外観をカスタマイズする場合、ウォーターマークやボタンを追加する場合

説明内容：

• プレースホルダーテキスト用の Watermark プロパティ
• カスタムのプレースホルダー UI 用の WatermarkTemplate
• テキストのスタイル設定（FontSize、FontWeight、FontFamily）
• ドロップダウンアイコンを表示する ShowDropDownButton
• クリア機能を追加する ShowClearButton
• 外観をカスタマイズするパターン
• テンプレートのカスタマイズ例

高度な機能

📄 参照： references/advanced-features.md

参照するタイミング： 発音区別符号を考慮した検索、テキストのハイライト表示、カスタムフィルターを実装する場合

説明内容：

• IgnoreDiacritic による発音区別符号の扱い
• TextHighlightMode（FirstOccurrence、MultiOccurrence）
• HighlightedTextColor の設定
• HighlightedTextStyle のカスタマイズ
• 複数パス検索の実装
• カスタム SuggestionMode の設定
• カスタムフィルタリングロジック用の Filter プロパティ
• カスタムフィルターの実装例
• リソースをクリーンアップする Dispose メソッド
• パフォーマンス最適化のヒント

クイックスタートの例

候補を表示する基本的なオートコンプリート

<Window xmlns:editors="http://schemas.syncfusion.com/wpf">
    <Window.DataContext>
        <local:EmployeeViewModel/>
    </Window.DataContext>
    
    <editors:SfTextBoxExt 
        Width="300"
        Height="40"
        Watermark="Search employees..."
        SearchItemPath="Name"
        AutoCompleteMode="Suggest"
        SuggestionMode="Contains"
        AutoCompleteSource="{Binding Employees}" />
</Window>

// ViewModel
public class EmployeeViewModel
{
    public List<Employee> Employees { get; set; }
    
    public EmployeeViewModel()
    {
        Employees = new List<Employee>
        {
            new Employee { Name = "John Doe", Email = "[email protected]" },
            new Employee { Name = "Jane Smith", Email = "[email protected]" },
            new Employee { Name = "Mike Johnson", Email = "[email protected]" }
        };
    }
}

// Model
public class Employee
{
    public string Name { get; set; }
    public string Email { get; set; }
}

トークンを使用した複数選択

<editors:SfTextBoxExt 
    Width="400"
    Height="60"
    Watermark="Select multiple items..."
    SearchItemPath="Name"
    AutoCompleteMode="Suggest"
    MultiSelectMode="Token"
    TokensWrapMode="Wrap"
    EnableAutoSize="True"
    AutoCompleteSource="{Binding Items}" />

// Code-behind
var textBoxExt = new SfTextBoxExt
{
    Width = 400,
    Watermark = "Select multiple items...",
    SearchItemPath = "Name",
    AutoCompleteMode = AutoCompleteMode.Suggest,
    MultiSelectMode = MultiSelectMode.Token,
    TokensWrapMode = TokensWrapMode.Wrap,
    EnableAutoSize = true,
    AutoCompleteSource = viewModel.Items
};

よくあるパターン

パターン 1：大文字と小文字を区別しない検索を行う基本的なオートコンプリート

var autoComplete = new SfTextBoxExt
{
    AutoCompleteMode = AutoCompleteMode.Suggest,
    SuggestionMode = SuggestionMode.Contains,
    IgnoreCase = true,
    MinimumPrefixCharacters = 2,
    AutoCompleteSource = GetDataSource()
};

パターン 2：イベント処理を伴う複数選択

<editors:SfTextBoxExt 
    SearchItemPath="Name"
    AutoCompleteMode="Suggest"
    MultiSelectMode="Token"
    SelectedItemChanged="OnSelectedItemChanged"
    AutoCompleteSource="{Binding Items}" />

private void OnSelectedItemChanged(object sender, SelectedItemChangedEventArgs e)
{
    var selectedItems = (sender as SfTextBoxExt)?.SelectedItems;
    // Handle selected items
    foreach (var item in selectedItems)
    {
        Console.WriteLine(item.ToString());
    }
}

パターン 3：カスタムフィルタリング

var autoComplete = new SfTextBoxExt
{
    SuggestionMode = SuggestionMode.Custom,
    AutoCompleteSource = employees
};

// Custom filter for multi-field search
autoComplete.Filter = (search, item) =>
{
    if (item is Employee emp)
    {
        return emp.Name.Contains(search, StringComparison.OrdinalIgnoreCase) ||
               emp.Email.Contains(search, StringComparison.OrdinalIgnoreCase) ||
               emp.Department.Contains(search, StringComparison.OrdinalIgnoreCase);
    }
    return false;
};

パターン 4：ポップアップの設定

<editors:SfTextBoxExt 
    AutoCompleteMode="Suggest"
    ShowSuggestionsOnFocus="True"
    PopupDelay="00:00:00.3"
    MaxDropDownHeight="200"
    SuggestionBoxPlacement="Bottom"
    AutoHighlightMatchedItem="True"
    AutoCompleteSource="{Binding Data}" />

主要なプロパティのリファレンス

主なプロパティ

プロパティ	型	説明
AutoCompleteSource	IEnumerable	候補のデータソース
SearchItemPath	string	カスタムオブジェクトをフィルタリングするためのプロパティパス
AutoCompleteMode	AutoCompleteMode	候補の表示モード（Suggest、Append、SuggestAppend、None）
SuggestionMode	SuggestionMode	フィルタリング方法（StartsWith、Contains、Equals など）
MultiSelectMode	MultiSelectMode	選択モード（None、Token、Delimiter）
SelectedItem	object	現在選択されている項目（単一選択）
SelectedItems	ObservableCollection<object>	選択されている項目（複数選択）
SelectedValue	object	選択されている項目の値

設定プロパティ

プロパティ	型	デフォルト値	説明
MinimumPrefixCharacters	int	1	フィルタリングを開始するまでに必要な最小文字数
IgnoreCase	bool	false	大文字と小文字を区別しないフィルタリング
MaximumSuggestionsCount	int	0 (無制限)	表示する候補の最大数
ShowSuggestionsOnFocus	bool	false	フォーカス時にすべての候補を表示
PopupDelay	TimeSpan	00:00:00	ポップアップが開くまでの遅延時間
MaxDropDownHeight	double	自動	ポップアップの最大高さ

カスタマイズプロパティ

プロパティ	型	説明
Watermark	string	プレースホルダーテキスト
WatermarkTemplate	DataTemplate	カスタムプレースホルダーテンプレート
AutoCompleteItemTemplate	DataTemplate	カスタム候補項目テンプレート
NoResultsFoundTemplate	DataTemplate	一致する項目が見つからない場合のテンプレート
ShowDropDownButton	bool	ドロップダウンボタンを表示
ShowClearButton	bool	クリアボタンを表示

イベント

イベント	説明
SelectedItemChanged	選択項目が変更されたときに発生します
SuggestionsChanged	フィルタリングされた候補が更新されたときに発生します
SuggestionPopupOpened	ポップアップが開いたときに発生します
SuggestionPopupClosed	ポップアップが閉じたときに発生します

一般的なユースケース

1. 従業員の検索と選択

複数のフィールドでフィルタリングして、名前、メールアドレス、または部署から従業員を検索するオートコンプリートを実装します。

2. タグ／ラベルの選択

トークンモードで複数選択を有効にし、視覚的なトークン表示でタグ、カテゴリ、またはラベルを選択できるようにします。

3. 製品検索

画像、カスタムテンプレート、豊富な項目表示を備えた、検索可能な製品ドロップダウンを作成します。

4. メールの宛先（To／CC／BCC）

トークンモード、区切り文字のサポート、連絡先候補を備えたメール宛先の選択機能を構築します。

5. 場所の検索

住所候補を表示し、国際的な住所を検索する際に発音区別符号を区別しない検索ができる場所のオートコンプリートを実装します。

6. コードエディターの自動補完

構文の強調表示、カスタムフィルタリング、キーボード操作に対応したコード候補のドロップダウンを作成します。

7. フォームの自動入力

過去のデータや事前定義された選択肢に基づく、インテリジェントなフォーム入力候補を追加します。

8. 多言語検索

国際的なコンテンツを対象に、アクセント記号を区別しない照合が可能な、発音区別符号に対応した検索を実装します。

関連リソース

• Syncfusion のドキュメント： https://help.syncfusion.com/wpf/autocomplete/overview
• API リファレンス： https://help.syncfusion.com/cr/wpf/Syncfusion.Windows.Controls.Input.SfTextBoxExt.html
• サンプルブラウザー： Syncfusion Control Panel から利用できます
• GitHub サンプル： https://github.com/SyncfusionExamples/wpf-textboxext-examples

サポートとライセンス

SfTextBoxExt は Syncfusion Essential Studio for WPF の一部であり、有効なライセンスが必要な商用製品です。ライセンス情報については、https://www.syncfusion.com/sales/products をご覧ください。

---

次のステップ： 実装のニーズに応じて、該当するリファレンスファイルに進んでください。初期設定については getting-started.md から始めるか、高度なシナリオ向けの機能別ガイドに直接進んでください。