syncfusion-winforms-autocomplete

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion WinForms AutoComplete Control

Syncfusion WinForms AutoComplete 控件

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.
AutoComplete控件可为Windows Forms应用中的文本输入字段提供自动建议功能,它会在用户输入时展示下拉建议列表,通过智能文本补全加快数据录入速度,提升用户体验。

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
当你需要实现以下需求时可使用AutoComplete控件:
  • 为文本输入字段添加自动建议功能
  • 实现预输入搜索功能
  • 创建带智能建议的搜索框
  • 支持URL或邮箱地址自动补全
  • 构建包含高频重复输入内容的表单
  • 为大型数据集提供过滤后的建议
  • 实现带多列展示的自定义下拉行为

Installation

安装

NuGet Installation

NuGet 安装

bash
Install-Package Syncfusion.Tools.Windows
bash
Install-Package Syncfusion.Tools.Windows

Assembly Reference

程序集引用

Add reference to:
  • Syncfusion.Tools.Windows.dll
  • Syncfusion.Shared.Base.dll
添加对以下程序集的引用:
  • Syncfusion.Tools.Windows.dll
  • Syncfusion.Shared.Base.dll

Quick Start

快速开始

Basic Setup

基础配置

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

namespace AutoCompleteDemo
{
    public partial class Form1 : Form
    {
        private AutoComplete autoComplete1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create AutoComplete control
            autoComplete1 = new AutoComplete();
            autoComplete1.Location = new System.Drawing.Point(20, 20);
            autoComplete1.Size = new System.Drawing.Size(200, 20);
            autoComplete1.ParentForm = this;
            
            // Add data source
            autoComplete1.DataSource = new string[] 
            { 
                "Australia", 
                "Austria", 
                "Brazil", 
                "Canada", 
                "China" 
            };
            
            // Add to form
            this.Controls.Add(autoComplete1);
        }
    }
}
csharp
using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

namespace AutoCompleteDemo
{
    public partial class Form1 : Form
    {
        private AutoComplete autoComplete1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create AutoComplete control
            autoComplete1 = new AutoComplete();
            autoComplete1.Location = new System.Drawing.Point(20, 20);
            autoComplete1.Size = new System.Drawing.Size(200, 20);
            autoComplete1.ParentForm = this;
            
            // Add data source
            autoComplete1.DataSource = new string[] 
            { 
                "Australia", 
                "Austria", 
                "Brazil", 
                "Canada", 
                "China" 
            };
            
            // Add to form
            this.Controls.Add(autoComplete1);
        }
    }
}

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
  1. 从工具箱拖拽
    AutoComplete
    控件到窗体中
  2. ParentForm
    属性设置为当前窗体
  3. 通过属性窗口或代码配置
    DataSource
  4. 通过属性面板自定义外观和行为

Core Concepts

核心概念

Data Source

数据源

The AutoComplete control can bind to various data sources:
  • String arrays
  • Generic collections (List<T>, ArrayList)
  • DataTable and DataSet
  • Custom objects with IList interface
AutoComplete控件可绑定多种类型的数据源:
  • 字符串数组
  • 泛型集合(List<T>、ArrayList)
  • DataTable和DataSet
  • 实现IList接口的自定义对象

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.
必须设置
ParentForm
属性才能让控件展示下拉建议列表,该属性会将AutoComplete与父窗体容器关联。

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
📄 阅读: references/getting-started.md
  • 安装与程序集引用
  • 创建WinForms应用
  • 通过设计器添加AutoComplete控件
  • 通过代码添加AutoComplete控件
  • 基础配置与设置
  • 运行应用

📊 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
📄 阅读: references/datasource.md
  • 绑定字符串集合
  • 绑定DataTable和DataSet
  • 绑定自定义对象
  • 多数据源配置
  • 设计时设置数据源
  • 动态更新数据源

🎨 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
📄 阅读: references/customization.md
  • 视觉样式与主题
  • 字体与颜色自定义
  • 边框样式
  • 下拉菜单外观
  • 自动大小配置
  • 下拉菜单列外观
  • 匹配文本高亮
  • 自定义渲染

🔧 Working with AutoComplete

🔧 使用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
📄 阅读: references/working-with-autocomplete.md
  • 自动补全模式(Suggest、Append、SuggestAppend)
  • 字符大小写设置
  • 加载行为
  • 自动填充
  • 默认建议
  • 清空与重置值
  • 程序化选择

📑 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
📄 阅读: references/multicolumn-dropdown.md
  • 启用多列模式
  • 列配置
  • 列标题
  • 列宽与尺寸设置
  • 展示多字段内容
  • 自定义列格式
  • 下拉菜单项插入图片
  • 类表格外观

⚡ Events

⚡ 事件

📄 Read: references/autocomplete-events.md
  • AutoCompleteCustomize event
  • AutoCompleteValueChanged event
  • BeforeCustomization event
  • Handling user selections
  • Validating input
  • Custom event handlers
