在C#的WinForms应用开发中，为输入框添加自动提示列表是提升用户交互体验的常见需求，借助内置的AutoComplete功能可以快速实现基础效果，也可以自定义逻辑适配复杂场景。
C#内置AutoComplete基础用法
WinForms的TextBox控件自带AutoComplete相关属性，只需要配置好数据源和模式就能实现基础提示效果。核心属性包含三个：AutoCompleteMode设置提示触发模式，AutoCompleteSource设置提示数据来源，AutoCompleteCustomSource设置自定义提示数据集合。
属性说明
| 属性名 | 可选值 | 作用说明 |
|---|---|---|
| AutoCompleteMode | None、Suggest、Append、SuggestAppend | None表示不启用，Suggest显示提示列表，Append自动补全文本，SuggestAppend同时生效 |
| AutoCompleteSource | FileSystem、HistoryList、CustomSource等 | 设置提示数据的来源类型，CustomSource表示使用自定义集合 |
| AutoCompleteCustomSource | AutoCompleteStringCollection类型 | 存储自定义提示字符串的集合，仅在AutoCompleteSource为CustomSource时生效 |
基础实现示例
以下代码演示如何为文本框配置固定的提示列表：
using System;
using System.Windows.Forms;
namespace AutoCompleteDemo
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
InitAutoComplete();
}
private void InitAutoComplete()
{
// 创建自定义提示集合
AutoCompleteStringCollection source = new AutoCompleteStringCollection();
source.AddRange(new string[] { "苹果", "香蕉", "橘子", "梨子", "葡萄", "草莓" });
// 配置文本框的AutoComplete属性
textBox1.AutoCompleteMode = AutoCompleteMode.SuggestAppend;
textBox1.AutoCompleteSource = AutoCompleteSource.CustomSource;
textBox1.AutoCompleteCustomSource = source;
}
}
}
动态更新提示列表的实现
实际场景中提示数据往往是动态的，比如根据用户历史输入、数据库查询结果动态生成，这时候可以在文本框的TextChanged事件中更新提示集合。
using System;
using System.Windows.Forms;
using System.Collections.Generic;
namespace AutoCompleteDemo
{
public partial class Form2 : Form
{
// 模拟数据库中的商品名称列表
private List<string> allProducts = new List<string>
{
"华为手机", "华为平板", "华为笔记本",
"小米手机", "小米电视", "小米手环",
"苹果手机", "苹果平板", "苹果耳机"
};
public Form2()
{
InitializeComponent();
// 初始不设置提示源，在文本变化时动态更新
textBox1.AutoCompleteMode = AutoCompleteMode.SuggestAppend;
textBox1.AutoCompleteSource = AutoCompleteSource.CustomSource;
textBox1.TextChanged += TextBox1_TextChanged;
}
private void TextBox1_TextChanged(object sender, EventArgs e)
{
string input = textBox1.Text.Trim();
AutoCompleteStringCollection dynamicSource = new AutoCompleteStringCollection();
if (!string.IsNullOrEmpty(input))
{
// 筛选包含输入内容的商品名称
foreach (var product in allProducts)
{
if (product.Contains(input))
{
dynamicSource.Add(product);
}
}
}
// 更新提示集合
textBox1.AutoCompleteCustomSource = dynamicSource;
}
}
}
自定义提示列表控件实现
如果内置的AutoComplete样式无法满足需求，比如需要显示多列信息、自定义列表项样式，可以结合ListBox控件自定义提示列表。核心思路是监听文本框的输入事件，将匹配的结果展示在ListBox中，点击ListBox项时回填到文本框。
using System;
using System.Windows.Forms;
using System.Collections.Generic;
namespace AutoCompleteDemo
{
public partial class Form3 : Form
{
private ListBox suggestionList;
private List<string> allData = new List<string>
{
"北京", "上海", "广州", "深圳",
"杭州", "成都", "武汉", "西安"
};
public Form3()
{
InitializeComponent();
InitCustomSuggestion();
}
private void InitCustomSuggestion()
{
// 初始化自定义提示列表控件
suggestionList = new ListBox();
suggestionList.Visible = false;
suggestionList.Width = textBox1.Width;
suggestionList.Height = 120;
// 设置列表位置在文本框下方
suggestionList.Top = textBox1.Bottom + 2;
suggestionList.Left = textBox1.Left;
suggestionList.Parent = this;
// 绑定事件
textBox1.TextChanged += TextBox1_TextChanged_Custom;
textBox1.Leave += TextBox1_Leave;
suggestionList.Click += SuggestionList_Click;
}
private void TextBox1_TextChanged_Custom(object sender, EventArgs e)
{
string input = textBox1.Text.Trim();
suggestionList.Items.Clear();
if (string.IsNullOrEmpty(input))
{
suggestionList.Visible = false;
return;
}
// 匹配数据
foreach (var item in allData)
{
if (item.Contains(input))
{
suggestionList.Items.Add(item);
}
}
suggestionList.Visible = suggestionList.Items.Count > 0;
}
private void TextBox1_Leave(object sender, EventArgs e)
{
// 文本框失去焦点时隐藏提示列表，延迟隐藏避免点击列表项时先触发失去焦点
BeginInvoke(new Action(() => { suggestionList.Visible = false; }));
}
private void SuggestionList_Click(object sender, EventArgs e)
{
if (suggestionList.SelectedItem != null)
{
textBox1.Text = suggestionList.SelectedItem.ToString();
suggestionList.Visible = false;
}
}
}
}
注意事项
- 使用内置AutoComplete时，如果数据源很大，频繁更新
AutoCompleteCustomSource可能会有性能问题，建议做输入防抖处理，比如等待用户输入暂停300毫秒后再更新提示数据。 - 自定义提示列表时，需要处理文本框获得焦点、其他控件点击等场景，确保提示列表能正确显示和隐藏，避免出现列表残留的问题。
- 如果提示数据需要异步加载，比如从远程接口获取，要注意异步操作的时序问题，避免旧请求的结果覆盖新的输入匹配结果。
C#AutoCompleteWinForms提示列表修改时间：2026-07-17 16:09:31