Vue3+Vant4实现通讯录A-Z排序：拼音分组、IndexBar索引与长列表优化实战

1. 项目背景与整体设计思路

1.1 这个需求到底在解决什么

通讯录 A-Z 排序，是移动端项目里非常经典的功能形态。它的本质不是排序本身，而是解决“从大量联系人中快速找到目标联系人”的信息检索问题。当联系人数量超过几十个的时候，线性查找效率就很低了，用户需要的是“我知道对方姓什么，按姓氏拼音首字母直接跳过去”的快捷路径。

这类交互不止出现在通讯录 App 里，城市选择器、会员列表、企业组织架构里的员工名册、车险保单里的客户列表，只要是“按名称展示的长列表”，需求逻辑几乎一模一样。你学会了这一套，等于掌握了一个可以复用到多类业务的通用前端能力。

我实际做这个需求时，用的是Vue 3 + Vant 4 组合，Vant 自带的 IndexBar 索引栏和 IndexAnchor 索引锚点组件，天生就是为这种场景设计的。Vue 2 的写法也类似，无非是组件 API 细节略有差异，本文核心逻辑完全兼容。

1.2 为什么直接用 Vant 的 IndexBar 而不是手写

有个朋友问我：“这种 A-Z 索引效果，用 CSS sticky 定位加一个字母列表，自己写也就几百行，为什么要依赖组件？”我的回答是：自己写完全可以，但我建议你用组件，原因很实在——IndexBar 帮你把容错细节处理掉了，而这些细节恰恰是手写最容易翻车的地方。

举个例子：右侧字母栏点击的时候，需要判断点击落在哪个字母上，还要考虑滚动容器到底是谁（窗口还是内部 div），不同浏览器下触摸事件的坐标计算还有细微差异。Vant 的 IndexBar 封装好了这些，你传一个索引列表进去，它帮你算位置、帮你滚动，你在业务层面只需要关注数据怎么分组，开发效率能提升一大截。

另外一个现实原因：如果你需要在项目里长期维护，组件库的代码经过了大量线上业务验证，比你自己维护一套滚动坐标计算逻辑要稳得多。手写方案的代码量看似小，但后续如果产品要求“字母吸顶”“点击字母震动反馈”，你又要加一堆兼容性代码，到时候维护成本就上去了。

2. 数据层设计：核心不在排序，而在“分组索引”

2.1 原始数据长什么样

这个需求最关键的一步其实发生在数据层，而不是视图层。排序只是把数组按字母排一遍，但通讯录的交互要求的是：点击右侧字母，视图跳到对应分组。这意味着数据必须形成“字母 → 联系人列表”的分组结构。

我们来看看原始数据。假设后端返回的格式是：

[ { "name": "张三", "phone": "13800001111", "avatar": "" }, { "name": "Alice", "phone": "13900002222", "avatar": "" }, { "name": "陈晨", "phone": "13700003333", "avatar": "" }, { "name": "123VIP", "phone": "13600004444", "avatar": "" } ]

我最初接手这个项目时，团队直接把后端数组塞进页面，用computed做分组，结果发现两个坑：一是中文转拼音的准确性不可控，二是非中文字符（英文、数字、特殊符号）不知该归到哪一组。后来我重新整理了数据结构，前端在拿到数据后统一做“拼音预处理 + 分组”，再交给渲染层，整个逻辑就顺了。

这里的原则是：原始数据不变，派生数据用 computed 处理。因为通讯录数据通常会伴随搜索、增删联系人等操作，如果用生命周期函数一次性分组，后续数据更新时分组不会自动重新计算，而 computed 有响应式依赖追踪，数据一变，分组结果自动更新。

2.2 中文转拼音的处理方案对比

分组的第一步是把联系人姓名转成拼音首字母。这一步有几种方案：

我用的pinyin-pro，它支持pattern: 'first'直接取首字母，而且可以设置customDict定制多音字。比如“重庆”如果把“重”读成 chong，拼音库默认可能是 zhong，这时候通过自定义字典纠正即可。

安装很简单：

npm install pinyin-pro

注意pinyin-pro也支持通过 script 标签引入 CDN，如果你是在非工程化环境里用 Vue，可以走 CDN 方式：

<script src="https://cdn.jsdelivr.net/npm/pinyin-pro@3.26.0/dist/index.js"></script>

2.3 分组逻辑的完整代码

我们需要把数据变成如下结构：