📄 阅读: references/autocomplete-events.md
  • AutoCompleteCustomize事件
  • AutoCompleteValueChanged事件
  • BeforeCustomization事件
  • 处理用户选择
  • 输入校验
  • 自定义事件处理器

🎯 Overview

🎯 概览

📄 Read: references/overview.md
  • Feature overview
  • Use cases and scenarios
  • Component architecture
  • Performance considerations
  • Best practices
📄 阅读: references/overview.md
  • 特性概览
  • 用例与场景
  • 组件架构
  • 性能注意事项
  • 最佳实践

Common Patterns

常见使用模式

Pattern 1: Simple String AutoComplete

模式1:简单字符串自动补全

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

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

this.Controls.Add(autoComplete1);
csharp
AutoComplete autoComplete1 = new AutoComplete();
autoComplete1.Location = new System.Drawing.Point(20, 20);
autoComplete1.Size = new System.Drawing.Size(200, 20);
autoComplete1.ParentForm = this;

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

this.Controls.Add(autoComplete1);

Pattern 2: DataTable Binding

模式2:绑定DataTable

csharp
AutoComplete autoComplete1 = new AutoComplete();
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;
autoComplete1.DisplayMember = "Name";

this.Controls.Add(autoComplete1);
csharp
AutoComplete autoComplete1 = new AutoComplete();
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;
autoComplete1.DisplayMember = "Name";

this.Controls.Add(autoComplete1);

Pattern 3: Multi-Column Display

模式3:多列展示

csharp
AutoComplete autoComplete1 = new AutoComplete();
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));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("Country", 80));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("City", 80));

this.Controls.Add(autoComplete1);
csharp
AutoComplete autoComplete1 = new AutoComplete();
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));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("Country", 80));
autoComplete1.Columns.Add(new AutoCompleteDataColumnInfo("City", 80));

this.Controls.Add(autoComplete1);

Pattern 4: Custom Filtering with Events

模式4:基于事件的自定义过滤

csharp
AutoComplete autoComplete1 = new AutoComplete();
autoComplete1.ParentForm = this;
autoComplete1.DataSource = GetDataSource();

// Handle custom filtering
autoComplete1.AutoCompleteControl.ItemsListBox.DrawItem += 
    new DrawItemEventHandler(ItemsListBox_DrawItem);

void ItemsListBox_DrawItem(object sender, DrawItemEventArgs e)
{
    if (e.Index >= 0)
    {
        // Custom drawing logic
        e.DrawBackground();
        e.Graphics.DrawString(
            autoComplete1.AutoCompleteControl.ItemsListBox.Items[e.Index].ToString(),
            e.Font,
            Brushes.Black,
            e.Bounds);
        e.DrawFocusRectangle();
    }
}

this.Controls.Add(autoComplete1);
csharp
AutoComplete autoComplete1 = new AutoComplete();
autoComplete1.ParentForm = this;
autoComplete1.DataSource = GetDataSource();

// Handle custom filtering
autoComplete1.AutoCompleteControl.ItemsListBox.DrawItem += 
    new DrawItemEventHandler(ItemsListBox_DrawItem);

void ItemsListBox_DrawItem(object sender, DrawItemEventArgs e)
{
    if (e.Index >= 0)
    {
        // Custom drawing logic
        e.DrawBackground();
        e.Graphics.DrawString(
            autoComplete1.AutoCompleteControl.ItemsListBox.Items[e.Index].ToString(),
            e.Font,
            Brushes.Black,
            e.Bounds);
        e.DrawFocusRectangle();
    }
}

this.Controls.Add(autoComplete1);

Pattern 5: URL/Email AutoComplete

模式5:URL/邮箱自动补全

csharp
AutoComplete autoComplete1 = new AutoComplete();
autoComplete1.ParentForm = this;
autoComplete1.Size = new System.Drawing.Size(300, 20);

// 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.AutoCompleteMode = AutoCompleteMode.SuggestAppend;

this.Controls.Add(autoComplete1);
csharp
AutoComplete autoComplete1 = new AutoComplete();
autoComplete1.ParentForm = this;
autoComplete1.Size = new System.Drawing.Size(300, 20);

// 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.AutoCompleteMode = AutoCompleteMode.SuggestAppend;

this.Controls.Add(autoComplete1);

Key Properties Reference

核心属性参考

