简介：这份资源面向 WinForm 桌面开发初学者与需要快速实现输入联想功能的开发者，针对原生 TextBox 只能从头匹配、ComboBox 自动补全不够灵活的问题，给出一种比重写 ListBox 更轻量的关键字智能提示实现思路，支持任意位置匹配与多关键字组合，适合在搜索框、录入框等场景中直接借鉴。压缩包共 24 个文件，约 45KB，以 6 个 cs 源码文件为核心，配合 sln、csproj 工程文件与 config、settings 配置，另有 exe、pdb、resources、resx 等运行与资源文件，结构完整，可直接打开编译运行。目前已有 420 人学习下载。通过阅读 Form1 与 Program 等关键代码，读者能掌握下拉提示框的触发、过滤与展示逻辑，理解如何在不依赖复杂控件重写的前提下扩展 TextBox 的输入联想能力，并可将该方案迁移到自己的 WinForm 项目中，减少重复摸索成本。
1. 从一次输入框卡顿说起：WinForm TextBox 关键字智能提示到底怎么落地
上个月帮朋友改一个 WinForm 的物料录入界面，TextBox 里要输物料编码，输错一位就得整条重来，操作员一天骂三回。我第一反应是加个下拉框，但字段太多，下拉框根本放不下。后来改成关键字智能提示：输入前几个字符，下面弹一个候选列表，回车或双击直接填进去。改完当天，录入效率肉眼可见地提上来了。
这个方案的核心不是「做个下拉框」，而是把 TextBox 的文本变化事件、候选数据源、弹出列表控件三者串起来，还要处理焦点、键盘、性能这几个老问题。适合谁？适合正在做 WinForm 数据录入、搜索框、编码选择这类场景的 C# 开发者，尤其是用 VS2022 维护老项目、不想引入第三方 UI 库的人。下面我按「能跑起来 → 能跑稳 → 能跑快」的顺序拆一遍。
2. 选型与原理：为什么用 ListBox 而不是 ComboBox
2.1 三种常见实现方式的取舍
WinForm 里做关键字提示，常见做法有三种：ComboBox 下拉、ListBox 浮动、ToolStripDropDown 承载列表。ComboBox 最省事，但它的下拉是「点一下才展开」，输入过程中不会自动弹，而且下拉宽度跟控件绑定，候选文字长了就截断。ToolStripDropDown 灵活，但宿主控件和焦点管理偏重，老项目里容易和已有布局打架。
我一般选 ListBox 浮动方案：把 ListBox 放在一个无边框的 Form 或者直接挂到主窗体上，根据 TextBox 的位置动态定位。原因是 ListBox 的 Items 操作简单，键盘上下键、回车选中都能自己接管，性能也可控。代价是要自己处理「点外面关掉」「焦点不丢」这些细节，后面避坑章节会讲。
2.2 数据源与匹配策略
候选数据从哪来？小数据量（几百条以内）直接内存 List ，每次 TextChanged 用 StartsWith 或 Contains 过滤。数据量大（上万条）就别每次全量扫，常见做法是预建前缀索引，或者用 Dapper 从数据库按前缀查。热词里提到的 winform dapper 依赖注入，在这个场景里就是用来把候选查询服务注入到窗体，避免把 SQL 写死在 UI 里。
匹配策略上，StartsWith 比 Contains 更符合「编码提示」的直觉，因为用户是从左往右输入的。如果做的是名称搜索，Contains 更合适。我一般做成可配置的枚举，默认 StartsWith。
2.3 最小可运行骨架
先看核心代码，这段是「能跑起来」的最小版本，放在窗体里就能用。
// 窗体字段 private ListBox _suggestionList; private List<string> _allItems = new List<string>(); private void InitSuggestion() { _suggestionList = new ListBox(); _suggestionList.Visible = false; _suggestionList.DoubleClick += SuggestionList_DoubleClick; _suggestionList.KeyDown += SuggestionList_KeyDown; this.Controls.Add(_suggestionList); _suggestionList.BringToFront(); } private void txtCode_TextChanged(object sender, EventArgs e) { string keyword = txtCode.Text.Trim(); if (keyword.Length == 0) { _suggestionList.Visible = false; return; } // StartsWith 过滤，最多取 10 条，避免列表过长 var matches = _allItems .Where(x => x.StartsWith(keyword, StringComparison.OrdinalIgnoreCase)) .Take(10) .ToList(); if (matches.Count == 0) { _suggestionList.Visible = false; return; } _suggestionList.Items.Clear(); _suggestionList.Items.AddRange(matches.ToArray()); // 定位到 TextBox 正下方 Point p = txtCode.Parent.PointToClient(txtCode.PointToScreen(new Point(0, txtCode.Height))); _suggestionList.Location = p; _suggestionList.Width = txtCode.Width; _suggestionList.Height = Math.Min(matches.Count * 18 + 4, 180); _suggestionList.Visible = true; _suggestionList.BringToFront(); }逻辑说明：TextChanged 里先判空，再过滤，再定位。Take(10)是性能保护，候选太多反而干扰选择。定位用PointToScreen再转客户端坐标，是为了兼容 TextBox 放在 Panel 或 GroupBox 里的情况，直接拿txtCode.Location在嵌套容器里会偏。
参数说明：StringComparison.OrdinalIgnoreCase忽略大小写，编码场景一般需要；Height用Math.Min限制最大高度，超过就出滚动条，ListBox 自带。
2.4 键盘与选中回填
光弹出来不够，用户要能用键盘选。回车填当前项，上下键移动，Esc 关掉。
private void txtCode_KeyDown(object sender, KeyEventArgs e) { if (!_suggestionList.Visible) return; if (e.KeyCode == Keys.Down) { // 焦点还在 TextBox，手动移动 ListBox 选中项 int idx = _suggestionList.SelectedIndex; if (idx < _suggestionList.Items.Count - 1) _suggestionList.SelectedIndex = idx + 1; e.Handled = true; } else if (e.KeyCode == Keys.Up) { int idx = _suggestionList.SelectedIndex; if (idx > 0) _suggestionList.SelectedIndex = idx - 1; e.Handled = true; } else if (e.KeyCode == Keys.Enter) { if (_suggestionList.SelectedItem != null) { txtCode.Text = _suggestionList.SelectedItem.ToString(); txtCode.SelectionStart = txtCode.Text.Length; _suggestionList.Visible = false; } e.Handled = true; e.SuppressKeyPress = true; // 防止回车触发窗体默认按钮 } else if (e.KeyCode == Keys.Escape) { _suggestionList.Visible = false; e.Handled = true; } }这里有个关键点：焦点始终留在 TextBox，ListBox 只是「显示选中」，不抢焦点。所以上下键要在 TextBox 的 KeyDown 里手动改SelectedIndex。SuppressKeyPress必须加，否则回车会触发窗体上的 AcceptButton，这是血泪经验。
3. 把提示做稳：焦点、定位与数据刷新
3.1 焦点丢失与点击外部关闭
ListBox 显示后，用户点窗体其他地方，列表要自动关。常见做法是给 ListBox 加 LostFocus，但焦点本来就不在 ListBox 上，这个事件不触发。正确做法是监听窗体的 Click 或者用 Timer 检测鼠标位置。
// 在窗体构造函数里挂上 this.MouseClick += (s, e) => { if (_suggestionList.Visible && !_suggestionList.Bounds.Contains(e.Location)) { _suggestionList.Visible = false; } };逻辑说明：用窗体 MouseClick 判断点击点是否在 ListBox 范围内，不在就隐藏。参数上e.Location是窗体坐标，_suggestionList.Bounds也是相对父容器的，如果 ListBox 直接挂在窗体上就一致；如果挂在 Panel 上，要做坐标转换。我一般直接把 ListBox 挂窗体，省掉转换。
3.2 定位偏移的两种典型场景
第一种，TextBox 在 GroupBox 里。txtCode.Location是相对 GroupBox 的，直接赋给 ListBox 会偏。用PointToScreen转绝对坐标再转回窗体客户端坐标，就是 2.3 里那段。
第二种，窗体有滚动条。如果外层是 Panel 且 AutoScroll 为 true，滚动后 ListBox 位置不会自动跟。解决方式是在 TextChanged 里重新算一次位置，或者干脆把 ListBox 也放进同一个滚动容器。我一般选前者，因为候选列表生命周期短，每次输入重算成本可接受。
3.3 数据源动态刷新
候选数据不是一成不变的。物料编码可能新增，用户可能切换仓库。常见做法是给候选服务加一个Refresh()，在窗体 Load 或切换条件时调用。
public interface ISuggestionService { IReadOnlyList<string> Search(string keyword, int max); void Refresh(); } public class MemorySuggestionService : ISuggestionService { private List<string> _cache = new List<string>(); public void Refresh() { // 实际项目里从数据库或文件重新加载 _cache = LoadFromSource(); } public IReadOnlyList<string> Search(string keyword, int max) { return _cache .Where(x => x.StartsWith(keyword, StringComparison.OrdinalIgnoreCase)) .Take(max) .ToList(); } }逻辑说明：把搜索逻辑抽到接口后面，UI 只依赖接口。这样单元测试好写，后面换数据库查询也不用改窗体代码。参数max由调用方决定，UI 传 10，其他地方可以传 50。
3.4 用 Dapper 做前缀查询的写法
数据量上万时，内存过滤会卡。常见做法是每次输入带前缀去数据库查，用 Dapper 写起来很直接。
public IReadOnlyList<string> Search(string keyword, int max) { using (var conn = new SqlConnection(_connStr)) { // 参数化查询，防止注入；TOP 限制返回条数 string sql = @"SELECT TOP (@Max) Code FROM Material WHERE Code LIKE @Prefix + '%' ORDER BY Code"; return conn.Query<string>(sql, new { Max = max, Prefix = keyword }).ToList(); } }参数说明：@Max控制返回条数，@Prefix拼%做前缀匹配。注意LIKE @Prefix + '%'这种写法在 SQL Server 里能走索引，比LIKE '%' + @Prefix + '%'好得多。如果每次按键都查库，建议加 200ms 防抖，避免输入快时打爆数据库。
4. 避坑与排查：五个真实翻车记录
4.1 现象：输入中文时候选列表闪烁
原因：中文输入法在拼字阶段会频繁触发 TextChanged，每次都在重建 ListBox 项。解决：判断ImeMode或者用CompositionState，拼字未上屏时不刷新。简单做法是加一个 150ms 的 Timer 防抖，TextChanged 只重置 Timer，Timer Tick 里才真正过滤。
4.2 现象：回车后窗体直接提交了
原因：TextBox 的 KeyDown 里没拦回车，事件冒泡到窗体 AcceptButton。解决：在 KeyDown 里设e.SuppressKeyPress = true和e.Handled = true，两个都要，只设一个在某些 .NET 版本下不生效。
4.3 现象：ListBox 显示在 TextBox 后面被挡住
原因：控件 Z 顺序问题，后添加的控件默认在上层，但如果 TextBox 是后添加的就会盖住。解决：每次显示前调_suggestionList.BringToFront()，或者在设计器里调整 Controls 集合顺序。我习惯在代码里 BringToFront，不依赖设计器。
4.4 现象：候选列表点一下没反应，要点两下
原因：第一次点击被窗体 MouseClick 处理成「关闭列表」，ListBox 的 Click 没收到。解决：MouseClick 里判断点击点是否在 ListBox 内，在的话不关闭，让 ListBox 自己处理。3.1 的代码已经包含这个判断。
4.5 现象：数据量大时输入卡顿
原因：每次 TextChanged 都全量 Where 扫描，几万条数据下 UI 线程被占满。解决：三层保护——防抖 200ms、Take(max)限制、数据源超过阈值时改走数据库前缀查询。如果还卡，把过滤放到 Task 里，但注意 ListBox 更新要回 UI 线程，用Invoke。
5. 进阶技巧：把提示做成可复用控件
5.1 封装成 SuggestionTextBox
每次在窗体里手写一遍太累，我一般封装一个继承自 TextBox 的控件，把 ListBox、防抖、键盘处理都塞进去。外部只需要设一个SuggestionService属性。
public class SuggestionTextBox : TextBox { private ListBox _list; private Timer _debounce; private ISuggestionService _service; public ISuggestionService SuggestionService { get => _service; set { _service = value; } } public SuggestionTextBox() { _list = new ListBox { Visible = false }; _debounce = new Timer { Interval = 200 }; _debounce.Tick += (s, e) => { _debounce.Stop(); DoSearch(); }; this.TextChanged += (s, e) => { _debounce.Stop(); _debounce.Start(); }; this.KeyDown += OnKeyDownInternal; } private void DoSearch() { if (_service == null || Text.Trim().Length == 0) { _list.Visible = false; return; } var matches = _service.Search(Text.Trim(), 10); // 后续定位与显示逻辑同 2.3 } }逻辑说明：防抖 Timer 在 TextChanged 里重置，停止输入 200ms 后才查。SuggestionService用属性注入，窗体初始化时赋值即可。这样每个用到的地方只写一行txtCode.SuggestionService = service;。
5.2 验证清单
封装完别急着上生产，按这个清单过一遍：
| 检查项 | 预期表现 | 不通过时看哪 |
|---|---|---|
| 输入单字符 | 列表弹出且定位准确 | 定位代码是否用了 PointToScreen |
| 输入无匹配 | 列表隐藏，不报错 | 空结果分支是否 return |
| 上下键 | 选中项移动，焦点不跳 | KeyDown 是否 Handled |
| 回车 | 回填并关闭，不提交窗体 | SuppressKeyPress 是否设 |
| 点外部 | 列表关闭 | MouseClick 判断范围 |
| 快速输入 | 不卡顿，不闪烁 | 防抖是否生效 |
| 切换数据源 | 候选更新 | Refresh 是否调用 |
5.3 一个容易忽略的细节
ListBox 的IntegralHeight属性默认 true，高度会被自动调整到整数行，导致你设的 Height 不生效。如果发现列表高度和预期差几像素，把它设成 false。这个坑我踩过两次，查了半天才发现是控件默认行为。
从那以后我每次封装这类浮动列表控件，都会先把IntegralHeight = false、BorderStyle = FixedSingle、DrawMode确认一遍，再写定位逻辑。希望帮到你。
本文还有配套的精品资源，点击获取