[ { letter: 'A', list: [{ name: 'Alice', phone: '...' }] }, { letter: 'B', list: [] }, // ... { letter: 'Z', list: [{ name: '张三', phone: '...' }] } ]

注意一点：Vant 的 IndexBar 索引列表默认展示 A-Z 26 个字母，如果某个字母没有联系人，最好也保留空的分组，让索引栏完整展示 26 个字母，这样体验更统一——当然如果你想让“没有联系人的字母置灰”，Vant 4 支持通过index-list属性传入自定义列表，灵活处理。

下面是我的分组实现：

import { pinyin } from 'pinyin-pro'; // 从 65 到 90 生成 A-Z 数组 const LETTERS = Array.from({ length: 26 }, (_, i) => String.fromCharCode(65 + i)); function getFirstLetter(name) { if (!name) return '#'; const trimmed = name.trim(); if (!trimmed) return '#'; const code = trimmed.charCodeAt(0); // 数字开头或特殊符号 if (code < 65) return '#'; // 英文开头直接取大写 if ((code >= 65 && code <= 90) || (code >= 97 && code <= 122)) { return trimmed[0].toUpperCase(); } // 中文走拼音 const pinyinStr = pinyin(trimmed[0], { pattern: 'first', toneType: 'none' }); const letter = pinyinStr.charAt(0).toUpperCase(); if (LETTERS.includes(letter)) return letter; return '#'; } function groupByLetter(contactList) { const map = {}; LETTERS.forEach(l => { map[l] = []; }); map['#'] = []; contactList.forEach(item => { const letter = getFirstLetter(item.name); map[letter].push(item); }); // 过滤掉空分组，保持 A-Z 顺序 return LETTERS .filter(l => map[l].length > 0) .map(l => ({ letter: l, list: map[l] })) .concat(map['#'].length ? [{ letter: '#', list: map['#'] }] : []); }

这段代码的细节都在注释里了，我再强调几个关键点：

• map['#']专门收纳数字和特殊符号开头的联系人，通常排在最底部。
• 为什么要过滤空分组？因为如果 A 组没有联系人，渲染层会出现一个空的“A 锚点”，浪费屏幕空间，用户点起来也显得劣质。
• 拼音转换只取第一个字符，所以整体性能非常快。几千条联系人数据，分组消耗可以忽略不计。

在组件里使用：

const contactList = ref([]); const groupedList = computed(() => groupByLetter(contactList.value));

这里有个容易被忽略的小细节：computed的返回值是只读的，你在模板里渲染时不要尝试修改groupedList里的某个字段，Vue 会警告。如果需要操作某一项（比如编辑联系人），那就复制一份再改，或者改原始数组让 computed 重新计算。

2.4 排序稳定性与多音字处理

分组之后，同一字母下的联系人内部顺序也需要处理。中文环境下一般按“拼音全拼”排序，而不是按首字母排序。我见过一些项目只按首字母分组、组内不排序，结果“张”和“赵”都归到 Z 组，但顺序完全随机，用户找起来还是费劲。

组内排序的稳妥写法：

function sortGroupList(grouped) { return grouped.map(group => { const sorted = [...group.list].sort((a, b) => { const pa = pinyin(a.name, { toneType: 'none' }).replace(/\s/g, ''); const pb = pinyin(b.name, { toneType: 'none' }).replace(/\s/g, ''); return pa.localeCompare(pb); }); return { ...group, list: sorted }; }); }

注意pinyin返回的字符串可能包含空格（每个汉字间会有空格），需要去掉再比较。

多音字这块，pinyin-pro已经做得不错，但仍然不是 100% 完美。比如“单”姓，读 shàn 不读 dān；“解”姓读 xiè 不读 jiě。在业务允许的情况下，可以这样处理：

import { pinyin } from 'pinyin-pro'; pinyin('单', { pattern: 'first', customDict: { '单': 'shan' } });

customDict配置项可以传一个对象，覆盖默认拼音结果。如果你在做企业内部系统，建议把常见的“易错姓氏”整理成一个字典文件统一维护，这样分组准确率就能达到理想状态。

3. Vant 组件落地：IndexBar 与 IndexAnchor 正确用法

3.1 基础页面结构

Vant 4 中IndexBar和IndexAnchor的配合方式如下：

<template> <div class="contact-page"> <van-nav-bar title="通讯录" fixed placeholder /> <van-index-bar :index-list="indexList" :sticky-offset-top="46" highlight-color="#1989fa" @change="onIndexChange" > <div v-for="group in groupedList" :key="group.letter" class="contact-group"> <van-index-anchor :index="group.letter" /> <van-cell v-for="item in group.list" :key="item.id" :title="item.name" :label="item.phone" :icon="item.avatar || 'contact'" is-link @click="onContactClick(item)" /> </div> </van-index-bar> </div> </template>

注意几个要点：

• sticky-offset-top表示吸顶时距离顶部的偏移量。我的页面顶部有van-nav-bar，高度默认是 46px，所以这里传 46。如果你项目里有自定义的搜索栏、tab 栏，需要把对应高度都算进去，否则吸顶位置会被挡住。

• 官方文档里IndexAnchor是直接放在IndexBar下的，你不能在中间套一个多余的 div 把它们分开。有些新手会把van-index-anchor包在自定义组件里再渲染，这样会导致索引锚点的吸顶计算失效。如果必须封装子组件，要走插槽或透传，不要破坏 DOM 层级。

• index-list你可以自己控制，比如过滤掉没有联系人的字母后作为索引列表传入。但注意：如果index-list里没有某个字母，而页面中又渲染了该字母的IndexAnchor，那点击索引栏就跳不过去，页面和索引列表会“对不上”。所以我上面分组过滤时已经做了对应处理，两边保持一致。

3.2 关键属性与事件解读

我个人特别提醒@select这个事件。默认用户点击右侧字母，IndexBar 会自动滚动到对应锚点，但如果你的页面里还有搜索框或者其他更高的吸顶模块，仅仅依靠默认滚动可能定位不准。在@select里可以做二次确认：

function onIndexSelect(index) { currentLetter.value = index; // 这里可以埋点统计高频字母，评估联系人分布 trackLetterClick(index); }

@change事件我一般用来做右侧字母高亮联动，比如页面自己顶部有个“当前字母提示气泡”，滚动到哪个分组就显示哪个字母。不过本案例不需要，所以我只简单记录一下。

3.3 长列表性能优化

通讯录数据量大之后，一次性渲染所有 cell 会有性能压力。Vant 4 的 IndexBar 本身不负责虚拟滚动，它只是索引和锚点逻辑。所以当联系人超过 500 条时，建议叠加虚拟滚动。

Vant 4 提供了van-list做列表滚动加载，但它是“滑动到底部加载更多”的类型，跟通讯录这种“一次性长列表 + 定位跳转”的场景配合不够理想。更好的选择是配合@vueuse/core的useVirtualList，或者直接使用社区里的vue-virtual-scroller。

不过说实话，通讯录场景绝大多数情况下一个分组里的联系人是有限的。我处理过一个 3000 人的企业通讯录，按字母分组后最多的一个组也就 300 人，Vue 渲染 300 个 cell 完全没问题。真正需要虚拟滚动的是“不分组的长列表”，分组本身就是一种性能优化手段。

有一个细节值得注意：van-cell里渲染联系人头像时，如果头像来自网络，建议加上懒加载，否则首屏图片请求过多，滚动时会有明显卡顿。Vant 有van-image组件，自带lazy-load属性，配合@vant/lazyload插件使用。

4. 踩坑实录：这些问题我花了三个小时才搞明白

4.1 IndexAnchor 吸顶失效的三种情况

这是社区里问得最多的问题。我排查过的几个案例：

情况一：滚动容器不是窗口。

Vant 4 的 IndexBar 默认监听窗口滚动。如果你的页面布局里，通讯录是在一个overflow-y: auto的 div 里滚动的，那么 IndexBar 的吸顶计算就会完全错乱，锚点不会吸在预期位置。

解决办法也很直接：给滚动容器设置height: 100vh（或具体高度），同时让 IndexBar 直接放在这个滚动容器内。如果你非要用内层滚动，就要自己计算滚动容器的scrollTop，手动定位锚点，但这基本等于放弃 IndexBar 组件了。

情况二：sticky-offset-top 没算对。

我最初把van-nav-bar设成了fixed定位但没加placeholder，导致页面内容被导航栏遮住一部分。sticky-offset-top设置为 46 之后，吸顶锚点还是被盖住了，后来才发现导航栏实际占位了46px + 状态栏高度。在移动端有刘海屏的情况下，状态栏高度往往没有算进 Vant 的 NavBar 里，需要你额外获取：

import { getWindowInfo } from '@/utils/device'; // 假设这个方法获取设备信息 const statusBarHeight = getWindowInfo().statusBarHeight; const stickyOffset = 46 + statusBarHeight;

Vant 4 的 NavBar 其实有placeholder属性，占位高度它自己会处理，但我计算吸顶偏移量的时候还是要自己加上状态栏高度，否则吸顶后锚点会隐藏在系统状态栏后面。

情况三：父级元素设置了transform或filter属性。

CSS 的transform和filter会创建新的包含块，导致position: sticky相对于这个父容器生效而不是相对于视口。如果你的通讯录组件被一个弹层包裹，而弹层有动画（translate 或 opacity），里面的 sticky 就会失灵。这是 CSS 层的老问题，排查方式很简单：打开 DevTools，看锚点元素的position: sticky是否生效，不生效就检查祖先元素有没有 transform 属性。

4.2 中部索引引发的场景冲突

产品经理可能会提一个需求：“右边字母条太长了，能不能只显示 A-Z 的中间字母，甚至用像 iOS 那样滑动选字母？”

Vant 的 IndexBar 索引列表不支持中间省略号模式，你需要传入完整的index-list，否则无法定位。如果确实要做“缩略索引条”，方案就不是 IndexBar 了，而是自己右侧做一个小 Bar，监听 touchmove 事件，计算手指位置对应哪个字母，再手动调用滚动方法。

Vant 4 的 IndexBar 实例暴露了scrollTo(index: string)方法，你可以通过 ref 调用：

<van-index-bar ref="indexBarRef" :index-list="indexList"> </van-index-bar>

const indexBarRef = ref(null); function scrollToLetter(letter) { indexBarRef.value?.scrollTo(letter); }

这个方案我实际也用过一次——客户要求右侧索引栏更紧凑，我自己用绝对定位做了一个缩略条，touch 的时候根据自己这个条的位置比例映射到 26 个字母，然后调用scrollTo跳转。做起来不算复杂，但要注意触摸事件要绑定在 document 上而不是 bar 本身上，否则手指滑出 bar 区域就断触了。

4.3 热更新导致的“组件明明引入了却不生效”

Vite 开发模式下偶尔遇到IndexBar组件引入后页面空白或组件不渲染。排查下来多是自动导入插件（unplugin-vue-components）缓存问题。解决办法：删掉node_modules/.vite缓存目录，重新运行npm run dev；如果还不行，直接在组件里手动 import：

import { IndexBar, IndexAnchor } from 'vant'; import 'vant/lib/index.css'; // 如果你不是按需引入样式

这里顺便说下样式。Vant 4 默认支持按需引入，配合unplugin-vue-components和@vant/auto-import-resolver，样式会自动注入。但如果你手动 import 了组件而忘了引入样式，就会出现“结构和逻辑都对，但页面光秃秃”的问题。

4.4 搜索与分组的联动

通讯录基本都会带搜索功能，搜索时 IndexBar 怎么处理也是个常见问题。我的处理方式是：搜索时有结果就只展示平铺列表，不显示索引栏；搜索无结果显示空状态；清空搜索恢复分组模式。

<template> <van-search v-model="keyword" placeholder="搜索联系人" /> <van-index-bar v-if="!keyword" :index-list="indexList"> <!-- 分组渲染 --> </van-index-bar> <div v-else> <van-cell v-for="item in searchResult" :key="item.id" :title="item.name" :label="item.phone" /> <van-empty v-if="!searchResult.length" description="没有找到相关联系人" /> </div> </template>

搜索过滤时有个细节：中文搜索要用includes而不是indexOf === 0，因为用户可能输入姓名的任意部分，而不仅仅是开头。全拼搜索、首字母搜索这类更高级的需求，可以引入pinyin-pro的match方法做拼音匹配，效果很好：

import { match } from 'pinyin-pro'; const result = list.filter(item => match(item.name, keyword) || item.phone.includes(keyword));

match方法支持“拼音首字母匹配”“全拼匹配”两种模式，比如你输入zs，它能匹配到“张三”，输入zhangsan也能匹配到。这块不展开讲了，等哪天真需要做拼音搜索，再单独写一篇。

5. 实战中的优化思路与扩展玩法

5.1 右侧字母条的视觉优化

IndexBar 默认样式比较朴素，右侧数字母细长一条。很多项目会要求它更明显一些，或者不至于在页面右侧的留白里看起来突兀。Vant 4 的 IndexBar 暴露了#index插槽，可以自定义每个索引项的样式：

<van-index-bar :index-list="indexList"> <template #index="{ index }"> <div class="custom-index">{{ index }}</div> </template> <!-- 其他内容 --> </van-index-bar>

在custom-index里你可以做背景圆角、字号调整、当前项高亮等。配合@select事件记录当前索引，给当前字母加特殊样式，体验能上一个台阶。

5.2 双端通讯录：一套逻辑复用

热词里有“双端通讯录”，这里聊一下。很多项目的通讯录同时存在于 App 内嵌 H5 和 PC 管理端，Vant 组件本身偏移动端，PC 端浏览器打开时布局会拉宽，IndexBar 在宽屏下表现一般。我的做法是：在 PC 端用媒体查询把页面容器限制在 500px 以下居中显示，模拟移动端布局；或者干脆另做一套左侧字母 + 右侧列表的桌面版。业务逻辑层（分组、拼音、排序）完全复用，只是视图层不同。

这正好印证了数据层和视图层分离的价值：核心逻辑用 composable 提取出来，组件只管展示和交互。我项目中把分组逻辑提取到了useContactList.js：

// useContactList.js import { ref, computed } from 'vue'; import { pinyin } from 'pinyin-pro'; export function useContactList(fetchApi) { const list = ref([]); const keyword = ref(''); const loading = ref(false); const groupedList = computed(() => groupByLetter(filteredList.value)); const filteredList = computed(() => { if (!keyword.value) return list.value; return list.value.filter(item => match(item.name, keyword.value)); }); async function load() { loading.value = true; try { const data = await fetchApi(); list.value = data; } finally { loading.value = false; } } return { list, keyword, loading, groupedList, load }; }

这样移动端、桌面端、甚至是小程序（如果有 web-view），都能用同一套逻辑。

5.3 从“联系人”到“城市选择器”的迁移

同样的代码逻辑，把联系人换成城市，就能做城市选择器。去年我做项目时，城市数据来自后端接口，返回的是“省份 + 城市”的列表，我要做的是“按省份首字母分组”，逻辑一模一样。

更有意思的是会员体系：会员列表按昵称首字母分组，点击字母快速定位。这套逻辑的应用范围比我最初设想的广得多。所以如果你只是单纯做一个通讯录，可能还没完全发挥这个方案的价值。

5.4 性能与体验的进阶调优

最后说几个我实测过的小提升：

第一，图片懒加载。上面提过，Vant 自带Image组件支持懒加载。不要用<img>标签直接渲染头像，否则一次性加载几百个图片资源，弱网环境下体验很糟糕。

第二，滚动节流。IndexBar 的@change事件在快速滚动时会高频触发，如果你在回调里有复杂逻辑，建议节流：

import { throttle } from 'lodash-es'; const onIndexChange = throttle((index) => { currentLetter.value = index; }, 100);

第三，分组项吸顶样式。如果默认吸顶样式不够好看，通过 CSS 变量覆盖：

:root { --van-index-anchor-z-index: 10; --van-index-anchor-color: #1989fa; --van-index-anchor-background: #f7f8fa; }

不过说实话，移动端 3000 人通讯录，分组后每组最多几百人，van-cell 自带右侧箭头，渲染全量列表在手机上并没有明显的性能问题。真到了万级数据量，建议走后端搜索，而不是靠前端渲染了。

6. 写在最后的经验总结

其实整个通讯录 A-Z 排序功能拆到最后，核心就三件事：拼音转换、分组索引、视图联动。Vant 的 IndexBar 帮我们省去了最麻烦的滚动计算和吸顶逻辑，我们只需要处理好数据层，页面就能顺畅地跑起来。步骤很清楚：安装pinyin-pro、写分组函数、配 IndexBar 组件、处理边界情况（非字母字符、多音字、滚动容器），一套流程下来基本不会有大问题。

如果让我重新做一遍这个需求，有一点我一定会更早做好——先确认滚动容器是谁。这个决定直接影响 IndexBar 的吸顶配置，等你把页面写到一半再回头改，坑就多了。另外拼音库的选择也建议一步到位，别图一时省事用不维护的老库，多音字准确率差一点，用户搜“单”搜不到，产品体验就拉分了。

最后分享一个小技巧：调试 IndexBar 的跳转逻辑时，把浏览器 DevTools 切换到移动端模拟模式，然后开启“touch simulation”，这样手指滑动右侧索引条的交互才会真实。我第一次调试时一直用鼠标点击，怎么都觉得“点击字母没反应”，其实在真机上压根不是这个问题。算是一个小小的经验教训吧。