uni-indexed-list仅负责渲染和点击事件，滚动定位、拖拽、高亮等需用scroll-view手动实现；须设固定高度、规范id、启用scroll-with-animation；首字母提取推荐pinyin-pro；分组需先排序；touchmove需防抖并阻止默认行为；真机测试至关重要。
uni-indexed-list 组件能直接用，但得先搞清它和原生 scroll-view 的分工
uni-app 官方 uni-indexed-list 确实封装了字母索引逻辑，但它不是“开箱即用”的万能组件——它只负责渲染结构和触发 @click 事件，**不处理滚动定位、触摸拖拽、首字母高亮、悬浮提示等交互细节**。这些都得你用 scroll-view + scroll-into-view + touchmove 手动补全。
常见错误现象：直接套用文档示例，点击右侧字母没反应，或滚动卡顿、跳转不准；原因往往是没给 scroll-view 设固定高度，或没按规范为每个分组设置唯一 id（比如 id="id_A"），又或者在 H5/小程序里漏了 scroll-with-animation 开关。
-
scroll-view必须显式设置height（如height: calc(100vh - 120px)），否则scroll-into-view失效 - 每个字母分组的
id要和右侧索引栏点击传入的值严格一致（大小写、空格、特殊字符都不能差） - H5 端需加
:scroll-with-animation="true"才有平滑滚动；App 和小程序默认支持，但 iOS App 有时需手动调用this.$refs.scrollView?.scrollTo({ scrollTop: xxx })做兜底
pinyin-pro 是目前最稳的中文首字母提取方案，别自己写正则
想让“张三”归到 “Z” 组、“上海”归到 “S” 组，就得把汉字转拼音取首字母。手写正则匹配多音字、生僻字、带符号姓名（如“欧阳修”“阿Q”）基本是自找麻烦。
pinyin-pro 是当前 uni-app 全端兼容性最好的选择：体积小、无依赖、支持多音字标注、API 直观。npm 安装后，一行就能拿到大写首字母：
import { pinyin } from 'pinyin-pro'
const initial = pinyin('张三', { style: 'first-letter' }).toUpperCase() // 'Z'
- 别用
pinyin（旧版）或chinese-to-pinyin，它们在 H5 或小程序里容易报global is not defined - 对空字符串、null、数字开头的姓名（如“360员工”）要做兜底处理，否则
pinyin()返回空或报错 - 分组前务必先用
Array.sort()按拼音排序，否则 A-Z 分组虽有，但内部顺序乱（微信通讯录就是先排序再分组）
右侧字母栏的 touchmove 逻辑必须防抖，否则滑动时疯狂触发跳转
用户手指在右侧字母栏上快速滑动时，@touchmove 会高频触发，如果每次都在里面直接设置 scroll-into-view，会导致滚动视图反复中断、卡顿甚至跳错位置。
公众号运营：文章发布至草稿、样式封面、评论与用户管理、数据统计等。用户要求将 Markdown 发送到公众号草稿、查看阅读量统计或类似后台操作时，使用本技能。
正确做法是：只记录当前滑动到的字母，用防抖控制最终跳转时机；同时配合 onTouchEnd 清除状态，避免残留。
- 用
setTimeout+clearTimeout实现简单防抖（300ms 足够），不要引入额外 debounce 库增加包体积 - 滑动过程中建议显示一个半透明浮层提示当前字母（如“Z”），提升体验；这个浮层的
v-show状态要和 touch 状态联动 - 注意移动端
touchmove默认行为是页面滚动，要在事件回调里加e.preventDefault()阻止默认滚动，否则字母栏会跟着页面一起动
scroll-into-view 在不同平台表现不一，真机测试比模拟器重要十倍
开发时在 HBuilderX 模拟器里看着没问题，一到真机就跳不准？这是常态。根本原因是各平台对 scroll-into-view 的实现机制不同：微信小程序用的是节点坐标计算，H5 是 DOM offsetTop，App（尤其是 iOS）可能还受 native 层渲染管线影响。
实战中必须做的几件事：
- 所有分组容器（如
<view class="letter-group" id="id_A">）必须有明确的 top 边距或 padding，不能靠内容撑开高度，否则 iOS 上scroll-into-view定位偏移 - 首次加载完数据后，延迟 100ms 再设置
scroll-into-view，确保 DOM 已完成渲染（尤其在使用v-for动态生成列表时） - 对关键机型（iOS 17+、Android 14、微信 8.0.50）做真机回归，重点看首字母是否跳到可视区顶部、是否有白屏闪动
最复杂的点不在代码量，而在于滚动定位的“像素级手感”——它没法一次写对，得靠真机反复调 offsetTop 补偿值、改防抖时间、试 scroll-with-animation 开关状态。这点没人能替你测完。
