syncfusion-winforms-autocomplete

Syncfusion WinForms AutoComplete コントロール

AutoComplete コントロールは、Windows Forms アプリケーションのテキスト入力フィールドに自動候補表示機能を提供します。ユーザーが入力すると候補のドロップダウンリストを表示し、インテリジェントなテキスト補完によってデータ入力を高速化し、ユーザーエクスペリエンスを向上させます。

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

次のような場合に AutoComplete コントロールを使用します。

• テキスト入力フィールドに自動候補表示を追加する
• 入力中の検索機能を実装する
• インテリジェントな候補を表示する検索ボックスを作成する
• URL やメールアドレスの自動補完を有効にする
• 頻繁に繰り返される入力を含むフォームを構築する
• 大規模なデータセットから候補を絞り込んで表示する
• 複数列表示を備えたカスタムドロップダウン動作を実装する

インストール

NuGet によるインストール

Install-Package Syncfusion.Tools.Windows

アセンブリ参照

次の参照を追加します。

• Syncfusion.Tools.Windows.dll
• Syncfusion.Shared.Base.dll

クイックスタート

基本設定

using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

namespace AutoCompleteDemo
{
    public partial class Form1 : Form
    {
        private AutoComplete autoComplete1;
        private TextBox textBox1;

        public Form1()
        {
            InitializeComponent();
            
            // Create AutoComplete control
            autoComplete1 = new AutoComplete();
            textBox1 = new TextBox();
            textBox1.Location = new System.Drawing.Point(20, 20);
            textBox1.Size = new System.Drawing.Size(200, 20);
            autoComplete1.ParentForm = this;
            
            // Add data source
            autoComplete1.DataSource = new string[] 
            { 
                "Australia", 
                "Austria", 
                "Brazil", 
                "Canada", 
                "China" 
            };
            autoComplete1.SetAutoComplete(textBox1, AutoCompleteModes.AutoSuggest);

            // Add to form
            this.Controls.Add(textBox1);
        }
    }
}

デザイナーでの設定

1. ツールボックスから AutoComplete コントロールをフォームにドラッグします
2. ParentForm プロパティを現在のフォームに設定します
3. プロパティウィンドウまたはコードから DataSource を設定します
4. プロパティを使って外観と動作をカスタマイズします

基本概念

データソース

AutoComplete コントロールは、さまざまなデータソースにバインドできます。

• 文字列配列
• ジェネリックコレクション（List、ArrayList）
• DataTable および DataSet
• IList インターフェイスを備えたカスタムオブジェクト

親フォーム

候補のドロップダウンリストを表示するには、ParentForm プロパティを設定する必要があります。これにより、AutoComplete が親フォームのコンテナーに関連付けられます。

フィルタリング

組み込みのフィルタリング機能により、ユーザーの入力がデータソースと自動的に照合され、入力に応じて関連する候補が表示されます。

ナビゲーションガイド

🚀 はじめに

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

• インストールとアセンブリ参照
• WinForms アプリケーションの作成
• デザイナーを使った AutoComplete コントロールの追加
• コードによる AutoComplete コントロールの追加
• 基本的な構成とセットアップ
• アプリケーションの実行

📊 データソースの操作

📄 参照先： references/datasource.md

• 文字列コレクションへのバインド
• DataTable および DataSet へのバインド
• カスタムオブジェクトへのバインド
• 複数のデータソース
• デザイン時のデータソース設定
• 動的なデータソースの更新

🎨 カスタマイズ

📄 参照先： references/customization.md

• ビジュアルスタイルとテーマ
• フォントと色のカスタマイズ
• 境界線のスタイル
• ドロップダウンの外観
• 自動サイズ設定
• ドロップダウン内の列の外観
• 一致するテキストの強調表示
• カスタム描画

🔧 AutoComplete の操作

📄 参照先： references/working-with-autocomplete.md

• 自動補完モード（Suggest、Append、SuggestAppend）
• 文字の大文字・小文字の設定
• 読み込み時の動作
• 自動入力
• 既定の候補
• 値のクリアとリセット
• プログラムによる選択

📑 複数列のドロップダウン

📄 参照先： references/multicolumn-dropdown.md

