做移动端通讯录功能那会儿，我一开始是真没把它当回事。觉得无非就是一个列表，v-for循环渲染，顶多按拼音排个序。结果越往后做越不对劲：产品要求右侧有A-Z字母索引栏、点一下能跳转到对应分组、滚动列表时右侧索引要跟着高亮、首字母非中文的还要归到特殊分组里。一套组合拳下来，一个看似简单的通讯录页面，硬是写成了移动端交互最复杂的场景之一。最后我选了Vant的IndexBar组件作为核心方案，配合Vue 3的组合式API，把整个功能完整落地了。这篇文章就把完整的实现思路、代码、以及我实际踩过的坑全部记录下来。
1. 为什么最终选择Vant IndexBar：三套方案的对比与选型取舍
先说结论：Vant的IndexBar组件是移动端实现A-Z索引排序最省心、最贴近业务场景的方案。但这里的有趣之处在于，它并不是唯一选择，甚至如果你只看了官方文档，你可能根本不会意识到这个组件的强大之处。组件文档写得越简洁，说明它隐藏的细节越多。
1.1 方案一：纯CSS sticky吸顶自己实现，初期看起来很美好
很多同学第一反应是：我不就用CSS的position: sticky让分组头吸顶，再自己写一个右侧的字母列表吗？这个方案我也试过，确实可以做出来，但它有两个地方特别麻烦：第一是右侧索引栏的触摸交互，从touchstart到touchmove再到touchend，每个事件都要自己接，还要处理手指滑出字母栏边界时的事件接管问题，这在iOS和Android上的表现差异还挺大的；第二是滚动联动高亮，你要算当前滚动位置落在哪个字母分组区间，这个计算逻辑在没有统一滚动容器时特别容易出偏差，尤其是页面里还有吸顶头部、Tab栏的情况下。
说白了，用sticky方案做一个“看起来能用的demo”是很快的，但要做到生产可用，后面的交互细节能把你磨到怀疑人生。
1.2 方案二：引入better-scroll或自研联动逻辑，过度设计
better-scroll这类库确实有成熟的索引列表实现，但它的依赖相对重，和Vue的响应式状态对接也绕了一层。如果你只是为了实现一个联系人或城市列表的索引跳转，引入这么一套滚动方案，后面一旦遇到自定义滚动容器、搜索过滤态、路由缓存恢复等场景，排查问题的成本会明显上升。自研联动逻辑就更不划算了，几乎是把Vant已经做好的事情重复做一遍，还得自己擦屁股。
1.3 方案三：Vant IndexBar，为索引场景量身定做
Vant的IndexBar组件从设计之初就是面向这类移动端通讯录场景的：右侧索引展示、触摸滑动检测、点击索引跳转对应锚点、滚动高亮联动，这些核心能力都是现成的。配合Vant的IndexAnchor锚点组件，你不需要去计算每个分组的偏移量，组件内部通过锚点的位置关系自动完成了字母与分组的映射。这等于把我在方案一里说的那些麻烦事，全部内置解决了。
1.4 版本差异提醒：Vant 2与Vant 4的用法不能混
这里必须提醒一下，如果你用的是Vue 2 + Vant 2，IndexBar的index-list属性名为index-list（短横线命名），而Vue 3 + Vant 4里组件已改为van-index-bar，事件名为change。网上搜出来的很多老博客是Vant 2的写法，直接复制到Vant 4会报事件不触发或属性不生效的诡异问题。我下面的代码统一基于Vue 3 + Vant 4。
2. 通讯录数据处理：从松散数组到A-Z分组的边界处理
组件选型只是第一步。真正决定这个功能好不好用的，是你喂给组件的数据长什么样。如果把IndexBar比作一个需要按字母归档的档案柜，那你要做的就是把一堆杂乱的员工名片，按照姓氏拼音分门别类放进对应抽屉里。这个归档过程有非常多的边界情况。
2.1 推荐的数据结构与字段约定
本地原始数据往往长这样，比如一份可能含中英文混合的联系人数组：
const rawList = [ { name: '张三', phone: '13800138000', isTop: true }, { name: 'Alice', phone: '13800138001' }, { name: '陈晨', phone: '13800138002' }, // ... ]这里的关键问题是：name字段里可能是中文、可能是英文、可能带数字，也可能带特殊符号。我们要做的，不是简单排序，而是先按分组规则归入对应字母，再保证同一字母内部按拼音或字母序稳定排序。
我最终采用的思路是：不直接修改原始列表，而是生成一个分组对象，格式如下：
const grouped = { A: [{ name: 'Alice', ... }, { name: '安然', ... }], B: [{ name: '白宇', ... }], // ... '#': [{ name: '3M公司', ... }, { name: '@老张', ... }], }外层用固定的大写字母顺序遍历，而不是动态扫描对象键，这样能确保无论数据怎么变，A-Z和#的顺序都是稳定的。
2.2 核心分组逻辑：用reduce一次性搞定
有了原始数组，我写了一个纯函数来做分组，这个函数是整个功能里最核心的一个逻辑单元：
import { getPinYinInitial } from './pinyin' // 封装好的拼音首字母获取函数，后面会说 export function groupByInitial(list, getKey = (item) => item.name) { const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('') const result = {} letters.forEach((letter) => { result[letter] = [] }) result['#'] = [] list.forEach((item) => { const name = getKey(item) const initial = getPinYinInitial(name) const targetKey = initial ? initial.toUpperCase() : '#' if (result[targetKey]) { result[targetKey].push(item) } else { result['#'].push(item) } }) // 每个分组内部再按拼音全拼排序，保证中文姓名的相对顺序稳定 Object.keys(result).forEach((key) => { result[key].sort((a, b) => { const nameA = getPinYinFull(getKey(a)) const nameB = getPinYinFull(getKey(b)) return nameA.localeCompare(nameB) }) }) return result }这段代码里有一个容易被忽略的细节：分组内部排序用的是拼音全拼而不是首字母。如果只用首字母排序，同一个字母分组内的顺序是乱的，比如“李雷”和“刘芳”都在L组，但如果不比较全拼，它们在L组内的先后顺序就取决于原数组顺序，体验上会显得很随机。用localeCompare比较拼音全拼字符串，才能做到L组内“李”在前、“刘”在后的稳定排序。
2.3 边界情况一：大小写与空白字符
英文联系人如“alice”和“Alice”，在分组时如果不统一大小写，可能被分到不一样的字母组里。所以我在getPinYinInitial里做了trim()去首尾空格，再取首字符后统一toUpperCase()。还有一个冷门但真实存在的坑：有些联系人姓名首字符是全角空格或零宽字符，肉眼看不见却会占据首位，导致分组错乱。处理方式是先用正则去掉\uFEFF和\u200B这类隐藏字符。
2.4 边界情况二：多音字和生僻字，用什么库
中文拼音转换是这个功能最大的技术难点。如果你只取首字母，最朴素的方案是维护一份常用汉字到拼音首字母的映射表，但几千个常用汉字的映射表本身就需要工具生成。直接用现成库是更合理的做法。
pinyin-pro是我目前在项目中实际使用的库，支持获取拼音、首字母、姓氏模式。一个很实际的问题是：通讯录场景里，姓氏的读法比普通词语优先。比如“单”在姓名里通常读shàn而不是dān，如果按通用词语转换，姓“单”的人可能被错误分到D而不是S。pinyin-pro提供了pattern: 'surname'选项来优先使用姓氏读音：
import { pinyin } from 'pinyin-pro' export function getPinYinInitial(name) { const str = name.trim().replace(/[\uFEFF\u200B]/g, '') if (!str) return '' const firstChar = str[0] const code = firstChar.charCodeAt(0) // 非中文字符，直接返回字符本身，交由上层决定是否归入# if (code < 0x4e00 || code > 0x9fa5) { return /^[a-zA-Z]$/.test(firstChar) ? firstChar.toUpperCase() : '' } const result = pinyin(firstChar, { pattern: 'first', toneType: 'none', surname: true }) return result ? result[0].toUpperCase() : '' }需要注意的是，pinyin-pro转换单个汉字时性能没有问题，但如果列表有几万条，每次groupByInitial时都对新旧列表做一次全量拼音转换，仍然会造成明显的计算开销。这个问题的优化方案我在后面专门用一节来展开。
2.5 字母分组后，还要把“置顶联系人”独立出来
真实通讯录产品里，往往还有一个“置顶”或“常用联系人”分组悬浮在整个A-Z索引之上。这个分组我用一个isTop字段控制，渲染时把它放在IndexBar之外，作为普通列表项先渲染，然后再渲染IndexBar的分组列表。这个方案比塞进IndexBar里更灵活，也不会干扰右侧字母索引的计算。
3. 页面布局与IndexBar联动：从能渲染到真正能跳转
数据分组完成后，就进入了页面实现层面。这部分的重点有两个：整个页面的滚动体系怎么搭，以及IndexBar和外部滚动容器的联动怎么做。
3.1 页面结构调整：为什么外层容器高度必须是100%
IndexBar的滚动联动依赖一个关键前提：页面里得有一个确定高度的滚动容器。如果整个页面由body滚动，IndexBar内部计算锚点位置时会把文档滚动当成容器滚动处理，逻辑上是可行的，但一旦遇到页面里还有其他非滚动区域，定位就容易错位。
我采用的布局结构是：
<template> <div class="contact-page"> <van-search v-model="keyword" placeholder="搜索姓名/手机号" /> <div class="contact-scroll" ref="scrollRef"> <van-index-bar :index-list="indexList" highlight-color="#1989fa" @change="onIndexChange"> <!-- 置顶联系人区域，不参与索引 --> <div v-if="topList.length" class="contact-top-list"> <div class="contact-item" v-for="item in topList" :key="item.id">{{ item.name }}</div> </div> <div v-for="letter in letters" :key="letter" class="contact-group"> <van-index-anchor :index="letter" /> <van-cell v-for="item in groupedData[letter] || []" :key="item.id" :title="item.name" :label="item.phone" /> </div> </van-index-bar> </div> </div> </template>对应样式部分，这里有几个细节：
.contact-page { height: 100vh; display: flex; flex-direction: column; } .contact-scroll { flex: 1; overflow-y: auto; -webkit-overflow-scrolling: touch; }100vh在移动端浏览器地址栏缩放时会有一些历史问题，100dvh是更现代的选择，但对低版本Android WebView兼容性较弱。我一般用100svh和100dvh做渐进增强：
.contact-page { height: 100vh; height: 100svh; height: 100dvh; }3.2 IndexBar的核心属性与事件，逐个说清用途
Vant 4的IndexBar组件主要就这几个API需要理解透：
index-list：右侧要显示的索引数组，不传则根据van-index-anchor的index属性自动收集。我建议显式传入，因为遇到搜索态或数据为空时，控制索引列表展示更灵活。highlight-color：当前索引的高亮颜色，默认是主题色。change事件：索引变化时触发，回调参数是当前索引字母。这个事件在做自定义滚动联动时非常关键。scroll-to事件：点击或滑动索引时触发，参数是锚点的index值。注意这个和change的区别：change是索引变化后通知你，scroll-to是索引触发跳转时的通知，触发时机更早。
3.3 锚点定位的两种实现方式：默认动画与手动scrollTo
最简单的联调方式，是让IndexBar完全接管滚动，你只要把van-index-anchor放置在正确的位置，点击右侧字母时会自动滚动到对应锚点，这个过程不需要写任何额外代码。但它的滚动目标是window或最近的滚动容器，如果你需要精确控制滚动行为（比如跳转时偏移吸顶头部的高度），就要自己接管滚动逻辑。
我实现的手动方式是这样的，监听scroll-to事件后，找到对应的DOM元素，再用scrollIntoView执行滚动：
const scrollRef = ref(null) function handleScrollTo(index) { if (!scrollRef.value) return const groupEl = document.querySelector(`[data-index="${index}"]`) if (groupEl) { groupEl.scrollIntoView({ behavior: 'smooth', block: 'start' }) // 如果外层容器有padding或存在吸顶元素，需要手动补偿偏移 // 这里用offsetTop的差值计算更可控 } }这里实际写的时候我踩了一个挺隐蔽的坑：scrollIntoView默认会让滚动元素（最近的scrollable ancestor）滚动，如果外层滚动容器和外层页面都不是同一个，scrollIntoView的block: 'start'有时会把页面根元素也滚动了。更好的做法是自己算出偏移量，然后设置滚动容器的scrollTop。完整写法我会在第5章的踩坑分析里详细展开。
3.4 自定义搜索过滤时，索引列表与分组的高度变化
当用户输入关键词搜索后，列表会动态变短，部分字母分组可能为空。此时如果还保留所有A-Z索引，点击后会定位到一个空分组，体验很糟。我的做法是：搜索状态下重新计算indexList，只保留有数据的分组字母。
const indexList = computed(() => { if (!keyword.value) return allLetters return allLetters.filter((letter) => (groupedData.value[letter] || []).length > 0) })注意，这里#分组的处理要特殊一点。如果#分组没有数据，就把它也过滤掉；如果搜索后只剩一个分组，索引栏还占着右侧空间就很浪费，应该直接隐藏整个IndexBar。这个小细节在真实项目里挺加分的。
3.5 首字母高亮跟随：滚动时自动更新右侧索引
IndexBar自带的滚动高亮逻辑，依赖锚点在视口内的位置计算。在标准的页面滚动场景下，你只要把van-index-anchor放在正确的位置，右侧索引会自动跟随高亮。但如果你用了自定义滚动容器，需要确认滚动容器是IndexBar的父容器。Vant 4的IndexBar在挂载时会收集每个IndexAnchor的offsetTop，并监听滚动容器的scroll事件来比对当前高亮字母。
如果你的滚动容器不在IndexBar的父级链路上，高亮就会失效。遇到这种情况，可以通过给IndexBar加scroll-to事件配合自己监听scroll事件来手动设置高亮字母。不过据我所用过的版本，Vant 4 的 IndexBar 已经能自动找到最近的滚动容器，通常不必自己实现高亮。
4. 结合Search与场景细节，补全通讯录页面的完整体验
一个能看、能跳的索引列表只是骨架。真正让页面“活”起来，还需要搜索过滤、空状态、键盘弹出、吸顶体验等细节的配合。
4.1 接入van-search，用computed实时生成过滤结果
搜索逻辑比较简单，但也最容易写出性能问题。我在项目里用的是keyword + computed的方案：
const keyword = ref('') const rawList = ref([]) // 从接口取到的原始列表 const filteredList = computed(() => { const kw = keyword.value.trim().toLowerCase() if (!kw) return rawList.value return rawList.value.filter((item) => { return ( item.name.toLowerCase().includes(kw) || item.phone.toLowerCase().includes(kw) || getPinYinFull(item.name).toLowerCase().includes(kw) ) }) }) const groupedData = computed(() => groupByInitial(filteredList.value))这里有个性能细节：getPinYinFull(item.name)在过滤时对每个联系人都会重新计算一次。如果列表很大，建议给原始列表预计算一个拼音字段缓存起来，搜索时直接查缓存属性，而不是现算。我第一次实现没注意，列表3000人时输入每个字符页面要卡几百毫秒，后来把拼音预计算一次，问题就消失了。
4.2 吸顶分组头的实现：CSS sticky也可以，但要注意IndexBar嵌套
Vant的IndexAnchor本身就是吸顶的。但如果你需要“分组头吸顶同时右侧索引栏固定在视口边缘”，Anchor已经处理了大部分情况。唯一要注意的是：IndexAnchor的吸顶依赖父容器的overflow设置。如果外层滚动容器是overflow-y: auto，并且容器内部还有position: relative或transform等CSS属性，会影响吸顶效果，甚至导致吸顶失效。
我的实践建议是：如果出现吸顶失效，先检查外层容器是否有transform或filter这类创建新层叠上下文的CSS属性。移动端有一些全局样式会顺手加transform: translateZ(0)做GPU加速，这个会直接打破position: sticky的定位。
4.3 搜索态下索引栏的隐藏与恢复
搜索时索引栏不仅没有意义，还容易干扰用户视线。我处理的方式很简单：搜索关键词非空时，用v-if将van-index-bar替换成普通列表。这需要把渲染逻辑拆成两部分，一部分是IndexBar索引列表，另一部分是纯列表。关键词变化时自动切换。这个设计能避免我前面说的“索引还在但分组空掉”的问题。
4.4 空状态和加载状态一个都不能少
通讯录场景还有一个常见的状态：列表为空。网络不好的时候接口返回空数组、或者搜索不到联系人，页面如果只显示一片空白，用户很容易误以为加载失败。我用van-empty组件，分别对“无搜索关键词时列表为空”和“搜索无结果”两种情况给出不同文案。在接口加载时，用van-loading包一层全屏loading。
4.5 性能考虑：计算属性与监听器的取舍
整个页面的数据链路是：rawList -> filteredList -> groupedData -> 渲染。多级computed嵌套在Vue 3里是完全合理的，它可以精确地按需更新。不建议用watch手动监听然后修改一个响应式对象，那样反而容易触发多余更新，并且容易写出命令式逻辑。
我在大型列表页面里的经验是：computed默认就带缓存，只有依赖变化才重新计算，性能问题不在于computed本身，而在于计算内部的算法复杂度。所以真正的优化点是分组算法和拼音转换的缓存策略，而不是把computed改成watch。
5. 实际项目复盘：5个高频踩坑点，每一个都真实影响线上功能
这部分是我最想写的。因为在项目上线前，我一度以为IndexBar已经把一切处理好了，直到测试反馈各种诡异问题，我才意识到很多细节光看文档根本看不出来。
5.1 坑一：IndexBar不生效，整页白屏或索引点了没反应
大概率是布局问题。van-index-bar内部计算锚点偏移时依赖外层滚动容器的高度。如果外层contact-scroll没有设置overflow-y: auto，或者它本身高度没有被flex布局约束住（即内容高度撑开了容器，导致它变成无限高），IndexBar就会以为整个页面都在滚动，很多定位和跳转逻辑都会失效。
排查方法很直接：在浏览器DevTools里看contact-scroll的高度，如果它等于页面总内容高度而不是视口剩余高度，就说明flex布局没有正确生效。修复方案是第3章的flex: 1; min-height: 0，注意min-height: 0这个属性经常被漏掉，没有它flex子项默认的最小高度是auto，内容一多还是会撑开容器。
5.2 坑二：分组列表更新了，但界面不刷新
通讯录页面经常需要在新增加联系人后返回列表时刷新。如果用push往rawList里塞数据，Vue 3的响应式系统可以正常触发视图更新，但前提是你直接修改的是ref的value数组本身。如果走的是接口返回新数组，直接rawList.value = newList也没问题。
真正的问题是：分组对象groupedData如果被不小心做成了ref({})并在更新时做Object.assign这种操作，它的深层响应式追踪在某些版本下会失效。稳妥做法是每次重新分组后整体赋值：
rawList.value = await fetchContactList()不要对foreach一个空对象然后逐个往里面塞分组结果，除非你很确定每一步都走响应式代理。在长列表性能优化时确实有人用非响应式对象绕过代理，但如果这时代码里其他地方引用了它，就会出现“数据变了视图不动”的灵异事件。
5.3 坑三：Android低端机滑动字母索引卡顿
IndexBar的触摸滑动本身是流畅的，但每个touchmove事件如果都触发一次scrollTo或一次锚点定位，在低端Android浏览器上会出现明显的掉帧。Vant在IndexBar内部已经做了节流，但业务侧接change事件后如果又去操作DOM或大量重计算，还是会造成性能问题。
我的做法是在change事件回调里做一次标记更新，用requestAnimationFrame把实际滚动任务合并到下一帧执行：
let ticking = false function onIndexChange(index) { if (ticking) return ticking = true requestAnimationFrame(() => { scrollToLetter(index) ticking = false }) }这个改造很小，但对滑动性能的提升非常明显。
5.4 坑四：锚点定位总是差一个分组或固定偏移一个像素
当你手动接管滚动时，最容易出现“点到C跳到了B”或“跳转后分组头压住了吸顶元素”。原因通常是两点：一是DOM结构里van-index-anchor并不是分组内的第一个节点，或者分组前还有一个置顶区域，导致锚点offsetTop计算偏移；二是页面导航栏或搜索框占据了一定高度，而滚动容器的sctollTop计算没有把这段高度减去。
最可靠的修复方式是不要用scrollIntoView，而是手动计算目标元素相对滚动容器的偏移：
function scrollToLetter(index) { const container = scrollRef.value const target = container.querySelector(`[data-index="${index}"]`) if (!target) return const top = target.offsetTop - container.offsetTop - 46 // 46为主吸顶元素高度，按实际调整 container.scrollTo({ top, behavior: 'smooth' }) }这里46的数值可以从van-search的实际高度读取，或在容器内通过getBoundingClientRect动态计算，避免魔法数字。这种写法在遇到页面结构调整时不会轻易被破坏。
5.5 坑五：搜索过滤后点击索引，字母对应位置错乱
搜索态下分组数量变化了，如果还用旧的><van-index-bar :key="reloadFlag" :index-list="indexList" @change="onIndexChange">
把reloadFlag在数据更新后自增，这个方案在实际项目里最省事，也最不容易引入时序bug。
6. 列表破5000后的进阶优化：索引栏之外的另一层战场
通讯录这个场景，数据量很容易飙升到几千甚至上万。索引分组能解决“跳转定位”的问题，但解决不了“一次性渲染几千个组件导致卡死”的问题。这块如果不提前规划，MVP上线时用户数量少可能还好，一旦用户增多，问题就会集中爆发。
6.1 渲染优化一：分组懒渲染，进入视口才真正挂载
IndexBar配合van-list组件可以做每个分组的滚动懒加载，但这样交互比较复杂。如果不想引入虚拟滚动库，一个比较实用的优化是：只渲染可视区域和相邻分组。具体思路是根据当前滚动的字母索引，动态计算出可见的几个字母，其余分组用占位节点替代。这种方式在Vue里实现起来要小心滚动高度塌陷，建议只对“分组非常多”的页面做。
6.2 渲染优化二：分组内部用虚拟滚动
对于单个分组就上千人的极极端情况，更合适的是接入成熟的虚拟滚动方案，比如vue-virtual-scroller，把每个分组内部的联系人列表变成虚拟列表。但需要注意：IndexBar的锚点定位依赖各分组的真实高度，虚拟滚动会让某些分组的实际渲染高度为0，从而破坏锚点偏移的计算。所以这个方案必须配合自定义锚点定位逻辑来用，复杂度明显更高，一般项目用不到这个程度。
6.3 拼音与索引缓存：一次转换，多次复用
这是我在实践中认为性价比最高的优化。做法是在数据进入前端时，就给每条联系人预计算并缓存拼音全拼、拼音首字母，后续无论分组、排序还是搜索，都直接从缓存字段取值：
const listWithPinyin = rawList.map((item) => ({ ...item, namePinyin: getPinYinFull(item.name), initial: getPinYinInitial(item.name), }))这样分组的复杂度从O(N * 拼音转换耗时)降为O(N)的数组遍历，搜索时也不用反复做拼音转换。移动端联系人列表数量在几千这个量级时，这个优化带来的性能提升是体感级别的。
6.4 本地数据与接口数据混合时的稳定策略
有些通讯录App会把本机通讯录和后台账户通讯录合并。本机通讯录读取到的姓名字段可能是空字符串，也可能是只有电话没有姓名。针对这种情况，分组前必须对空姓名字段兜底，比如统一用“#”分组，或者用号码后四位作为临时显示名。这个兜底逻辑要写在数据预处理阶段，而不是渲染阶段，否则过滤逻辑会反复处理脏数据。
写在最后
讲真，通讯录A-Z排序这个功能，表面上看起来是Vue + Vant几分钟搞定的小Case，但真正推到生产环境，要考虑数据边界、交互细节、性能瓶颈和外层容器布局的隐性约束，每一步都有不少实际问题需要处理。我在这个项目里最大的收获是：好的组件库确实省掉了大量底层的滚动计算，但页面的布局结构、数据预处理和异常状态管理才是决定功能是否“能上线”的关键。如果你也在做类似的移动端索引列表，建议先确定好滚动容器和布局骨架，再来接IndexBar，这样能少走不少弯路。后面我打算继续把搜索、筛选、大数据量下的加载策略做成一个更完整的模板，也会同步更新出来。
