syncfusion-winforms-autocomplete（同步融合 winform 自动完成）

Syncfusion WinForms AutoComplete Control

The AutoComplete control provides auto-suggestion functionality for text input fields in Windows Forms applications. It displays a dropdown list of suggestions as users type, enabling faster data entry and improved user experience with intelligent text completion.

When to Use This Skill

Use the AutoComplete control when you need to:

• Add auto-suggestion to text input fields
• Implement type-ahead search functionality
• Create search boxes with intelligent suggestions
• Enable URL or email address autocomplete
• Build forms with frequently repeated input
• Provide filtered suggestions from large datasets
• Implement custom dropdown behaviors with multi-column displays

Installation

NuGet Installation

Install-Package Syncfusion.Tools.Windows

Assembly Reference

Add reference to:

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

Quick Start

Basic Setup

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);
        }
    }
}

Designer Setup

1. Drag AutoComplete control from Toolbox to Form
2. Set the ParentForm property to current form
3. Configure DataSource through Properties window or code
4. Customize appearance and behavior through Properties

Core Concepts

Data Source

The AutoComplete control can bind to various data sources:

• String arrays
• Generic collections (List, ArrayList)
• DataTable and DataSet
• Custom objects with IList interface

Parent Form

The ParentForm property must be set to enable the control to display the dropdown suggestion list. This associates the AutoComplete with the parent form's container.

Filtering

Built-in filtering automatically matches user input against the data source, displaying relevant suggestions as the user types.

Navigation Guide

🚀 Getting Started

📄 Read: references/getting-started.md

• Installation and assembly references
• Creating WinForms application
• Adding AutoComplete control via Designer
• Adding AutoComplete control programmatically
• Basic configuration and setup
• Running the application

📊 Working with Data Sources

📄 Read: references/datasource.md

• Binding to string collections
• Binding to DataTable and DataSet
• Binding to custom objects
• Multiple data sources
• Setting data source at design time
• Dynamic data source updates

🎨 Customization

📄 Read: references/customization.md

• Visual styles and themes
• Font and color customization
• Border styles
• Dropdown appearance
• Auto-size configuration
• Column appearance in dropdown
• Highlight matching text
• Custom rendering

🔧 Working with AutoComplete

📄 Read: references/working-with-autocomplete.md

• Auto-complete modes (Suggest, Append, SuggestAppend)
• Character casing
• Loading behavior
• Auto-population
• Default suggestions
• Clearing and resetting values
• Programmatic selection

📑 Multi-Column Dropdown

📄 Read: references/multicolumn-dropdown.md

• Enabling multi-column mode
• Column configuration
• Column headers
• Column width and sizing
• Displaying multiple fields
• Custom column formatting
• Images in dropdown items
• Grid-like appearance

⚡ Events

📄 Read: references/autocomplete-events.md

• AutoCompleteCustomize event
• AutoCompleteValueChanged event
• BeforeCustomization event
• Handling user selections
• Validating input
• Custom event handlers

🎯 Overview

📄 Read: references/overview.md

• Feature overview
• Use cases and scenarios
• Component architecture
• Performance considerations
• Best practices

Common Patterns

Pattern 1: Simple String 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);

Pattern 2: DataTable Binding

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", "john@example.com");
dt.Rows.Add("Jane Smith", "jane@example.com");

autoComplete1.DataSource = dt;

this.Controls.Add(textBox1);

Pattern 3: Multi-Column Display

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);

Pattern 4: Custom Filtering with Events

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);

Pattern 5: URL/Email 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);

Key Properties Reference

Events

Common events for the AutoComplete control:

• AutoCompleteValueChanged: Triggered when selected value changes
• AutoCompleteCustomize: Before displaying the dropdown list
• BeforeCustomization: Before applying customization
• TextChanged: When text content changes
• SelectedIndexChanged: When selection changes
• GotFocus: When control receives focus
• LostFocus: When control loses focus

Best Practices

1. Always Set ParentForm: The ParentForm property is mandatory for the dropdown to work properly
2. Use Appropriate Mode: Choose the right AutoCompleteMode:

- Suggest: Show dropdown only - Append: Auto-complete text only - SuggestAppend: Both dropdown and text completion

1. Optimize Large Datasets: Use LoadOnDemand for large data sources to improve performance
2. Multi-Column for Complex Data: Use multi-column display when showing related information
3. Handle Events Properly: Use AutoCompleteValueChanged to respond to user selections
4. Clear Data Appropriately: Call ResetItems() or set DataSource = null to clear suggestions
5. Consider Character Casing: Set CharacterCasing based on data type (e.g., Upper for state codes)
6. Theme Consistency: Use matching visual styles across all Syncfusion controls

Visual Styles

The control supports multiple visual themes:

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

autoComplete1.Style = AutoCompleteStyle.Office2016Colorful;

Framework Support

• .NET Framework 4.5 and above
• .NET 6.0,.NET 7.0,.NET 8.0 (Windows)
• .NET Core 3.1 (Windows)

Additional Resources

• Syncfusion AutoComplete Documentation
• API Reference
• Knowledge Base Articles
• GitHub Samples

Troubleshooting

Issue: Dropdown doesn't appear

• Ensure ParentForm property is set
• Check that DataSource contains valid data
• Verify control is added to form's Controls collection

Issue: Multi-column not displaying

• Set appropriate AutoCompleteStyle
• Add columns to Columns collection
• Ensure DataSource has matching column names

Issue: Performance issues with large datasets

• Enable LoadOnDemand property
• Reduce the number of columns displayed
• Consider filtering data source before binding

Issue: Styling not applied

• Ensure Syncfusion theme DLLs are referenced
• Apply style after setting DataSource
• Check for conflicting custom drawing code