• 複数列モードの有効化
• 列の設定
• 列ヘッダー
• 列幅とサイズ設定
• 複数のフィールドの表示
• カスタム列の書式設定
• ドロップダウン項目内の画像
• グリッド風の外観

⚡ イベント

📄 参照先： references/autocomplete-events.md

• AutoCompleteCustomize イベント
• AutoCompleteValueChanged イベント
• BeforeCustomization イベント
• ユーザーによる選択の処理
• 入力の検証
• カスタムイベントハンドラー

🎯 概要

📄 参照先： references/overview.md

• 機能の概要
• ユースケースとシナリオ
• コンポーネントのアーキテクチャ
• パフォーマンスに関する考慮事項
• ベストプラクティス

よく使われるパターン

パターン 1：シンプルな文字列の AutoComplete

AutoComplete autoComplete1 = new AutoComplete();
TextBox textBox1 = new TextBox();
textBox1.Location = new System.Drawing.Point(20, 20);
textBox1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;

autoComplete1.SetAutoComplete(textBox1, AutoCompleteModes.AutoSuggest);

// Add string data
autoComplete1.DataSource = new string[] 
{
    "John", "Jane", "Bob", "Alice", "Charlie"
};

this.Controls.Add(textBox1);

パターン 2：DataTable へのバインド

AutoComplete autoComplete1 = new AutoComplete();
TextBox textBox1 = new TextBox();
textBox1.Location = new System.Drawing.Point(20, 50);
textBox1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;

// Create DataTable
DataTable dt = new DataTable();
dt.Columns.Add("Name", typeof(string));
dt.Columns.Add("Email", typeof(string));
dt.Rows.Add("John Doe", "[email protected]");
dt.Rows.Add("Jane Smith", "[email protected]");

autoComplete1.DataSource = dt;

this.Controls.Add(textBox1);

パターン 3：複数列の表示

AutoComplete autoComplete1 = new AutoComplete();
TextBox textBox1 = new TextBox();
textBox1.Location = new System.Drawing.Point(20, 50);
textBox1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;
autoComplete1.Style = AutoCompleteStyle.Default;

// Create DataTable with multiple columns
DataTable dt = new DataTable();
dt.Columns.Add("Name", typeof(string));
dt.Columns.Add("Country", typeof(string));
dt.Columns.Add("City", typeof(string));

dt.Rows.Add("John Doe", "USA", "New York");
dt.Rows.Add("Jane Smith", "UK", "London");
dt.Rows.Add("Bob Johnson", "Canada", "Toronto");

autoComplete1.DataSource = dt;

// Configure columns
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("Name", 100, true));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("Country", 80, true));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("City", 80, true));

this.Controls.Add(textBox1);

パターン 4：イベントによるカスタムフィルタリング

AutoComplete autoComplete1 = new AutoComplete();
TextBox textBox1 = new TextBox();
textBox1.Location = new System.Drawing.Point(20, 50);
textBox1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;
autoComplete1.DataSource = GetDataSource();
// Attach AutoComplete to the TextBox
autoComplete1.SetAutoComplete(textBox1, AutoCompleteModes.AutoSuggest);

// Subscribe when the dropdown is displayed so the popup list is initialized
autoComplete1.DropDownDisplayed += (s, e) =>
{
    var lv = autoComplete1.AutoCompletePopup.Controls[0] as VirtualListView;
    if (lv != null)
    {
        lv.DrawItem -= ItemsListView_DrawItem;
        lv.DrawItem += ItemsListView_DrawItem;
    }
};

void ItemsListView_DrawItem(object sender, DrawListViewItemEventArgs e)
{
    if (e.Item != null)
    {
        e.DrawBackground();
        var text = e.Item.Text;
        using (var brush = new SolidBrush(e.Item.ForeColor))
        {
            e.Graphics.DrawString(text, e.Item.Font ?? e.Item.ListView.Font, brush, e.Bounds);
        }
        e.DrawFocusRectangle();
    }
}

this.Controls.Add(textBox1);

パターン 5：URL／メールアドレスの AutoComplete

AutoComplete autoComplete1 = new AutoComplete();
TextBox textBox1 = new TextBox();
textBox1.Location = new System.Drawing.Point(20, 50);
textBox1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;
// Common URLs
autoComplete1.DataSource = new string[]
{
    "http://www.syncfusion.com",
    "http://www.google.com",
    "http://www.microsoft.com",
    "http://www.github.com"
};

