n-index-list 索引列表
分组浏览长列表，支持索引点击、触摸与桌面拖动定位、分组标题吸顶及气泡提示。普通列表只配置数据；自定义内容提供 item 或 section 插槽。容器需有确定高度。
右侧索引条固定在实际滚动可视容器的右侧并整体居中。列表滚动只更新当前索引高亮，不改变索引条和各键的位置、尺寸；开启 headerFixed/footerFixed 时，首尾插槽独立占位，中间区域才是滚动视口，索引条不会覆盖首尾；未开启时对应插槽随列表滚动。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
标题与标准行文字的单行省略由 CSS（
white-space: nowrap+text-overflow: ellipsis）全端统一承担，不绑定 text 的行数属性——该属性官方已废弃，App 端编译告警，Web / 微信端框架也不消费（绑定无效，真实截断始终走上述样式）。
如何调用
<view style="height:500px">
<n-index-list v-model="current" :list="groups" />
</view>import { ref } from "vue";
import type { NIndexListGroup } from "@/uni_modules/new-ui/components/n-index-list/props";
const current = ref("");
const groups = ref<NIndexListGroup[]>([
{ index: "A", items: [{ text: "安禾", subText: "成都" }] },
{ index: "B", title: "常用联系人", items: [{ text: "白澈", subText: "苏州" }] }
]);标准项读取 text（主文字）、subText（副文字）、src（图片地址）、checked（勾选态）、disabled（禁用）。业务字段保留并在 click 参数的 item 中原样提供。
默认行最小高度为 44px，上下内边距各 8px，与中号单元格一致；开启复选框不增加行高，图片按内容撑高，默认主副文字单行省略；自定义多行布局使用 item 插槽。需要更紧凑时使用 item-style="min-height:40px;padding-top:4px;padding-bottom:4px"，主、副文字分别用 itemTextStyle、itemSubTextStyle 定制。
开启选择时用 <n-index-list v-model="current" v-model:list="groups" selectable show-image />。组件生成新列表回写勾选态，不修改传入对象；业务只在 click 中处理提交、限制选择等规则。禁用项不切换、不派发 click。自定义 item 插槽也使用相同点击与选择通道，插槽内无须重写勾选算法。
<n-index-list :list="groups" custom-style="height:380px">
<template #item="{ item, last }">
<n-cell :title="item.text" :value="item.subText" :border="!last" />
</template>
</n-index-list>anchor 插槽定制分组标题内容，参数 group、groupIndex；标题内容随真实段头吸顶，无须自行测量或复制悬浮层。
item 插槽的按压与禁用状态由组件外层项统一承接，插槽负责内容。section 插槽覆盖整组内容，适合网格等布局；此时不产生 item 插槽及逐项 click，业务交互由 section 插槽内的节点承担。插槽须静态提供；切换插槽组合时使用完整组件变体。
固定搜索栏或操作区可配置 <n-index-list :list="groups" header-fixed footer-fixed>，首尾高度由插槽内容自然撑开，无须业务测量。两个属性可独立开启，示例页默认开启两者。
API
属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 当前索引键；支持 v-model，外部赋值自动定位，留空从顶部开始 | string | "" |
| list | 分组数据；index 空白的组不参与索引定位，index 重复时仅首个分组参与定位并触发 error | NIndexListGroup[] | [] |
| headerFixed | 将 header 插槽固定在列表上方并独立占位，索引条不覆盖该区域 | boolean | false |
| footerFixed | 将 footer 插槽固定在列表下方并独立占位，索引条不覆盖该区域 | boolean | false |
| selectable | 开启标准项的复选框；点击由组件生成新列表并通过 update:list 回写，配合 v-model:list 使用 | boolean | false |
| showImage | 标准项显示 src 图片，地址为空时保留图片位置 | boolean | false |
| subRight | 标准项 subText 居右；关闭后紧跟主文字 | boolean | true |
| selectedColor | 标准项复选框选中颜色；空 = 主题品牌色 | string | "" |
| borderColor | 标准项复选框未选中描边色；空 = 主题边框色 | string | "" |
| sticky | 分组标题吸顶：滚动时当前段标题悬浮在容器顶部，下一段标题将其推走 | boolean | true |
| navbarHeight | 为自定义导航栏预留的顶部高度（px）；滚动视口、吸顶标题及索引定位统一位于该区域下方 | number | 0 |
| showIndicator | 触摸索引条时显示气泡提示当前索引 | boolean | true |
| zIndex | 索引条与悬浮头的层级（z-index），须为有限整数；非法时停止吸顶 | number | 10 |
| titleColor | 段头文字色；空 = 主题次要文字色 | string | "" |
| titleBackground | 段头背景色；空 = 主题弱填充（随深浅主题） | string | "" |
| titleHeight | 段头高度（px），-1 使用主题高度，其他值须为有限正数；非法时停止吸顶并使用主题高度 | number | -1 |
| titleStyle | 段头容器行内样式，最后应用；字号走 titleTextStyle | string | "" |
| titleTextStyle | 段头文字行内样式，同时作用于吸顶标题；如 "font-size:14px" | string | "" |
| keyColor | 索引条键位文字色；空 = 主题次要文字色 | string | "" |
| activeColor | 索引条激活键位文字色；空 = 白色 | string | "" |
| activeBackground | 索引条激活键位底色（圆形）；空 = 主题品牌色 | string | "" |
| keyStyle | 索引条键位行内样式，最后应用 | string | "" |
| keyTextStyle | 索引键文字行内样式，最后应用 | string | "" |
| indicatorBackground | 气泡背景色；空 = 主题品牌色 | string | "" |
| indicatorColor | 气泡文字色；空 = 白色 | string | "" |
| indicatorStyle | 气泡行内样式，最后应用 | string | "" |
| indicatorTextStyle | 气泡文字行内样式，最后应用 | string | "" |
| itemStyle | 标准列表行的容器样式，可调整内边距和最小高度；item 插槽不受影响 | string | "" |
| itemTextStyle | 标准列表行主文字样式；item 插槽不受影响 | string | "" |
| itemSubTextStyle | 标准列表行副文字样式，同时作用于居右和跟随布局；item 插槽不受影响 | string | "" |
| customClass | 根节点额外 class，类须定义在组件样式表内 | string | "" |
| customStyle | 根节点行内样式，最后应用；组件默认撑满父容器高度，父容器需有确定高度，可在此调整 | string | "" |
事件
| 事件名 | 说明 |
|---|---|
| update:modelValue | 当前索引键变化时回写，配合 v-model 使用，参数 String |
| update:list | selectable 开启时点击项回写新列表，不修改传入数据，配合 v-model:list 使用 |
| change | 当前索引键变化时触发，参数 String；空字符串表示位于首组之前或列表为空 |
| select | 点击索引或连续拖动进入新键时触发，参数 String；重复点击同一键仍触发 |
| click | 点击列表项时触发，参数 {item, group, groupIndex, itemIndex, checked}，禁用项不触发 |
| init | 首次完成布局测量后触发，后续布局变化自动重测 |
| scrolltolower | 滚动到底部时触发，适合衔接分页加载 |
| error | 数据、属性或可见节点测量非法时触发，参数 {prop, message}；恢复后自动继续 |
插槽
| 插槽名 | 说明 |
|---|---|
| header | 前置内容；headerFixed 开启时固定并独立占位，否则随内容滚动 |
| anchor | 分组标题内容；参数 group、groupIndex；默认显示 title 或 index |
| item | 单项渲染；参数 item、group、groupIndex、itemIndex、last；不提供则使用标准行 |
| section | 整组渲染；参数 group、groupIndex；提供后 item 与标准行不渲染 |
| footer | 末尾内容；footerFixed 开启时固定并独立占位，否则随内容滚动 |
方法
| 方法名 | 说明 |
|---|---|
| refresh() | 主动重测布局；数据、插槽及尺寸变化自动检测，正常使用无须调用 |
| scrollTo(key: string) | 按索引键定位，超出滚动范围时停在边界；布局未就绪时保存最后一次请求；空字符串回到顶部，未知或空白键触发 error |
数据与状态
- index 为非空索引键；title 可覆盖段头文案；items 为数据项数组。空白组保留内容但没有索引键；重复键只定位首组，并派发 error。
- 分组可设置 titleStyle、titleTextStyle，分别覆盖全局的标题容器和文字样式；例如
{ index: "A", titleStyle: "background-color:#e8f5ef", titleTextStyle: "font-size:16px;color:#14532d", items: [] }。同组的普通标题与吸顶标题保持一致。 - modelValue 是当前索引键。外部赋值自动定位；首组前的 header 区域与空列表为 ""。手动滚动触底可高亮末键；主动定位被滚动范围夹取时保留请求的索引。吸顶标题始终按实际分组计算。清空 modelValue 会取消尚未完成的定位请求。
- select 表示主动点击或拖动进入新键，即使当前键没有变化，重复点击也会派发；change 只在当前索引键变化时派发。
- items.checked 通过 v-model:list 受控回写；单向绑定 list 时可在 update:list 中审核后提交。
- titleHeight 非法时派发 error，停止吸顶并使用主题高度保留内容；修正后自动恢复。容器隐藏时暂停定位就绪状态，重新显示后自动测量。
- navbarHeight 默认0。设置后在组件顶部为自定义导航栏留出空间，剩余区域为实际滚动视口；段头、索引条与定位均以该视口为准。非法值派发 error 并按0处理。
- 普通调用无须传 titleHeight，默认跟随主题（32px）；-1 仅表示使用主题高度，不会输出负高度。指定正数才覆盖主题高度。
样式令牌
| CSS 变量 | 默认值 | 作用 |
|---|---|---|
| --n-index-list-title-h | 32px | 段头高度；titleHeight 非 -1 的合法值优先 |
| --n-index-list-key-w | 16px | 索引键宽度及默认内圆直径 |
| --n-index-list-key-h | 20px | 索引行高度；默认内圆16px，行间留出4px；容器不足时行高压缩，内圆始终等宽高 |
| --n-index-list-bubble | 48px | 气泡边长 |
| --n-index-list-active-bg | rgba(0,0,0,0.2) | 列表项按压背景，独立于分组标题背景 |
右侧索引采用独立命中行和圆形高亮，默认行高20px、内圆16px。26组索引的自然总高度为520px；可用区域不足时压缩行高和内圆，始终限制在滚动可视容器内，内圆保持等宽高。
根节点 padding 后，标题、索引条与气泡仍对齐实际滚动视口；默认行左右内边距均为16px；索引条加宽时，右侧仅增加必要的避让宽度。
文字颜色有对应颜色属性；文字字号/字重用 titleTextStyle、keyTextStyle、indicatorTextStyle。标题与标准行文字默认单行省略，避免长文字侵入其他行；需要富内容时使用 anchor/item 插槽。titleStyle、keyStyle、indicatorStyle 分别作用于容器，几何计算以最终渲染结果为准。
默认行复用 --n-cell-height-md、--n-cell-padding-y 与 --n-cell-border-color，保持列表行的尺寸和分隔线一致；itemStyle 可局部覆盖容器尺寸。列表项按压背景通过 --n-index-list-active-bg 定制，默认使用半透明黑色，与分组标题底色独立；分组标题没有按压态。复选框选中后的填充与描边始终同为 selectedColor。
实现说明
| 能力 | 常见做法 | 本组件做法与取舍 |
|---|---|---|
| 长列表渲染 | 原生列表复用或可见窗口渲染 | App使用 list-view/list-item；Web/微信使用可见窗口与上下占位。标准项逐行处理，整组插槽按组渲染 |
| 标题内容 | 分组标题插槽 | anchor 插槽作用于真实段头，吸顶沿用同一份内容，不复制浮层标题 |
| 导航栏高度 | 指定吸顶偏移 | navbarHeight 为滚动视口顶部预留高度，标题吸顶、索引条与定位统一使用该视口坐标 |
| 分组吸顶 | 原生列表分组头或分组内 sticky | App开启 sticky 时使用 sticky-section/sticky-header，关闭后标题作为普通列表项滚动；Web/微信在分组内使用 CSS sticky。真实段头承载 anchor，不复制浮动标题 |
| 索引定位 | 按节点ID跳转或累计高度 | 使用组件自有分组ID和 scroll-into-view；App普通组定位标题列表项，Web/微信保留完整分组容器与屏外占位，尺寸和数据变化后统一校准窗口及分组位置 |
| 布局与状态 | 全组测量或可见项检测 | 当前组由仍在渲染的段头和列表项确定，不要求屏外节点存在；容器、索引条和气泡使用统一尺寸监听，非小程序观察分组尺寸变化；Web/微信共享容器及内容尺寸检测，仅尺寸变化、滚动或数据更新时重算窗口；数据与配置变化自动更新 |
| 索引范围 | 相对容器固定居中 | 索引条属于实际滚动视口，固定首尾区在视口之外独立占位；CSS负责居中，最大高度使用视口实测高度的px值，滚动不改变键位 |
| 索引交互 | 固定键高换算或逐键实测 | 按实际键位中心命中，兼容高度、margin和压缩；气泡按实测尺寸定位；触摸与鼠标使用单一处理链，松手后500ms隐藏气泡，Web支持Enter/空格激活 |
| 定位请求 | 受控值或程序方法 | v-model、scrollTo保留最后一次请求；布局未就绪、异步数据、隐藏恢复及重复定位均由组件处理；状态回写不产生新的定位请求，手动滚动恢复实际分组同步 |
| 标准内容与选择 | 标准行与内容插槽 | 默认主副文字、图片及复选框；默认行与item插槽统一处理点击、禁用和不可变选择回写，section插槽接管整组内容 |
| 逐组定制 | 分段字号、背景和标题内容 | group.titleStyle/titleTextStyle覆盖全局，anchor定制内容；同一原生段头负责普通展示和吸顶 |
默认项逐行参与列表复用；section 插槽以整组为一个列表项，适合网格或少量自定义内容。大量数据优先使用默认项或 item 插槽，避免将数千项合并进单个 section 插槽。列表复用时，插槽中的业务状态应与数据绑定；数据项可提供稳定 id 用于更新识别。
长列表渲染由平台列表负责：App复用列表项；Web/微信首窗先按估算布局输出缓冲项，再由实际测量校准；按可见窗口保留上下缓冲，屏外高度占位，实际渲染项高度自动缓存；异步内容变高时自动更新。兼容表表示支持范围，不替代目标设备的帧率、内存和系统字号验收。