PropertyTypeDefaultDescription
DataSource
objectnullData source for suggestions (array, DataTable, etc.)
ParentForm
FormnullParent form containing the control (required)
AutoCompleteMode
AutoCompleteModeSuggestBehavior mode: None, Suggest, Append, SuggestAppend
DisplayMember
string""Property name to display from data source
ValueMember
string""Property name for internal value
Columns
AutoCompleteDataColumnInfoCollection-Column configuration for multi-column display
Style
AutoCompleteStyleDefaultVisual style of the control
Text
string""Current text value
SelectedValue
objectnullCurrently selected value
CharacterCasing
CharacterCasingNormalText casing: Normal, Upper, Lower
LoadOnDemand
boolfalseLoad suggestions on demand
AutoCompleteControl
AutoCompletePopup-Access to underlying popup control
属性类型默认值描述
DataSource
objectnull建议内容的数据源(数组、DataTable等)
ParentForm
Formnull包含控件的父窗体(必填)
AutoCompleteMode
AutoCompleteModeSuggest行为模式:None、Suggest、Append、SuggestAppend
DisplayMember
string""数据源中要展示的属性名称
ValueMember
string""内部值对应的属性名称
Columns
AutoCompleteDataColumnInfoCollection-多列展示的列配置
Style
AutoCompleteStyleDefault控件的视觉样式
Text
string""当前文本值
SelectedValue
objectnull当前选中的值
CharacterCasing
CharacterCasingNormal文本大小写:Normal、Upper、Lower
LoadOnDemand
boolfalse按需加载建议内容
AutoCompleteControl
AutoCompletePopup-访问底层弹出控件

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
AutoComplete控件的常用事件:
  • AutoCompleteValueChanged:选中值发生变化时触发
  • AutoCompleteCustomize:展示下拉列表前触发
  • BeforeCustomization:应用自定义配置前触发
  • TextChanged:文本内容变化时触发
  • SelectedIndexChanged:选中项变化时触发
  • GotFocus:控件获得焦点时触发
  • LostFocus:控件失去焦点时触发

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
  3. Optimize Large Datasets: Use
    LoadOnDemand
    for large data sources to improve performance
  4. Multi-Column for Complex Data: Use multi-column display when showing related information
  5. Handle Events Properly: Use
    AutoCompleteValueChanged
    to respond to user selections
  6. Clear Data Appropriately: Call
    ResetItems()
    or set
    DataSource = null
    to clear suggestions
  7. Consider Character Casing: Set
    CharacterCasing
    based on data type (e.g., Upper for state codes)
  8. Theme Consistency: Use matching visual styles across all Syncfusion controls
  1. 始终设置ParentForm
    ParentForm
    属性是下拉菜单正常工作的必要条件
  2. 使用合适的模式:选择正确的
    AutoCompleteMode
    • Suggest
      :仅展示下拉菜单
    • Append
      :仅自动补全文本
    • SuggestAppend
      :同时展示下拉菜单和自动补全文本
  3. 大型数据集优化:针对大型数据源启用
    LoadOnDemand
    提升性能
  4. 复杂数据使用多列展示:需要展示关联信息时使用多列展示模式
  5. 正确处理事件:使用
    AutoCompleteValueChanged
    响应用户选择操作
  6. 合理清空数据:调用
    ResetItems()
    或设置
    DataSource = null
    清空建议内容
  7. 考虑字符大小写设置:根据数据类型设置
    CharacterCasing
    (例如州编码使用Upper)
  8. 主题一致性:所有Syncfusion控件使用统一的视觉样式

Visual Styles

视觉样式

The control supports multiple visual themes:
  • Default
  • Office2016Colorful
  • Office2016White
  • Office2016Black
  • Office2016DarkGray
  • Metro
  • Office2007
  • Office2010
  • VS2010
csharp
autoComplete1.Style = AutoCompleteStyle.Office2016Colorful;
控件支持多种视觉主题:
  • Default
  • Office2016Colorful
  • Office2016White
  • Office2016Black
  • Office2016DarkGray
  • Metro
  • Office2007
  • Office2010
  • VS2010
csharp
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)
  • .NET Framework 4.5及以上版本
  • .NET 6.0、.NET 7.0、.NET 8.0(Windows平台)
  • .NET Core 3.1(Windows平台)

Additional Resources

额外资源

Related Controls

相关控件

  • ComboBoxAdv: Advanced combo box with more customization options
  • TextBoxExt: Extended text box with additional features
  • AutoCompleteControl: Standalone popup control for custom scenarios
  • MultiColumnComboBox: Dedicated multi-column dropdown control
  • ComboBoxAdv:支持更多自定义选项的高级组合框
  • TextBoxExt:带额外功能的扩展文本框
  • AutoCompleteControl:适用于自定义场景的独立弹出控件
  • MultiColumnComboBox:专属多列下拉控件

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
问题:下拉菜单不显示
  • 确认已设置
    ParentForm
    属性
  • 检查
    DataSource
    包含有效数据
  • 验证控件已添加到窗体的Controls集合中
问题:多列内容不展示
  • 设置合适的
    AutoCompleteStyle
  • 已向
    Columns
    集合添加列配置
  • 确认DataSource包含匹配的列名
问题:大型数据集下性能不佳
  • 启用
    LoadOnDemand
    属性
  • 减少展示的列数量
  • 绑定数据源前先过滤数据
问题:样式未生效
  • 确认已引用Syncfusion主题DLL
  • 在设置DataSource后应用样式
  • 检查是否存在冲突的自定义绘制代码