// Enable append mode for URL completion
autoComplete1.SetAutoComplete(textBox1, AutoCompleteModes.Both);

this.Controls.Add(textBox1);

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

プロパティ	型	既定値	説明
DataSource	object	null	候補のデータソース（配列、DataTable など）
ParentForm	Form	null	コントロールを含む親フォーム（必須）
AutoCompleteMode	AutoCompleteMode	Suggest	動作モード：None、Suggest、Append、SuggestAppend
DisplayMember	string	""	データソースから表示するプロパティ名
ValueMember	string	""	内部値に使用するプロパティ名
Columns	AutoCompleteDataColumnInfoCollection	-	複数列表示の列設定
Style	AutoCompleteStyle	Default	コントロールのビジュアルスタイル
Text	string	""	現在のテキスト値
SelectedValue	object	null	現在選択されている値
CharacterCasing	CharacterCasing	Normal	テキストの大文字・小文字：Normal、Upper、Lower
LoadOnDemand	bool	false	必要に応じて候補を読み込みます
AutoCompleteControl	AutoCompletePopup	-	基盤となるポップアップコントロールにアクセスします

イベント

AutoComplete コントロールの一般的なイベント：

• AutoCompleteValueChanged：選択された値が変更されたときに発生します
• AutoCompleteCustomize：ドロップダウンリストを表示する前に発生します
• BeforeCustomization：カスタマイズを適用する前に発生します
• TextChanged：テキストの内容が変更されたときに発生します
• SelectedIndexChanged：選択が変更されたときに発生します
• GotFocus：コントロールがフォーカスを受け取ったときに発生します
• LostFocus：コントロールがフォーカスを失ったときに発生します

ベストプラクティス

1. ParentForm は必ず設定する：ドロップダウンを正しく動作させるには、ParentForm プロパティが必須です

2. 適切なモードを使用する：適切な AutoCompleteMode を選択します：

   • Suggest：ドロップダウンのみを表示します
   • Append：テキストのみを自動補完します
   • SuggestAppend：ドロップダウン表示とテキスト補完の両方を行います

3. 大規模なデータセットを最適化する：パフォーマンスを向上させるには、大規模なデータソースで LoadOnDemand を使用します

4. 複雑なデータには複数列を使用する：関連情報を表示する場合は、複数列表示を使用します

5. イベントを適切に処理する：ユーザーの選択に対応するには、AutoCompleteValueChanged を使用します

6. データを適切にクリアする：候補をクリアするには、ResetItems() を呼び出すか、DataSource = null を設定します

7. 文字の大文字・小文字を考慮する：データの種類に応じて CharacterCasing を設定します（例：州コードには Upper）

8. テーマの一貫性を保つ：すべての Syncfusion コントロールで、統一感のあるビジュアルスタイルを使用します

ビジュアルスタイル

このコントロールは、複数のビジュアルテーマに対応しています：

• Default
• Office2016Colorful
• Office2016White
• Office2016Black
• Office2016DarkGray
• Metro
• Office2007
• Office2010
• VS2010

autoComplete1.Style = AutoCompleteStyle.Office2016Colorful;

フレームワークのサポート

• .NET Framework 4.5 以降
• .NET 6.0、.NET 7.0、.NET 8.0（Windows）
• .NET Core 3.1（Windows）

追加リソース

• Syncfusion AutoComplete のドキュメント
• API リファレンス
• ナレッジベースの記事
• GitHub のサンプル

トラブルシューティング

問題：ドロップダウンが表示されない

• ParentForm プロパティが設定されていることを確認します
• DataSource に有効なデータが含まれていることを確認します
• コントロールがフォームの Controls コレクションに追加されていることを確認します

問題：複数列が表示されない

• 適切な AutoCompleteStyle を設定します
• Columns コレクションに列を追加します
• DataSource に対応する列名があることを確認します

問題：大規模なデータセットでパフォーマンスに問題がある

• LoadOnDemand プロパティを有効にします
• 表示する列の数を減らします
• バインドする前にデータソースをフィルターすることを検討します

問題：スタイルが適用されない

• Syncfusion のテーマ DLL が参照されていることを確認します
• DataSource の設定後にスタイルを適用します
• 競合するカスタム描画コードがないか確認します