syncfusion-winforms-autocomplete

Syncfusion WinForms 自动完成控件

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 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 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 后再应用样式
• 检查是否存在冲突的自定义绘制代码