更新记录

1.0.1（2026-04-30） 下载此版本

• 更新文档

1.0.0（2026-04-30） 下载此版本

• 支持 uni-index-bar 组件

平台兼容性

uni-app x(5.0)

介绍

本组件以竖排方式显示字母索引，常悬浮或固定于列表右侧，用户通过点击或滑动索引条上的字母索引，触发 select 事件。在该事件中通过代码驱动指定的列表滚动到该字母索引所在的位置。

本组件为绝对定位，默认垂直居中于父容器右侧。

本组件不包括 list-view 组件，需要配合 list-view 使用。list-view 中需要有对应索引的 list-item，且这些 list-item 需要有 id 属性，可以通过 scroll-into-view 属性或 scrollTop 属性跳转。

本组件包括一个指示器（indicator）子组件。当用户手指触摸在索引条上的某个字母时，在触摸的字母左边悬浮显示一个水滴形气泡，箭头指向当前触摸的字母。

Tips

• 该组件在微信小程序端从 hx 5.08 起开始支持

基本用法

<view style="flex: 1; position: relative;">
  <list-view ref="listRef" style="flex: 1;">
    <!-- 列表内容 -->
  </list-view>
  <uni-index-bar @select=""></uni-index-bar>
</view>

const  = (index: string) => {
  // 处理索引选择，滚动列表到对应位置
}

事件

外部样式类

示例

自定义索引

<uni-index-bar :indexs="'☆\nA\nB\nC\n#'" @select=""></uni-index-bar>

自定义样式

<uni-index-bar
  indicator-view-class="custom-indicator"
  indicator-text-class="custom-indicator-text"
  style="color: aqua;"
  @select="">
</uni-index-bar>

.custom-indicator {
  background-color: #007aff;
}
.custom-indicator-text {
  color: #ffff00;
}

配合 list-view 使用

<view style="flex: 1; position: relative;">
  <list-view ref="listRef" style="flex: 1;" :scroll-into-view="indexViewID">
    <template v-for="group in cityGroups" :key="group.index">
      <list-item :id="'idx-' + group.index" type="header">
        <view class="group-header">
          <text>{{ group.index }}</text>
        </view>
      </list-item>
      <list-item v-for="city in group.cities" :key="city.id" type="city">
        <view class="city-item">
          <text>{{ city.name }}</text>
        </view>
      </list-item>
    </template>
  </list-view>
  <uni-index-bar :indexs="indexList" @select=""></uni-index-bar>
</view>

const indexList = cityGroups.map((g): string => g.index).join('\n')
const indexViewID = ref("")

const  = (index: string) => {
  indexViewID.value = 'idx-' + index
}