syncfusion-winforms-autocomplete
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion 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.Windowsbash
Install-Package Syncfusion.Tools.WindowsAssembly Reference
程序集引用
Add reference to:
Syncfusion.Tools.Windows.dllSyncfusion.Shared.Base.dll
添加对以下程序集的引用:
Syncfusion.Tools.Windows.dllSyncfusion.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
设计器配置
- Drag control from Toolbox to Form
AutoComplete - Set the property to current form
ParentForm - Configure through Properties window or code
DataSource - Customize appearance and behavior through Properties
- 从工具箱拖拽控件到窗体中
AutoComplete - 将属性设置为当前窗体
ParentForm - 通过属性窗口或代码配置
DataSource - 通过属性面板自定义外观和行为
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 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与父窗体容器关联。
ParentFormFiltering
过滤
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
核心属性参考
| Property | Type | Default | Description |
|---|---|---|---|
| object | null | Data source for suggestions (array, DataTable, etc.) |
| Form | null | Parent form containing the control (required) |
| AutoCompleteMode | Suggest | Behavior mode: None, Suggest, Append, SuggestAppend |
| string | "" | Property name to display from data source |
| string | "" | Property name for internal value |
| AutoCompleteDataColumnInfoCollection | - | Column configuration for multi-column display |
| AutoCompleteStyle | Default | Visual style of the control |
| string | "" | Current text value |
| object | null | Currently selected value |
| CharacterCasing | Normal | Text casing: Normal, Upper, Lower |
| bool | false | Load suggestions on demand |
| AutoCompletePopup | - | Access to underlying popup control |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| object | null | 建议内容的数据源(数组、DataTable等) |
| Form | null | 包含控件的父窗体(必填) |
| AutoCompleteMode | Suggest | 行为模式:None、Suggest、Append、SuggestAppend |
| string | "" | 数据源中要展示的属性名称 |
| string | "" | 内部值对应的属性名称 |
| AutoCompleteDataColumnInfoCollection | - | 多列展示的列配置 |
| AutoCompleteStyle | Default | 控件的视觉样式 |
| string | "" | 当前文本值 |
| object | null | 当前选中的值 |
| CharacterCasing | Normal | 文本大小写:Normal、Upper、Lower |
| bool | false | 按需加载建议内容 |
| 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
最佳实践
-
Always Set ParentForm: Theproperty is mandatory for the dropdown to work properly
ParentForm -
Use Appropriate Mode: Choose the right:
AutoCompleteMode- : Show dropdown only
Suggest - : Auto-complete text only
Append - : Both dropdown and text completion
SuggestAppend
-
Optimize Large Datasets: Usefor large data sources to improve performance
LoadOnDemand -
Multi-Column for Complex Data: Use multi-column display when showing related information
-
Handle Events Properly: Useto respond to user selections
AutoCompleteValueChanged -
Clear Data Appropriately: Callor set
ResetItems()to clear suggestionsDataSource = null -
Consider Character Casing: Setbased on data type (e.g., Upper for state codes)
CharacterCasing -
Theme Consistency: Use matching visual styles across all Syncfusion controls
-
始终设置ParentForm:属性是下拉菜单正常工作的必要条件
ParentForm -
使用合适的模式:选择正确的:
AutoCompleteMode- :仅展示下拉菜单
Suggest - :仅自动补全文本
Append - :同时展示下拉菜单和自动补全文本
SuggestAppend
-
大型数据集优化:针对大型数据源启用提升性能
LoadOnDemand -
复杂数据使用多列展示:需要展示关联信息时使用多列展示模式
-
正确处理事件:使用响应用户选择操作
AutoCompleteValueChanged -
合理清空数据:调用或设置
ResetItems()清空建议内容DataSource = null -
考虑字符大小写设置:根据数据类型设置(例如州编码使用Upper)
CharacterCasing -
主题一致性:所有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 property is set
ParentForm - Check that contains valid data
DataSource - Verify control is added to form's Controls collection
Issue: Multi-column not displaying
- Set appropriate
AutoCompleteStyle - Add columns to collection
Columns - Ensure DataSource has matching column names
Issue: Performance issues with large datasets
- Enable property
LoadOnDemand - 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后应用样式
- 检查是否存在冲突的自定义绘制代码