XComboBox 可输入下拉框组件：从状态机到虚拟滚动与远程搜索的工程实践

简介XComboBox.rar 是一份面向 Qt 开发者的自定义控件实战源码针对标准 QComboBox 只能单选、无法直接支持复选框的痛点通过继承 QComboBox 并重写关键方法实现带复选框的多选下拉列表。资源适合具备一定 Qt 基础、需要在工程中实现多选交互的开发者参考学习。压缩包共 13 个文件约 9KB包含 3 个 cpp 与 2 个 h 源文件、1 个 ui 界面文件、1 个 qrc 资源文件以及 sln、vcxproj、pro 等工程配置覆盖 XComboBox 类定义、自定义模型、复选框绘制与信号槽处理等核心实现。目前已有 1311 人学习下载。通过研读源码读者可掌握 initStyleOption、paintEvent 重写及 QAbstractItemModel 自定义方法理解复选框状态同步与 checkedItemsChanged 信号的使用并可直接将 XComboBox 集成到自己的 Qt 项目中快速获得可复用的多选下拉控件方案。1. 一个压缩包名背后XComboBox 到底在解决什么交互问题第一次看到 XComboBox.rar 这个文件名多数人第一反应是「这不就是个下拉框控件吗」。但真在业务里做过复杂表单的人会知道原生下拉框在「可输入 可筛选 可多选 可远程加载」这四个需求叠加时几乎必然翻车。XComboBox 这类方案要解决的核心是把输入框的自由输入能力和下拉列表的结构化选择能力缝合成一个控件同时不牺牲键盘可达性和大数据量下的渲染性能。它适合三类人一是做后台管理系统、需要在表单里塞大量枚举字段的前端二是做桌面端或跨平台界面、手头 UI 框架自带控件不够用的开发者三是想自己封装一套可复用组件、但不确定边界条件该覆盖哪些的人。读完你应该能判断这个方向值不值得投入以及自己动手时参数该往哪调。2. 拆开 XComboBox输入框与下拉列表怎么合成一个控件2.1 为什么原生 select 撑不住复杂场景原生select的问题不在于「能不能选」而在于它的行为被浏览器锁死了。你没法在选项里塞自定义 DOM没法对输入做实时过滤多选只能靠multiple属性配合 Ctrl 点击这种反人类操作移动端还会被系统弹层接管样式完全失控。更麻烦的是远程数据选项来自接口分页返回时原生控件根本没有「输入触发查询」这个钩子。所以 XComboBox 这类控件的本质是把一个input和一个浮层列表组合起来用状态机管理它们的关系。输入框负责文本和光标浮层负责候选集和选中态两者通过一个受控的 value 和 open 状态同步。听起来简单但真正难的是边界什么时候该开浮层、什么时候该关、输入的值和选中的值什么时候算一致。我一般会把状态拆成四块inputValue输入框里显示的文本、selectedValue真正提交的值、options当前候选集、open浮层开关。很多人翻车就翻在把inputValue和selectedValue混成一个 state结果用户输入一半没选中就失焦值要么丢了要么脏了。2.2 最小可用实现一个受控组件的骨架下面这段是骨架级实现用原生 JS 写方便你移植到任何框架。核心是「输入归输入、选中归选中」两条线。// XComboBox 最小骨架受控 过滤 键盘导航 class XComboBox { constructor(root, { options [], filter true, onChange } {}) { this.root root; this.allOptions options; // 全量候选远程场景下由外部更新 this.filter filter; // 是否开启本地过滤 this.onChange onChange; // 选中回调抛出 selectedValue this.inputValue ; // 输入框文本独立于选中值 this.selectedValue null; // 真正提交的值 this.open false; this.activeIndex -1; // 键盘高亮项-1 表示无 this.render(); this.bindEvents(); } render() { this.root.innerHTML div classxcombo input classxcombo-input typetext autocompleteoff / ul classxcombo-list rolelistbox/ul /div; this.input this.root.querySelector(.xcombo-input); this.list this.root.querySelector(.xcombo-list); } // 根据 inputValue 计算当前应展示的候选集 getVisibleOptions() { if (!this.filter || !this.inputValue) return this.allOptions; const kw this.inputValue.toLowerCase(); return this.allOptions.filter(o o.label.toLowerCase().includes(kw)); } bindEvents() { this.input.addEventListener(input, (e) { this.inputValue e.target.value; this.open true; this.activeIndex -1; this.updateList(); }); this.input.addEventListener(keydown, (e) this.onKeyDown(e)); // 失焦延迟关闭否则点击列表项时列表先消失 this.input.addEventListener(blur, () { setTimeout(() { this.open false; this.updateList(); }, 120); }); } onKeyDown(e) { const opts this.getVisibleOptions(); if (e.key ArrowDown) { e.preventDefault(); this.activeIndex Math.min(this.activeIndex 1, opts.length - 1); this.updateList(); } else if (e.key ArrowUp) { e.preventDefault(); this.activeIndex Math.max(this.activeIndex - 1, 0); this.updateList(); } else if (e.key Enter this.activeIndex 0) { this.select(opts[this.activeIndex]); } else if (e.key Escape) { this.open false; this.updateList(); } } select(option) { this.selectedValue option.value; this.inputValue option.label; // 选中后回填文本 this.open false; this.input.value this.inputValue; this.updateList(); this.onChange this.onChange(option.value); } updateList() { const opts this.getVisibleOptions(); this.list.style.display this.open ? block : none; this.list.innerHTML opts.map((o, i) li roleoption>// 远程搜索防抖 丢弃过期响应 let seq 0; let timer null; input.addEventListener(input, (e) { const kw e.target.value; clearTimeout(timer); timer setTimeout(async () { const mySeq seq; const res await fetch(/api/options?kw${encodeURIComponent(kw)}); const data await res.json(); if (mySeq ! seq) return; // 过期响应直接丢 combo.allOptions data; combo.updateList(); }, 250); });防抖 250ms 是输入场景的常用值低于 150ms 请求太密高于 400ms 用户会觉得卡。seq自增比对是丢弃过期响应的最简做法比 AbortController 兼容性好代价是请求还是发出去了只是结果不用。如果接口压力大再叠加 AbortController 真正取消。3. 多选、分组与大数据量三个把控件拖垮的场景3.1 多选模式下的值同步与标签渲染多选不是把selectedValue换成数组就完事。真正的坑在于输入框里显示什么常见做法是选中项渲染成标签tag输入框缩到标签后面用户继续输入时在已有选中基础上过滤。这时候inputValue和selectedValue的关系变成「输入是临时过滤词选中是标签集合」失焦时输入词要清空标签保留。// 多选选中集合与输入词分离 this.selectedValues []; // 数组存 value this.inputValue ; // 仅作过滤词失焦清空 addTag(option) { if (this.selectedValues.includes(option.value)) return; // 去重 this.selectedValues.push(option.value); this.inputValue ; // 选中后清空过滤词 this.input.value ; this.renderTags(); this.onChange this.onChange([...this.selectedValues]); } renderTags() { const tags this.selectedValues.map(v { const opt this.allOptions.find(o o.value v); return span classxcombo-tag style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />