xtf-index-bar

组件说明

xtf-index-bar 是索引栏组件，提供侧边字母索引导航和滚动联动。配合 xtf-index-anchor 使用，支持吸顶锚点和触摸滑动选择，适用于通讯录、城市选择和分类列表等场景。

---

基础用法

1. 基础用法

通过 indexList 设置索引列表，配合 xtf-index-anchor 使用：

<template>
  <xtf-index-bar :index-list="indexList" height="100vh" @select="onSelect" @change="onChange">
    <xtf-index-anchor v-for="letter in indexList" :key="letter" :index="letter">
      <xtf-cell v-for="name in getNameList(letter)" :key="name" :title="name" />
    </xtf-index-anchor>
  </xtf-index-bar>
</template>

<script>
export default {
  data() {
    return {
      indexList: ['A', 'B', 'C', 'D', 'E'],
      nameMap: {
        A: ['安琪', '艾伦'],
        B: ['白雪', '白云'],
        C: ['陈明', '程程'],
        D: ['杜鹃', '丁一'],
        E: ['恩熙']
      }
    }
  },
  methods: {
    getNameList(letter) {
      return this.nameMap[letter] || []
    },
    onSelect({ index, name }) {
      console.log('选择:', index, name)
    },
    onChange({ index, name }) {
      console.log('切换:', index, name)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
sticky	Boolean	true	是否吸顶	吸顶
stickyOffsetTop	Number	0	吸顶偏移(px)	吸顶
highlightColor	String	''	高亮颜色	样式
indexList	Array	[]	索引字符列表	索引
zIndex	Number	1	层级	层级
height	String | Number	'100%'	滚动区域高度	布局
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
select	选择索引时触发	(index)	选中的索引字符
change	当前索引变化时触发	(index)	当前索引字符

源码实际传参：select 与 change 均为 { index, name }。公开方法 scrollTo(index) 可定位索引；内容锚点的 id 必须为 xtf-index-anchor- 加索引字符。sticky 与 stickyOffsetTop 当前未参与滚动计算。

2. 外观配置

<template>
  <xtf-index-bar
    :index-list="letters"
    height="500rpx"
    sidebar-background="#ffffff"
    :sidebar-padding="8"
    :sidebar-item-size="40"
  >
    <xtf-index-anchor v-for="letter in letters" :key="letter" :index="letter">
      <xtf-cell :title="letter + ' 组联系人'" />
    </xtf-index-anchor>
  </xtf-index-bar>
</template>

<script>
export default {
  data() {
    return { letters: ['A', 'B', 'C'] }
  }
}
</script>

3. 方法调用

<template>
  <view>
    <xtf-button label="定位 B" @click="scrollToB" />
    <xtf-index-bar ref="bar" :index-list="letters" height="300rpx">
      <xtf-index-anchor v-for="letter in letters" :key="letter" :index="letter">
        <xtf-cell :title="letter + ' 组内容'" />
      </xtf-index-anchor>
    </xtf-index-bar>
  </view>
</template>

<script>
export default {
  data() {
    return { letters: ['A', 'B'] }
  },
  methods: {
    scrollToB() {
      this.$refs.bar.scrollTo(1)
    }
  }
}
</script>

---

插槽

插槽名称	说明
default	滚动内容区

---

主题说明

• 侧边栏使用半透明背景和圆角
• 触摸提示使用大号字母浮层
• 高亮项使用主题色

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。