前段时间帮一个做本地生活的团队改移动端 H5里面有个城市选择弹层全国三百多个地级市加上下辖区县拢共两千三百多条数据原封不动塞进一个 vant picker 里让用户靠手指滚。上线第二天测试同学就在群里甩了一句“选个深圳要滚到我怀疑人生”产品跟着补刀“能不能加个搜索”。于是就有了这次改造给 vant picker 选择器组件增加 search 搜索功能。这件事听起来只是“加个输入框过滤一下”真动手才会发现坑集中在两个地方——Picker 的选中状态其实是索引而不是值以及中文列表的搜索体验如果只做全字匹配用户搜“sz”找不到深圳照样骂人。这篇文章写给已经用过 Vant、正在被长列表滚轮折磨的前端同学也写给刚接触移动端组件库、想知道“组件不够用的时候该怎么改”的新手。Vue 2 Vant 2 和 Vue 3 Vant 4 两套写法我都会给代码可以直接抄走改成自己的业务组件。文中所有关于数据量、耗时的描述都来自我在几个真实项目里的实测参数怎么选、为什么这么选我也会一并说清楚尽量让你少走一遍我走过的弯路。1. 改造之前先想清楚搜索能力该长在哪一层1.1 我遇到的真实场景与数据规模先做个经验分档不是所有 Picker 都值得加搜索。选项在 50 条以内的比如性别、证件类型、订单状态滚轮两三下就能到硬塞一个搜索框反而增加认知负担用户还得先判断“我是滚还是搜”。50 到 500 条这个区间比较尴尬比如部门列表、常见商品分类加不加都能用我的判断标准是看用户的使用频次高频重复选择的操作宁可加搜索因为熟练用户会直接输入关键词比滚轮快一个数量级低频一次性的选择保持原样更省事。超过 500 条基本没有讨论余地必须加两千条以上的列表不加搜索等于把筛选成本全部转嫁给用户。还有一个容易被忽略的维度是“选项名称的可输入性”。城市名、人名、商品名这类用户能准确说出来的搜索收益极大而像“方案 A / 方案 B / 方案 C”这种命名用户根本记不住全称搜索框反而变成摆设这时候应该改的是数据命名而不是加搜索。我在第二个项目里就踩过这个坑给一个只有编号的方案列表加了搜索结果后台数据显示使用率不到 3%用户还是靠滚因为没人记得住“技术方案-2023-修订版-B”这种鬼东西。1.2 三条技术路线对比与选型确定要加搜索之后摆在面前的有三条路我把它们放在一起对比过结论写在表里。方案改动量交互一致性多列联动支持维护成本适用场景改造 Picker 本体中约 150 行高保留原有滚轮手感好只是换数据源低逻辑集中在组件内大多数业务选择场景Popup Search List 自建大300 行以上中滚轮变成长列表滚动差级联要自己写中样式和交互都要自己维护单列且选项极多如商品库换成支持搜索的第三方组件小但引入依赖低与项目其余部分风格割裂视组件而定高升级受制于人新项目且团队认可新依赖我最终选的是第一条理由很实在项目里已经有七八处用到 van-picker交互手势、动效、无障碍标签都是用户熟悉的换组件等于把一致性成本重新付一遍。而自建列表方案我在商品选择的场景里用过一次因为那个场景选项有上万条需要虚拟滚动 分页搜索滚轮形态本身就不合适了——但那是特例不是常态。这里还有一个隐藏的决策点搜索是本地过滤还是服务端搜索。数据量在五千条以内、且能一次性拿到的情况下本地过滤完全够用响应是零延迟的数据量再大或者数据本身有权限过滤比如只能看到自己部门的员工就得走服务端。本地过滤的代码简单到不可思议服务端搜索则要处理防抖、加载状态、请求竞态这些额外问题能本地解决就别给自己找麻烦。1.3 整体设计思路数据层、视图层、状态层我给这个改造定了一个“三明治”结构分层想清楚了再写代码返工次数会少很多。数据层负责两件事一是保持原始 columns 不动它是唯一的真相来源二是预先给每条数据挂上拼音索引字段。这里强调“预先”因为拼音转换是个 CPU 密集活两千条数据在低端安卓机上现算要几百毫秒放在用户输入时算就是灾难正确做法是在数据加载完成的那一刻算一次存起来复用。视图层由三块组成顶部是搜索输入框和标题栏中间是 Picker 滚轮底部是确认区。三者之间的关系是搜索框只影响中间滚轮的候选集不影响最终提交的值。这一点听起来理所当然但我在第一版里就写错了——我把搜索关键词也当成了选择结果的一部分导致用户搜完“深圳”之后选中提交上来的值里混进了关键词后端直接报错。状态层是最容易出 bug 的地方。需要明确区分三个东西keyword用户输入的字符串、filteredColumns过滤后的候选集、selectedValue最终选中项的值。三者中只有 selectedValue 是业务关心的另外两个都是临时状态。记住这条线后面所有的索引重置、回显、清除关键词的逻辑都会顺畅很多。2. 动手前必须吃透的 Picker 内部机制2.1 columns 只是数据源index 才是真正的状态很多人对 Picker 的理解停留在“传个数组进去它就能滚”这是不够的。Picker 内部维护的是一组索引滚轮的每一个位置对应的是 columns 数组的下标它对外暴露的滚动、回调、选中底层都是索引在动。当你把 columns 从 2000 条变成 12 条的时候索引并不会自动跟着收敛它会保留原来的数值于是出现越界Vant 的处理方式是把这个索引钳制到边界或者直接归零表现就是“搜索后滚轮位置突然跳到第一个”或者“选中的项和显示的文字对不上”。理解了这一层很多诡异现象就有了解释。比如用户滚到第 800 项这时输入“深圳”候选集只剩 12 条索引 800 显然越界Vant 内部要么回退到第 11 项要么回到第 0 项两种表现都不是我们想要的——我们想要的是“过滤后默认停在第一项或者停在最匹配的那一项”。这个“想要的行为”必须由我们自己在数据变化后手动设置组件不会替我们猜。顺带说一个相关的量Picker 可见选项数是visible-option-num默认 6每项高度option-height默认 44px所以 Picker 主体的可视高度大概是 264px。搜索框加进去之后整个弹层的高度要重新算如果还用原来写死的高度小屏机型上滚轮会被挤压到只剩三四行很难操作。我的做法是弹层高度用百分比70% 左右或者calc(100% - 键盘高度)让内容自己去分配空间。2.2 Vant 2 与 Vant 3/4 的 API 差异对照这是最容易出事的地方网上大量教程是 Vue 2 时代的你直接抄到 Vue 3 项目里会发现方法根本不存在。我把关键差异整理成了表对照着看能省不少时间。能力Vant 2Vue 2Vant 3 / 4Vue 3获取选中值getValues()返回数组getSelectedOptions()返回选项对象数组设置单列选中索引setColumnIndex(columnIndex, optionIndex)setColumnIndex(columnIndex, optionIndex)设置多列索引setColumnIndex逐列调用setIndexes([0, 0])一次设置多列替换某列数据setColumnValues(index, values)主动推送直接改columns响应式数据必要时再setIndexes顶部内容插槽title/columns-top/columns-bottomtoolbar/title/columns-top/columns-bottom自定义选项渲染不支持只能传字符串或对象支持option插槽字段名映射value-key指定对象取值字段columns-field-names配置 text / value / children最大的差异是数据更新机制。Vant 2 有个著名的坑你直接修改传给columns的数组如果引用没变组件可能不会重新渲染社区里的标准解法是调用setColumnValues(index, newArray)把新数组推进去。Vant 3/4 改成了完全响应式直接改columns绑定的数据就会更新但也正因为走的是响应式索引的钳制行为变得更难预测反而更需要手动重置。另外提醒一句Vant 4 的getValues()还存在但已标记为不推荐返回的是 value 数组getSelectedOptions()返回的是完整选项对象能同时拿到 text 和 value做回显更方便。新项目直接用后者。2.3 过滤之后索引为什么会错乱把这个问题单独拎出来讲是因为它是整个改造里出现频率最高的 bug。举个具体例子原始列表[北京,上海,广州,...,深圳,...]深圳在第 800 位用户滚到深圳此时selectedIndex是 800。接着用户手抖点了一下搜索框输入“深圳”候选集变成[深圳]长度 1索引 800 越界。更隐蔽的一种错乱发生在“清除关键词”的时候。用户搜完“深圳”选中接着清空搜索框想改选别的此时候选集变回 2000 条而索引还停在过滤后的位置 0于是滚轮回到了“北京”用户一脸茫然我明明选的是深圳怎么变成北京了这个问题的根源在于我们没有把“选中值”和“索引”解耦。正确做法是选中结果始终用 value 记录每次候选集变化后用这个 value 去新数组里反查索引查得到就定位过去查不到就回到 0并在界面上给一点提示。我在代码里把这段逻辑抽成了一个函数叫syncIndexByValue它接收当前选中的 value 和过滤后的数组返回应该设置的索引。这个函数在“输入关键词”“清空关键词”“重新打开弹层”三个时机都会调用保证索引始终跟着值走而不是跟着上一次的滚动位置走。2.4 中文搜索的两级匹配全拼与首字母只做中文全字匹配就等着被用户教育。真实用户的输入习惯分成三类完整中文“深圳”、全拼“shenzhen”、首字母“sz”三者都要覆盖。中文全字匹配最简单includes一下就行后两种需要拼音。拼音索引的生成时机前面说过了在数据加载时一次性算好挂到每条数据上格式建议是“全拼 空格 首字母”比如深圳存成shenzhen sz这样一次includes就能同时命中两种输入不用写两套判断。字符串会稍微长一点但两千条数据的内存占用完全可以忽略换来的是一次索引、多次复用的效率。还有个细节是大小写和空格。用户输入“ ShenZhen ”的情况很常见尤其是从别的地方复制过来的时候所以匹配前统一trim().toLowerCase()。另外中文标点也是个坑像“北京·朝阳”这种带间隔号的名称用户输入“北京朝阳”匹配不上我的处理是在生成索引时把非字母数字汉字的字符统一剔除生成一份“净化版”文本专门用于匹配展示时仍然用原文。这个做法在数据里含有括号、破折号、全角空格的时候特别好用。3. 完整实现从零封装一个带搜索的 Picker3.1 组件骨架与 props 设计先定接口。一个能被复用的组件props 的设计比实现更重要。我的签名是这样的show控制弹层显隐columns传数据title是标题modelValue是当前选中值用 value 而不是索引fieldNames允许外部指定 text / value 字段名pinyinField指定拼音字段名方便外部自定义。事件上只需要暴露update:show和confirm两个confirm的载荷是完整的选项对象而不是数组因为单列 Picker 的场景下返回数组纯属添乱。组件内部结构分三层头部工具栏取消 / 标题 / 确定、搜索区、滚轮区。头部我选择自己写而不是用 Vant 的默认工具栏原因是搜索框需要占一整行Vant 的工具栏只能放一个标题和两个按钮塞不下。自己写的好处还有样式完全可控按钮的禁用态、确认时的 loading 都能按业务加。有一点要提前说明这套代码基于 Vant 4 Vue 3 的script setup写法Vant 2 的等价实现放在 3.5 节。两者的结构是一样的差别集中在方法调用上理解了结构切换版本就是改几行的事。3.2 搜索框放哪里三种位置的取舍位置选择直接影响交互手感我试过三种说说各自的体验。第一种是用 Picker 的columns-top插槽把搜索框塞进 Picker 内部。好处是 DOM 结构紧凑滚动区域和搜索框是一体的坏处是这个插槽在 Vant 2 和 Vant 4 里的表现不完全一致某些版本上插槽内容会跟着滚轮一起被裁剪而且输入框的点击事件偶尔会被滚轮容器吞掉表现为“点了没反应要点第二次”。我在两个项目里都遇到过类似问题最后放弃了这条路。第二种是自建头部区域搜索框放在 Picker 外面的弹层里两者是兄弟节点。这是我最推荐的方案事件边界清晰输入框和滚轮的触摸区域互不干扰样式想怎么调就怎么调而且跨版本最稳从 Vant 2 到 Vant 4 都不用改结构。第三种是把搜索框做成悬浮在滚轮上方的浮层只在输入时展开。这个方案视觉上最“轻”但它对新手不友好——用户不点开根本不知道这里能搜等于白做。除非产品明确要求极简视觉否则别选。我选第二种并且把搜索区固定在头部下方不随滚轮滚动。这样用户输入的时候视线稳定键盘弹出来也不会把输入框顶出屏幕后面 4.2 节会讲怎么处理键盘。3.3 过滤逻辑与索引重置的核心代码现在是主菜。先看模板部分我尽量写得完整可用。template van-popup v-model:showvisible positionbottom round :style{ height: 70% } closedonClosed div classsearch-picker !-- 头部工具栏 -- div classsearch-picker__header span classsearch-picker__btn clickvisible false取消/span span classsearch-picker__title{{ title }}/span span classsearch-picker__btn search-picker__btn--primary :class{ is-disabled: !canConfirm } clickhandleConfirm 确定/span /div !-- 搜索区 -- div classsearch-picker__search touchmove.stop van-search v-modelkeyword placeholder输入名称或拼音首字母 shaperound clearable / /div !-- 滚轮区 -- div classsearch-picker__body van-picker v-iffilteredColumns.length refpickerRef :columnsfilteredColumns :show-toolbarfalse :default-indexinitialIndex :columns-field-namesfieldNames changehandleChange template #optionoption span classpicker-option v-htmlhighlight(option.text) / /template /van-picker van-empty v-else imagesearch description没有找到匹配的选项换个关键词试试 / /div /div /van-popup /template这段模板里有几个决策点值得展开。touchmove.stop加在搜索区上是为了阻断触摸事件冒泡到滚轮容器否则在输入框上滑动时下面的滚轮会跟着动非常割裂。v-if切换滚轮和空状态而不是在滚轮里塞一个“无结果”选项是因为 Vant 的滚轮需要至少一个有效选项才正常渲染塞假数据会污染候选集用户还能选中它。:show-toolbarfalse关掉 Vant 自带的工具栏因为我们自己写了一个。接下来是脚本部分核心是过滤和索引同步。import { ref, computed, watch, nextTick } from vue const props defineProps({ show: { type: Boolean, default: false }, title: { type: String, default: 请选择 }, columns: { type: Array, default: () [] }, modelValue: { type: [String, Number], default: }, fieldNames: { type: Object, default: () ({ text: text, value: value }) }, pinyinField: { type: String, default: pinyin } }) const emit defineEmits([update:show, confirm]) const visible computed({ get: () props.show, set: (val) emit(update:show, val) }) const keyword ref() const pickerRef ref(null) const selectedValue ref(props.modelValue) const initialIndex ref(0) const canConfirm ref(true) // 把选项统一成可比较的字符串 const getText (item) { if (item null || item undefined) return return typeof item string ? item : String(item[props.fieldNames.text] ?? ) } const getValue (item) { if (typeof item string) return item return item[props.fieldNames.value] } // 去掉标点与空格专供匹配使用 const purify (str) str.replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() const filteredColumns computed(() { const kw purify(keyword.value) if (!kw) return props.columns return props.columns.filter((item) { const text purify(getText(item)) const py typeof item object item ! null ? String(item[props.pinyinField] || ).toLowerCase() : return text.includes(kw) || py.includes(kw) }) })过滤函数就这么多purify是关键它同时解决了标点干扰和大小写问题。拼音字段pinyin里存的是“全拼 空格 首字母”所以一次includes同时覆盖两种输入。再看索引同步这是防止错乱的保险丝。// 根据 value 在新候选集中反查索引 const syncIndexByValue () { const list filteredColumns.value if (!list.length) return const idx list.findIndex((item) getValue(item) selectedValue.value) initialIndex.value idx -1 ? idx : 0 } watch(filteredColumns, async () { canConfirm.value filteredColumns.value.length 0 await nextTick() syncIndexByValue() if (pickerRef.value filteredColumns.value.length) { pickerRef.value.setIndexes([initialIndex.value]) } }) // 打开弹层时重置搜索状态 watch( () props.show, (val) { if (!val) return selectedValue.value props.modelValue keyword.value nextTick(syncIndexByValue) } ) const handleChange ({ selectedOptions }) { const opt selectedOptions selectedOptions[0] if (!opt) return selectedValue.value getValue(opt) } const handleConfirm () { if (!canConfirm.value) return const opt filteredColumns.value.find( (item) getValue(item) selectedValue.value ) emit(confirm, opt) visible.value false } const onClosed () { keyword.value }这段代码里有两个 watch分别负责“候选集变化时同步索引”和“弹层打开时重置状态”逻辑分开了可读性和可维护性都比堆在一个 watch 里强。setIndexes([initialIndex.value])在nextTick之后调用是必须的因为v-if切换时 Picker 可能刚被重新创建直接调方法会拿到 null 引用。还有一个容易漏的点getValue对字符串类型的选项返回字符串本身所以selectedValue的初始值必须和 columns 里的值类型一致。如果 columns 是[北京, 上海]而你把modelValue传成了数字或者带了空格反查就会失败索引永远停在 0。这种类型不一致的问题在联调时特别难查建议在组件里加一个开发环境的类型校验警告。3.4 关键词高亮与无结果占位高亮不是必需品但加上之后用户的“命中感”会强很多尤其是拼音匹配的场景——用户搜“sz”列表里“深圳”两个中文字被标黄他立刻明白为什么这个词出现在结果里。实现上用option插槽配合v-html但必须有转义否则数据里的尖括号会直接变成标签。const escapeHtml (str) String(str).replace(/[]/g, (c) ({ : amp;, : lt;, : gt;, : quot;, : #39; }[c])) const highlight (text) { const safe escapeHtml(text) const kw keyword.value.trim() if (!kw) return safe const escaped kw.replace(/[.*?^${}()|[\]\\]/g, \\$) return safe.replace( new RegExp((${escaped}), gi), span classkw-hit$1/span ) }注意escapeHtml必须在拼接正则之前执行顺序反了就会有注入风险。高亮只对中文文本生效拼音匹配的情况下文本里没有关键词不会误标这是符合预期的。无结果状态用van-empty文案别写“暂无数据”这种冷冰冰的话改成“没有找到匹配的选项换个关键词试试”给用户一个下一步动作的暗示。同时要把确认按钮置灰否则用户点确认会提交一个空值。这里还有个细节置灰用样式加pointer-events还是用逻辑拦截我两个都做了样式上给一个禁用视觉逻辑上handleConfirm里再判断一次因为有些用户会用键盘回车触发绕过视觉拦截。3.5 Vue 2 Vant 2 的适配写法老项目升级成本高很多时候只能原地改所以这版也得给。结构完全一样差别有四处。第一处是数据定义用data()返回filteredColumns用computed计算写法基本一致。第二处是事件绑定v-model:show换成v-model加.sync的写法或者直接监听input事件手动改。第三处是插槽Vant 2 不支持option插槽高亮功能只能放弃或者改用columns里传带 HTML 的对象不推荐有安全风险。第四处也是最关键的数据更新机制不同。// Vant 2 中过滤变化后的处理 watch: { filteredColumns(val) { this.canConfirm val.length 0 this.$nextTick(() { if (!this.$refs.picker || !val.length) return const idx val.findIndex( (item) this.getValue(item) this.selectedValue ) const target idx -1 ? idx : 0 // 先推送新数据再设置索引顺序不能反 this.$refs.picker.setColumnValues(0, val) this.$refs.picker.setColumnIndex(0, target) }) } }setColumnValues和setColumnIndex的调用顺序是硬性要求反了的话索引会基于旧数组计算还是会错位。这个坑我在两个项目里各踩过一次现在写代码前都会先在注释里把顺序标出来。另外 Vant 2 的getValues()返回的是数组input事件回调里拿到的picker实例提供的值需要自己取第一项。整体上 Vant 2 版本要多写十几行胶水代码但核心思路和 Vant 4 完全一致迁移的时候基本是搬运。4. 踩坑记录与问题排查速查表4.1 常见问题速查表下面这张表是我在三个项目里攒下来的遇到现象先查表能省掉一半的调试时间。现象根因排查手段解决方式搜索后滚轮位置乱跳过滤后数组变短旧索引越界在 change 回调里打印索引与数组长度候选集变化后nextTick里setIndexes重置清空关键词后选中项变了索引未随值回填停在过滤后的位置对比选中值与滚轮文字用 value 反查索引不用缓存的位置输入框点两次才聚焦触摸事件被滚轮容器吞掉在 input 上监听 click 与 touchstart 计数搜索区加touchmove.stop避免插槽嵌套输入时卡顿每次输入都重算拼音或重建大数组Performance 面板看 computed 耗时拼音预生成 computed 缓存提交上来的值里混进关键词把 keyword 当成了选中值打日志看 confirm 的载荷分离 keyword 与 selectedValue小屏机滚轮只剩三行弹层高度写死搜索区挤压在小屏真机或模拟器上看高度改百分比或calc(100% - 键盘高度)拼音搜不到拼音字段为空或大小写未统一打印某条数据的 pinyin 字段生成索引时统一小写并去标点选中项与文本不一致columns 对象字段名与 fieldNames 不匹配检查 columns-field-names统一字段名或在组件里做兼容映射4.2 软键盘弹起导致的遮挡与滚动冲突移动端最烦的就是键盘它弹起来会改变可视区域高度而底部弹层是基于视口定位的结果就是搜索框被顶到屏幕中间甚至上方滚轮被键盘完全盖住。我在 iOS 和安卓上各测了一遍行为还不一样iOS 上视口会整体上移安卓部分机型是压缩视口高度。我的处理方式是监听窗口的resize事件用弹层打开时的高度减去当前高度估算出键盘高度然后把弹层的高度动态改成calc(100% - 键盘高度)。这个方法不完美因为安卓某些机型不触发resize但配合visualViewportAPI 就能覆盖大部分情况。如果不想这么麻烦还有一个更省事的思路输入框聚焦时把滚轮区域的高度临时压缩让搜索框始终贴在被键盘顶起的位置上方用户输完再恢复。实测这个方案在两年前的安卓机上也能跑得比较稳。滚动冲突是另一个高频问题。搜索框和滚轮靠得很近用户在输入框上滑动想看看后面的内容结果下面的滚轮动了输入框失焦键盘收起页面跳动。解决就是在搜索区阻断触摸事件冒泡同时给输入框加touchstart.stop。代价是用户没法在搜索区上下滑动页面但在弹层场景里本来就不需要滑动页面所以没有副作用。4.3 上千条数据下的性能实测我把过滤逻辑放在两千三百条城市数据上测了一遍中端安卓机约三年前的中端芯片上的结果是单次过滤大约 1 到 3 毫秒完全感觉不到卡顿。这个数字比我预期的小原因是Array.prototype.filter配合String.includes在 V8 里的优化很好两千次字符串匹配的耗时很短。所以我的结论很明确五千条以内不需要做防抖也不需要 Web Worker直接过滤就行过度优化反而增加代码复杂度。真正需要警惕的是拼音索引的生成两千条数据用拼音库全量转换一次大概在 300 到 800 毫秒之间这个开销放在输入时是绝对不行的放在页面初始化时也会让首屏卡一下。我的做法是把这一步挪到“数据请求回来之后、渲染之前”用一个 loading 状态盖住或者干脆在服务端把拼音字段一起返回。后者是最优解只要后端配合前端就完全没有这个开销字段体积增加不到 20%非常划算。还有一个容易被忽略的性能点van-search组件的v-model更新频率很高每次输入都会触发filteredColumns重算。如果列表项渲染本身很重比如每项还带图标可以给 keyword 加一个 200 毫秒的防抖减少重渲染次数。这个防抖在五千条以上才有必要两千条加了反而让输入感觉粘手。4.4 多列联动省市区场景怎么搜单列好办多列联动的搜索是另一个量级的复杂度。用户输入“朝阳”你希望他直接选中“北京市 / 北京市 / 朝阳区”但 Picker 的联动结构是三级嵌套的搜索只能在某一列里发生这就要求我们把树形结构拍平成路径。我的做法是正常情况下保持三级联动的原样用户一旦输入关键词就把整棵树拍平成一列每项的文本是“省 / 市 / 区”的完整路径值是叶子节点的值清空关键词后再切回三级联动模式并根据选中的叶子值反推各级索引。拍平的逻辑大概是这样。function flattenCascade(tree, path [], result []) { tree.forEach((node) { const nextPath [...path, node] if (node.children node.children.length) { flattenCascade(node.children, nextPath, result) } else { result.push({ text: nextPath.map((n) n.text).join( / ), value: node.value, // 记录路径用于切回联动模式时定位 pathValues: nextPath.map((n) n.value) }) } }) return result }这里额外存了pathValues它的用途是切回联动模式时用这个路径数组去设置每一列的索引比用 value 逐级反查更直接、更不容易出错。切换模式的时候要记得把 Picker 整个重建用key强制刷新因为列数从 1 变 3 或者从 3 变 1组件内部的列状态不是简单重置能清干净的这是我在测试时发现的一个隐蔽 bug从搜索模式切回联动模式第三列的数据残留了上一次的内容用 key 重建是最省心的解法。5. 可以继续往下做的两件事5.1 把拼音索引提前到数据构建阶段前面反复提到预生成拼音字段这里给一个具体的实现用的是社区里常用的拼音转换库思路是同时产出全拼和首字母用空格分隔保存在同一个字段里。import { pinyin } from pinyin-pro const purify (str) str.replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() export function buildPinyinIndex(list, textField text) { return list.map((item) { const text typeof item string ? item : item[textField] const clean purify(text || ) // 兜底写法不依赖特定选项名取完整拼音后手动截首字母 const arr clean ? pinyin(clean, { toneType: none, type: array }) : [] const full arr.join() const initial arr.map((s) s[0] || ).join() const py ${full} ${initial}.toLowerCase() return typeof item string ? { text: item, value: item, pinyin: py } : { ...item, pinyin: py } }) }这里我特意用了“取完整拼音数组再手动截首字母”的写法而不是依赖某个特定的选项名因为不同版本的拼音库选项名有细微差异写成这样在任何版本上都能跑。如果你的数据里有大量多音字比如“重庆”的“重”库里一般有词库能处理正确但如果数据是冷门地名建议在服务端人工校对一遍或者允许运营在后台手动覆盖拼音字段。5.2 抽成可复用的组合式函数组件写完之后我发现过滤逻辑和索引同步逻辑可以完全脱离 UI 复用。比如另一个页面用的是自建列表而不是 Picker同样需要“关键词过滤 拼音匹配 值反查”这三件事。于是我把这部分抽成了一个组合式函数接收原始列表、关键词、字段配置返回过滤后的列表和一个反查函数。import { computed, unref } from vue export function useFilterColumns(columns, keyword, options {}) { const { textField text, valueField value, pinyinField pinyin } options const purify (s) String(s || ).replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() const filtered computed(() { const list unref(columns) || [] const kw purify(unref(keyword)) if (!kw) return list return list.filter((item) { const text purify(typeof item string ? item : item[textField]) const py typeof item object item ? String(item[pinyinField] || ).toLowerCase() : return text.includes(kw) || py.includes(kw) }) }) const indexOfValue (value) { const list filtered.value return list.findIndex((item) (typeof item string ? item : item[valueField]) value ) } return { filtered, indexOfValue } }抽出来之后主组件少了三十多行另一个列表页面直接引入就能用。这种“先写通、再抽取”的顺序比一上来就设计通用方案要靠谱因为只有写通了你才知道哪些是真正共用的部分哪些只是看起来像共用。我在实际项目里的体会是给 Picker 加搜索这件事代码量其实不大真正花时间的是把索引、值、关键词这三者的关系理顺。理顺之后你会发现同样的思路可以用在很多地方级联选择、树形下拉、带搜索的穿梭框本质上都是“候选集变化后如何维持选中状态”这一个问题。踩过几次坑之后我养成了一个习惯凡是涉及列表过滤的地方先把“用值不用索引”这条写进注释里后面接手的人会少走很多弯路。还有一个实用的小技巧在开发阶段给组件加一个调试开关打开后把当前关键词、候选集长度、索引、选中值一起打印到控制台排查问题时比反复打断点快得多上线前把开关关掉就行。
Vant Picker 搜索改造：城市长列表过滤与拼音索引同步
前段时间帮一个做本地生活的团队改移动端 H5里面有个城市选择弹层全国三百多个地级市加上下辖区县拢共两千三百多条数据原封不动塞进一个 vant picker 里让用户靠手指滚。上线第二天测试同学就在群里甩了一句“选个深圳要滚到我怀疑人生”产品跟着补刀“能不能加个搜索”。于是就有了这次改造给 vant picker 选择器组件增加 search 搜索功能。这件事听起来只是“加个输入框过滤一下”真动手才会发现坑集中在两个地方——Picker 的选中状态其实是索引而不是值以及中文列表的搜索体验如果只做全字匹配用户搜“sz”找不到深圳照样骂人。这篇文章写给已经用过 Vant、正在被长列表滚轮折磨的前端同学也写给刚接触移动端组件库、想知道“组件不够用的时候该怎么改”的新手。Vue 2 Vant 2 和 Vue 3 Vant 4 两套写法我都会给代码可以直接抄走改成自己的业务组件。文中所有关于数据量、耗时的描述都来自我在几个真实项目里的实测参数怎么选、为什么这么选我也会一并说清楚尽量让你少走一遍我走过的弯路。1. 改造之前先想清楚搜索能力该长在哪一层1.1 我遇到的真实场景与数据规模先做个经验分档不是所有 Picker 都值得加搜索。选项在 50 条以内的比如性别、证件类型、订单状态滚轮两三下就能到硬塞一个搜索框反而增加认知负担用户还得先判断“我是滚还是搜”。50 到 500 条这个区间比较尴尬比如部门列表、常见商品分类加不加都能用我的判断标准是看用户的使用频次高频重复选择的操作宁可加搜索因为熟练用户会直接输入关键词比滚轮快一个数量级低频一次性的选择保持原样更省事。超过 500 条基本没有讨论余地必须加两千条以上的列表不加搜索等于把筛选成本全部转嫁给用户。还有一个容易被忽略的维度是“选项名称的可输入性”。城市名、人名、商品名这类用户能准确说出来的搜索收益极大而像“方案 A / 方案 B / 方案 C”这种命名用户根本记不住全称搜索框反而变成摆设这时候应该改的是数据命名而不是加搜索。我在第二个项目里就踩过这个坑给一个只有编号的方案列表加了搜索结果后台数据显示使用率不到 3%用户还是靠滚因为没人记得住“技术方案-2023-修订版-B”这种鬼东西。1.2 三条技术路线对比与选型确定要加搜索之后摆在面前的有三条路我把它们放在一起对比过结论写在表里。方案改动量交互一致性多列联动支持维护成本适用场景改造 Picker 本体中约 150 行高保留原有滚轮手感好只是换数据源低逻辑集中在组件内大多数业务选择场景Popup Search List 自建大300 行以上中滚轮变成长列表滚动差级联要自己写中样式和交互都要自己维护单列且选项极多如商品库换成支持搜索的第三方组件小但引入依赖低与项目其余部分风格割裂视组件而定高升级受制于人新项目且团队认可新依赖我最终选的是第一条理由很实在项目里已经有七八处用到 van-picker交互手势、动效、无障碍标签都是用户熟悉的换组件等于把一致性成本重新付一遍。而自建列表方案我在商品选择的场景里用过一次因为那个场景选项有上万条需要虚拟滚动 分页搜索滚轮形态本身就不合适了——但那是特例不是常态。这里还有一个隐藏的决策点搜索是本地过滤还是服务端搜索。数据量在五千条以内、且能一次性拿到的情况下本地过滤完全够用响应是零延迟的数据量再大或者数据本身有权限过滤比如只能看到自己部门的员工就得走服务端。本地过滤的代码简单到不可思议服务端搜索则要处理防抖、加载状态、请求竞态这些额外问题能本地解决就别给自己找麻烦。1.3 整体设计思路数据层、视图层、状态层我给这个改造定了一个“三明治”结构分层想清楚了再写代码返工次数会少很多。数据层负责两件事一是保持原始 columns 不动它是唯一的真相来源二是预先给每条数据挂上拼音索引字段。这里强调“预先”因为拼音转换是个 CPU 密集活两千条数据在低端安卓机上现算要几百毫秒放在用户输入时算就是灾难正确做法是在数据加载完成的那一刻算一次存起来复用。视图层由三块组成顶部是搜索输入框和标题栏中间是 Picker 滚轮底部是确认区。三者之间的关系是搜索框只影响中间滚轮的候选集不影响最终提交的值。这一点听起来理所当然但我在第一版里就写错了——我把搜索关键词也当成了选择结果的一部分导致用户搜完“深圳”之后选中提交上来的值里混进了关键词后端直接报错。状态层是最容易出 bug 的地方。需要明确区分三个东西keyword用户输入的字符串、filteredColumns过滤后的候选集、selectedValue最终选中项的值。三者中只有 selectedValue 是业务关心的另外两个都是临时状态。记住这条线后面所有的索引重置、回显、清除关键词的逻辑都会顺畅很多。2. 动手前必须吃透的 Picker 内部机制2.1 columns 只是数据源index 才是真正的状态很多人对 Picker 的理解停留在“传个数组进去它就能滚”这是不够的。Picker 内部维护的是一组索引滚轮的每一个位置对应的是 columns 数组的下标它对外暴露的滚动、回调、选中底层都是索引在动。当你把 columns 从 2000 条变成 12 条的时候索引并不会自动跟着收敛它会保留原来的数值于是出现越界Vant 的处理方式是把这个索引钳制到边界或者直接归零表现就是“搜索后滚轮位置突然跳到第一个”或者“选中的项和显示的文字对不上”。理解了这一层很多诡异现象就有了解释。比如用户滚到第 800 项这时输入“深圳”候选集只剩 12 条索引 800 显然越界Vant 内部要么回退到第 11 项要么回到第 0 项两种表现都不是我们想要的——我们想要的是“过滤后默认停在第一项或者停在最匹配的那一项”。这个“想要的行为”必须由我们自己在数据变化后手动设置组件不会替我们猜。顺带说一个相关的量Picker 可见选项数是visible-option-num默认 6每项高度option-height默认 44px所以 Picker 主体的可视高度大概是 264px。搜索框加进去之后整个弹层的高度要重新算如果还用原来写死的高度小屏机型上滚轮会被挤压到只剩三四行很难操作。我的做法是弹层高度用百分比70% 左右或者calc(100% - 键盘高度)让内容自己去分配空间。2.2 Vant 2 与 Vant 3/4 的 API 差异对照这是最容易出事的地方网上大量教程是 Vue 2 时代的你直接抄到 Vue 3 项目里会发现方法根本不存在。我把关键差异整理成了表对照着看能省不少时间。能力Vant 2Vue 2Vant 3 / 4Vue 3获取选中值getValues()返回数组getSelectedOptions()返回选项对象数组设置单列选中索引setColumnIndex(columnIndex, optionIndex)setColumnIndex(columnIndex, optionIndex)设置多列索引setColumnIndex逐列调用setIndexes([0, 0])一次设置多列替换某列数据setColumnValues(index, values)主动推送直接改columns响应式数据必要时再setIndexes顶部内容插槽title/columns-top/columns-bottomtoolbar/title/columns-top/columns-bottom自定义选项渲染不支持只能传字符串或对象支持option插槽字段名映射value-key指定对象取值字段columns-field-names配置 text / value / children最大的差异是数据更新机制。Vant 2 有个著名的坑你直接修改传给columns的数组如果引用没变组件可能不会重新渲染社区里的标准解法是调用setColumnValues(index, newArray)把新数组推进去。Vant 3/4 改成了完全响应式直接改columns绑定的数据就会更新但也正因为走的是响应式索引的钳制行为变得更难预测反而更需要手动重置。另外提醒一句Vant 4 的getValues()还存在但已标记为不推荐返回的是 value 数组getSelectedOptions()返回的是完整选项对象能同时拿到 text 和 value做回显更方便。新项目直接用后者。2.3 过滤之后索引为什么会错乱把这个问题单独拎出来讲是因为它是整个改造里出现频率最高的 bug。举个具体例子原始列表[北京,上海,广州,...,深圳,...]深圳在第 800 位用户滚到深圳此时selectedIndex是 800。接着用户手抖点了一下搜索框输入“深圳”候选集变成[深圳]长度 1索引 800 越界。更隐蔽的一种错乱发生在“清除关键词”的时候。用户搜完“深圳”选中接着清空搜索框想改选别的此时候选集变回 2000 条而索引还停在过滤后的位置 0于是滚轮回到了“北京”用户一脸茫然我明明选的是深圳怎么变成北京了这个问题的根源在于我们没有把“选中值”和“索引”解耦。正确做法是选中结果始终用 value 记录每次候选集变化后用这个 value 去新数组里反查索引查得到就定位过去查不到就回到 0并在界面上给一点提示。我在代码里把这段逻辑抽成了一个函数叫syncIndexByValue它接收当前选中的 value 和过滤后的数组返回应该设置的索引。这个函数在“输入关键词”“清空关键词”“重新打开弹层”三个时机都会调用保证索引始终跟着值走而不是跟着上一次的滚动位置走。2.4 中文搜索的两级匹配全拼与首字母只做中文全字匹配就等着被用户教育。真实用户的输入习惯分成三类完整中文“深圳”、全拼“shenzhen”、首字母“sz”三者都要覆盖。中文全字匹配最简单includes一下就行后两种需要拼音。拼音索引的生成时机前面说过了在数据加载时一次性算好挂到每条数据上格式建议是“全拼 空格 首字母”比如深圳存成shenzhen sz这样一次includes就能同时命中两种输入不用写两套判断。字符串会稍微长一点但两千条数据的内存占用完全可以忽略换来的是一次索引、多次复用的效率。还有个细节是大小写和空格。用户输入“ ShenZhen ”的情况很常见尤其是从别的地方复制过来的时候所以匹配前统一trim().toLowerCase()。另外中文标点也是个坑像“北京·朝阳”这种带间隔号的名称用户输入“北京朝阳”匹配不上我的处理是在生成索引时把非字母数字汉字的字符统一剔除生成一份“净化版”文本专门用于匹配展示时仍然用原文。这个做法在数据里含有括号、破折号、全角空格的时候特别好用。3. 完整实现从零封装一个带搜索的 Picker3.1 组件骨架与 props 设计先定接口。一个能被复用的组件props 的设计比实现更重要。我的签名是这样的show控制弹层显隐columns传数据title是标题modelValue是当前选中值用 value 而不是索引fieldNames允许外部指定 text / value 字段名pinyinField指定拼音字段名方便外部自定义。事件上只需要暴露update:show和confirm两个confirm的载荷是完整的选项对象而不是数组因为单列 Picker 的场景下返回数组纯属添乱。组件内部结构分三层头部工具栏取消 / 标题 / 确定、搜索区、滚轮区。头部我选择自己写而不是用 Vant 的默认工具栏原因是搜索框需要占一整行Vant 的工具栏只能放一个标题和两个按钮塞不下。自己写的好处还有样式完全可控按钮的禁用态、确认时的 loading 都能按业务加。有一点要提前说明这套代码基于 Vant 4 Vue 3 的script setup写法Vant 2 的等价实现放在 3.5 节。两者的结构是一样的差别集中在方法调用上理解了结构切换版本就是改几行的事。3.2 搜索框放哪里三种位置的取舍位置选择直接影响交互手感我试过三种说说各自的体验。第一种是用 Picker 的columns-top插槽把搜索框塞进 Picker 内部。好处是 DOM 结构紧凑滚动区域和搜索框是一体的坏处是这个插槽在 Vant 2 和 Vant 4 里的表现不完全一致某些版本上插槽内容会跟着滚轮一起被裁剪而且输入框的点击事件偶尔会被滚轮容器吞掉表现为“点了没反应要点第二次”。我在两个项目里都遇到过类似问题最后放弃了这条路。第二种是自建头部区域搜索框放在 Picker 外面的弹层里两者是兄弟节点。这是我最推荐的方案事件边界清晰输入框和滚轮的触摸区域互不干扰样式想怎么调就怎么调而且跨版本最稳从 Vant 2 到 Vant 4 都不用改结构。第三种是把搜索框做成悬浮在滚轮上方的浮层只在输入时展开。这个方案视觉上最“轻”但它对新手不友好——用户不点开根本不知道这里能搜等于白做。除非产品明确要求极简视觉否则别选。我选第二种并且把搜索区固定在头部下方不随滚轮滚动。这样用户输入的时候视线稳定键盘弹出来也不会把输入框顶出屏幕后面 4.2 节会讲怎么处理键盘。3.3 过滤逻辑与索引重置的核心代码现在是主菜。先看模板部分我尽量写得完整可用。template van-popup v-model:showvisible positionbottom round :style{ height: 70% } closedonClosed div classsearch-picker !-- 头部工具栏 -- div classsearch-picker__header span classsearch-picker__btn clickvisible false取消/span span classsearch-picker__title{{ title }}/span span classsearch-picker__btn search-picker__btn--primary :class{ is-disabled: !canConfirm } clickhandleConfirm 确定/span /div !-- 搜索区 -- div classsearch-picker__search touchmove.stop van-search v-modelkeyword placeholder输入名称或拼音首字母 shaperound clearable / /div !-- 滚轮区 -- div classsearch-picker__body van-picker v-iffilteredColumns.length refpickerRef :columnsfilteredColumns :show-toolbarfalse :default-indexinitialIndex :columns-field-namesfieldNames changehandleChange template #optionoption span classpicker-option v-htmlhighlight(option.text) / /template /van-picker van-empty v-else imagesearch description没有找到匹配的选项换个关键词试试 / /div /div /van-popup /template这段模板里有几个决策点值得展开。touchmove.stop加在搜索区上是为了阻断触摸事件冒泡到滚轮容器否则在输入框上滑动时下面的滚轮会跟着动非常割裂。v-if切换滚轮和空状态而不是在滚轮里塞一个“无结果”选项是因为 Vant 的滚轮需要至少一个有效选项才正常渲染塞假数据会污染候选集用户还能选中它。:show-toolbarfalse关掉 Vant 自带的工具栏因为我们自己写了一个。接下来是脚本部分核心是过滤和索引同步。import { ref, computed, watch, nextTick } from vue const props defineProps({ show: { type: Boolean, default: false }, title: { type: String, default: 请选择 }, columns: { type: Array, default: () [] }, modelValue: { type: [String, Number], default: }, fieldNames: { type: Object, default: () ({ text: text, value: value }) }, pinyinField: { type: String, default: pinyin } }) const emit defineEmits([update:show, confirm]) const visible computed({ get: () props.show, set: (val) emit(update:show, val) }) const keyword ref() const pickerRef ref(null) const selectedValue ref(props.modelValue) const initialIndex ref(0) const canConfirm ref(true) // 把选项统一成可比较的字符串 const getText (item) { if (item null || item undefined) return return typeof item string ? item : String(item[props.fieldNames.text] ?? ) } const getValue (item) { if (typeof item string) return item return item[props.fieldNames.value] } // 去掉标点与空格专供匹配使用 const purify (str) str.replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() const filteredColumns computed(() { const kw purify(keyword.value) if (!kw) return props.columns return props.columns.filter((item) { const text purify(getText(item)) const py typeof item object item ! null ? String(item[props.pinyinField] || ).toLowerCase() : return text.includes(kw) || py.includes(kw) }) })过滤函数就这么多purify是关键它同时解决了标点干扰和大小写问题。拼音字段pinyin里存的是“全拼 空格 首字母”所以一次includes同时覆盖两种输入。再看索引同步这是防止错乱的保险丝。// 根据 value 在新候选集中反查索引 const syncIndexByValue () { const list filteredColumns.value if (!list.length) return const idx list.findIndex((item) getValue(item) selectedValue.value) initialIndex.value idx -1 ? idx : 0 } watch(filteredColumns, async () { canConfirm.value filteredColumns.value.length 0 await nextTick() syncIndexByValue() if (pickerRef.value filteredColumns.value.length) { pickerRef.value.setIndexes([initialIndex.value]) } }) // 打开弹层时重置搜索状态 watch( () props.show, (val) { if (!val) return selectedValue.value props.modelValue keyword.value nextTick(syncIndexByValue) } ) const handleChange ({ selectedOptions }) { const opt selectedOptions selectedOptions[0] if (!opt) return selectedValue.value getValue(opt) } const handleConfirm () { if (!canConfirm.value) return const opt filteredColumns.value.find( (item) getValue(item) selectedValue.value ) emit(confirm, opt) visible.value false } const onClosed () { keyword.value }这段代码里有两个 watch分别负责“候选集变化时同步索引”和“弹层打开时重置状态”逻辑分开了可读性和可维护性都比堆在一个 watch 里强。setIndexes([initialIndex.value])在nextTick之后调用是必须的因为v-if切换时 Picker 可能刚被重新创建直接调方法会拿到 null 引用。还有一个容易漏的点getValue对字符串类型的选项返回字符串本身所以selectedValue的初始值必须和 columns 里的值类型一致。如果 columns 是[北京, 上海]而你把modelValue传成了数字或者带了空格反查就会失败索引永远停在 0。这种类型不一致的问题在联调时特别难查建议在组件里加一个开发环境的类型校验警告。3.4 关键词高亮与无结果占位高亮不是必需品但加上之后用户的“命中感”会强很多尤其是拼音匹配的场景——用户搜“sz”列表里“深圳”两个中文字被标黄他立刻明白为什么这个词出现在结果里。实现上用option插槽配合v-html但必须有转义否则数据里的尖括号会直接变成标签。const escapeHtml (str) String(str).replace(/[]/g, (c) ({ : amp;, : lt;, : gt;, : quot;, : #39; }[c])) const highlight (text) { const safe escapeHtml(text) const kw keyword.value.trim() if (!kw) return safe const escaped kw.replace(/[.*?^${}()|[\]\\]/g, \\$) return safe.replace( new RegExp((${escaped}), gi), span classkw-hit$1/span ) }注意escapeHtml必须在拼接正则之前执行顺序反了就会有注入风险。高亮只对中文文本生效拼音匹配的情况下文本里没有关键词不会误标这是符合预期的。无结果状态用van-empty文案别写“暂无数据”这种冷冰冰的话改成“没有找到匹配的选项换个关键词试试”给用户一个下一步动作的暗示。同时要把确认按钮置灰否则用户点确认会提交一个空值。这里还有个细节置灰用样式加pointer-events还是用逻辑拦截我两个都做了样式上给一个禁用视觉逻辑上handleConfirm里再判断一次因为有些用户会用键盘回车触发绕过视觉拦截。3.5 Vue 2 Vant 2 的适配写法老项目升级成本高很多时候只能原地改所以这版也得给。结构完全一样差别有四处。第一处是数据定义用data()返回filteredColumns用computed计算写法基本一致。第二处是事件绑定v-model:show换成v-model加.sync的写法或者直接监听input事件手动改。第三处是插槽Vant 2 不支持option插槽高亮功能只能放弃或者改用columns里传带 HTML 的对象不推荐有安全风险。第四处也是最关键的数据更新机制不同。// Vant 2 中过滤变化后的处理 watch: { filteredColumns(val) { this.canConfirm val.length 0 this.$nextTick(() { if (!this.$refs.picker || !val.length) return const idx val.findIndex( (item) this.getValue(item) this.selectedValue ) const target idx -1 ? idx : 0 // 先推送新数据再设置索引顺序不能反 this.$refs.picker.setColumnValues(0, val) this.$refs.picker.setColumnIndex(0, target) }) } }setColumnValues和setColumnIndex的调用顺序是硬性要求反了的话索引会基于旧数组计算还是会错位。这个坑我在两个项目里各踩过一次现在写代码前都会先在注释里把顺序标出来。另外 Vant 2 的getValues()返回的是数组input事件回调里拿到的picker实例提供的值需要自己取第一项。整体上 Vant 2 版本要多写十几行胶水代码但核心思路和 Vant 4 完全一致迁移的时候基本是搬运。4. 踩坑记录与问题排查速查表4.1 常见问题速查表下面这张表是我在三个项目里攒下来的遇到现象先查表能省掉一半的调试时间。现象根因排查手段解决方式搜索后滚轮位置乱跳过滤后数组变短旧索引越界在 change 回调里打印索引与数组长度候选集变化后nextTick里setIndexes重置清空关键词后选中项变了索引未随值回填停在过滤后的位置对比选中值与滚轮文字用 value 反查索引不用缓存的位置输入框点两次才聚焦触摸事件被滚轮容器吞掉在 input 上监听 click 与 touchstart 计数搜索区加touchmove.stop避免插槽嵌套输入时卡顿每次输入都重算拼音或重建大数组Performance 面板看 computed 耗时拼音预生成 computed 缓存提交上来的值里混进关键词把 keyword 当成了选中值打日志看 confirm 的载荷分离 keyword 与 selectedValue小屏机滚轮只剩三行弹层高度写死搜索区挤压在小屏真机或模拟器上看高度改百分比或calc(100% - 键盘高度)拼音搜不到拼音字段为空或大小写未统一打印某条数据的 pinyin 字段生成索引时统一小写并去标点选中项与文本不一致columns 对象字段名与 fieldNames 不匹配检查 columns-field-names统一字段名或在组件里做兼容映射4.2 软键盘弹起导致的遮挡与滚动冲突移动端最烦的就是键盘它弹起来会改变可视区域高度而底部弹层是基于视口定位的结果就是搜索框被顶到屏幕中间甚至上方滚轮被键盘完全盖住。我在 iOS 和安卓上各测了一遍行为还不一样iOS 上视口会整体上移安卓部分机型是压缩视口高度。我的处理方式是监听窗口的resize事件用弹层打开时的高度减去当前高度估算出键盘高度然后把弹层的高度动态改成calc(100% - 键盘高度)。这个方法不完美因为安卓某些机型不触发resize但配合visualViewportAPI 就能覆盖大部分情况。如果不想这么麻烦还有一个更省事的思路输入框聚焦时把滚轮区域的高度临时压缩让搜索框始终贴在被键盘顶起的位置上方用户输完再恢复。实测这个方案在两年前的安卓机上也能跑得比较稳。滚动冲突是另一个高频问题。搜索框和滚轮靠得很近用户在输入框上滑动想看看后面的内容结果下面的滚轮动了输入框失焦键盘收起页面跳动。解决就是在搜索区阻断触摸事件冒泡同时给输入框加touchstart.stop。代价是用户没法在搜索区上下滑动页面但在弹层场景里本来就不需要滑动页面所以没有副作用。4.3 上千条数据下的性能实测我把过滤逻辑放在两千三百条城市数据上测了一遍中端安卓机约三年前的中端芯片上的结果是单次过滤大约 1 到 3 毫秒完全感觉不到卡顿。这个数字比我预期的小原因是Array.prototype.filter配合String.includes在 V8 里的优化很好两千次字符串匹配的耗时很短。所以我的结论很明确五千条以内不需要做防抖也不需要 Web Worker直接过滤就行过度优化反而增加代码复杂度。真正需要警惕的是拼音索引的生成两千条数据用拼音库全量转换一次大概在 300 到 800 毫秒之间这个开销放在输入时是绝对不行的放在页面初始化时也会让首屏卡一下。我的做法是把这一步挪到“数据请求回来之后、渲染之前”用一个 loading 状态盖住或者干脆在服务端把拼音字段一起返回。后者是最优解只要后端配合前端就完全没有这个开销字段体积增加不到 20%非常划算。还有一个容易被忽略的性能点van-search组件的v-model更新频率很高每次输入都会触发filteredColumns重算。如果列表项渲染本身很重比如每项还带图标可以给 keyword 加一个 200 毫秒的防抖减少重渲染次数。这个防抖在五千条以上才有必要两千条加了反而让输入感觉粘手。4.4 多列联动省市区场景怎么搜单列好办多列联动的搜索是另一个量级的复杂度。用户输入“朝阳”你希望他直接选中“北京市 / 北京市 / 朝阳区”但 Picker 的联动结构是三级嵌套的搜索只能在某一列里发生这就要求我们把树形结构拍平成路径。我的做法是正常情况下保持三级联动的原样用户一旦输入关键词就把整棵树拍平成一列每项的文本是“省 / 市 / 区”的完整路径值是叶子节点的值清空关键词后再切回三级联动模式并根据选中的叶子值反推各级索引。拍平的逻辑大概是这样。function flattenCascade(tree, path [], result []) { tree.forEach((node) { const nextPath [...path, node] if (node.children node.children.length) { flattenCascade(node.children, nextPath, result) } else { result.push({ text: nextPath.map((n) n.text).join( / ), value: node.value, // 记录路径用于切回联动模式时定位 pathValues: nextPath.map((n) n.value) }) } }) return result }这里额外存了pathValues它的用途是切回联动模式时用这个路径数组去设置每一列的索引比用 value 逐级反查更直接、更不容易出错。切换模式的时候要记得把 Picker 整个重建用key强制刷新因为列数从 1 变 3 或者从 3 变 1组件内部的列状态不是简单重置能清干净的这是我在测试时发现的一个隐蔽 bug从搜索模式切回联动模式第三列的数据残留了上一次的内容用 key 重建是最省心的解法。5. 可以继续往下做的两件事5.1 把拼音索引提前到数据构建阶段前面反复提到预生成拼音字段这里给一个具体的实现用的是社区里常用的拼音转换库思路是同时产出全拼和首字母用空格分隔保存在同一个字段里。import { pinyin } from pinyin-pro const purify (str) str.replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() export function buildPinyinIndex(list, textField text) { return list.map((item) { const text typeof item string ? item : item[textField] const clean purify(text || ) // 兜底写法不依赖特定选项名取完整拼音后手动截首字母 const arr clean ? pinyin(clean, { toneType: none, type: array }) : [] const full arr.join() const initial arr.map((s) s[0] || ).join() const py ${full} ${initial}.toLowerCase() return typeof item string ? { text: item, value: item, pinyin: py } : { ...item, pinyin: py } }) }这里我特意用了“取完整拼音数组再手动截首字母”的写法而不是依赖某个特定的选项名因为不同版本的拼音库选项名有细微差异写成这样在任何版本上都能跑。如果你的数据里有大量多音字比如“重庆”的“重”库里一般有词库能处理正确但如果数据是冷门地名建议在服务端人工校对一遍或者允许运营在后台手动覆盖拼音字段。5.2 抽成可复用的组合式函数组件写完之后我发现过滤逻辑和索引同步逻辑可以完全脱离 UI 复用。比如另一个页面用的是自建列表而不是 Picker同样需要“关键词过滤 拼音匹配 值反查”这三件事。于是我把这部分抽成了一个组合式函数接收原始列表、关键词、字段配置返回过滤后的列表和一个反查函数。import { computed, unref } from vue export function useFilterColumns(columns, keyword, options {}) { const { textField text, valueField value, pinyinField pinyin } options const purify (s) String(s || ).replace(/[\s·•\-—_()[\]【】]/g, ).toLowerCase() const filtered computed(() { const list unref(columns) || [] const kw purify(unref(keyword)) if (!kw) return list return list.filter((item) { const text purify(typeof item string ? item : item[textField]) const py typeof item object item ? String(item[pinyinField] || ).toLowerCase() : return text.includes(kw) || py.includes(kw) }) }) const indexOfValue (value) { const list filtered.value return list.findIndex((item) (typeof item string ? item : item[valueField]) value ) } return { filtered, indexOfValue } }抽出来之后主组件少了三十多行另一个列表页面直接引入就能用。这种“先写通、再抽取”的顺序比一上来就设计通用方案要靠谱因为只有写通了你才知道哪些是真正共用的部分哪些只是看起来像共用。我在实际项目里的体会是给 Picker 加搜索这件事代码量其实不大真正花时间的是把索引、值、关键词这三者的关系理顺。理顺之后你会发现同样的思路可以用在很多地方级联选择、树形下拉、带搜索的穿梭框本质上都是“候选集变化后如何维持选中状态”这一个问题。踩过几次坑之后我养成了一个习惯凡是涉及列表过滤的地方先把“用值不用索引”这条写进注释里后面接手的人会少走很多弯路。还有一个实用的小技巧在开发阶段给组件加一个调试开关打开后把当前关键词、候选集长度、索引、选中值一起打印到控制台排查问题时比反复打断点快得多上线前把开关关掉就行。